klasse ara::crypto::cryp::SignerPrivateCtx

De methode Cancel() dient voor het synchroon afbreken van een lopende, nog niet voltooide streamingoperatie binnen de klasse ara::crypto::cryp::SignerPrivateCtx, die eerder werd geïnitieerd door een aanroep van Start() [SWS_CRYPT_50041]. De zuiver virtuele interface virtual ara::core::Result<void> Cancel() noexcept = 0; is gedeclareerd in header ara/crypto/cryp/signer_private_ctx.h, accepteert geen invoerparameters en signaleert de succesvolle afbreking via een lege ara::core::Result<void> [SWS_CRYPT_50041]. Voor de aanroeper is de methode gespecificeerd als uitzonderingsveilig (exception safe) en concurrent thread-safe [SWS_CRYPT_50041].

Met betrekking tot de aanroepvolgorde en foutafhandeling vereist Cancel() dwingend een actieve verwerking: als de gegevensverwerking niet eerder is ingeleid door een aanroep van de methode Start(), mislukt het afbreken en retourneert deze de foutcode ara::crypto::CryptoErrc::kProcessingNotStarted met gedefinieerde rollback-semantiek [SWS_CRYPT_50041]. Interpretatie: na een succesvolle aanroep van Cancel() keert de context vermoedelijk terug naar een niet-gestarte basistoestand, zodat een nieuw handtekening- of streamingproces kan worden gestart. Vraag Q-348fb3ae43e424c9 (open)

Het ontwerp volgt een uniform principe voor alle streamingoperaties in de cryptomodule. Volledig identieke signaturen en foutsemantieken bestaan voor verwante contexten zoals VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SymmetricCipherCtx [SWS_CRYPT_50046], HashFunctionCtx [SWS_CRYPT_50058], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] en EncryptorPublicCtx [SWS_CRYPT_50089].

Gebruik

De methode ara::crypto::cryp::SignerPrivateCtx::Finish voltooit de handtekeninggeneratie synchroon en schrijft de berekende handtekening direct naar de bereitgestelde uitvoerbuffer signature [SWS_CRYPT_50040]. De functie verwacht als overdrachtsparameters het beschrijfbare geheugengebied signature (type ReadWriteMemRegion) en het gewenste formaat signatureFormat (type FormatId) [SWS_CRYPT_50040]. Als retourwaarde levert ara::core::Result<size_t> de werkelijke bytegrootte van de geschreven handtekeninggegevens; deze hoeveelheid gegevens mag kleiner zijn dan de capaciteit van de doelbuffer [SWS_CRYPT_50040].

Foutafhandeling

Voor alle optredende foutgevallen is een rollback-semantiek gespecificeerd [SWS_CRYPT_50040]. De volgende foutcodes kunnen via het resultaat worden geretourneerd:

• ara::crypto::CryptoErrc::kProcessingNotStarted: de handtekeninggeneratie is vooraf niet met succes gestart [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kInsufficientCapacity: de capaciteit van de doorgegeven uitvoerbuffer signature is te gering [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kUnsupportedFormat: de waarde van signatureFormat is onbekend of wordt niet ondersteund [SWS_CRYPT_50040].

Gelijktijdigheid en beperkingen

De methode is gespecificeerd als thread-safe en exception safe en mag geen excepties werpen (noexcept) [SWS_CRYPT_50040]. Een geldige aanroep vereist dwingend dat het generatieproces in de context vooraf met succes is geïnitieerd [SWS_CRYPT_50040].

Samenspel

Het directe functionele tegenstuk voor de verificatie van de gegenereerde handtekening vormt de methode ara::crypto::cryp::VerifierPublicCtx::Finish [SWS_CRYPT_50022]. Vergeleken met contexten voor hash- of MAC-berekeningen, waarbij Finish() alleen de berekening afrondt en het tussen- of eindresultaat afzonderlijk wordt opgehaald [SWS_CRYPT_21115] [SWS_CRYPT_21116], schrijft SignerPrivateCtx::Finish de handtekening direct naar de buffer [SWS_CRYPT_50040].

Gebruik

De virtuele methode SetKey van de klasse ara::crypto::cryp::SignerPrivateCtx (#include "ara/crypto/cryp/signer_private_ctx.h") configureert de ondertekeningscontext voor het gebruik van een verstrekte privésleutel [SWS_CRYPT_23515]. Als parameter wordt key van het type PrivateKey::Sptr doorgegeven als bronsleutelobject [SWS_CRYPT_23515]. De methode wordt synchroon uitgevoerd en retourneert een ara::core::Result<void>, dat in geval van succes leeg is of bij een fout de opgetreden foutcode transporteert [SWS_CRYPT_23515].

Foutafhandeling

Als er tijdens de configuratie een fout optreedt, treedt een rollback-semantiek in werking [SWS_CRYPT_23515]. De volgende foutcodes zijn gespecificeerd:

• ara::crypto::CryptoErrc::kIncompatibleObject: Het doorgegeven sleutelobject is incompatibel met de huidige context [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUsageViolation: Het toegestane gebruik van de sleutel omvat niet het genereren van handtekeningen (kAllowSig Generation) [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUnsupported: De specifieke context ondersteunt uitsluitend het instellen via een KeySlot [SWS_CRYPT_23515].

Gelijktijdigheid en beperkingen

De interface is gedeclareerd als noexcept en volgens de specificatie geclassificeerd als zowel exceptieveilig („exception safe”) als thread-veilig („thread-safe”) [SWS_CRYPT_23515].

Samenspel

In SignerPrivateCtx bestaat als alternatief de overbelasting SetKey(KeySlot::Sptr), die de context zodanig configureert dat de in een KeySlot opgeslagen sleutel pas op het starttijdstip van de handtekeningberekening wordt gebruikt [SWS_CRYPT_50036]. Voor de controle van handtekeningen dient aan verificatiezijde de functionele tegenhanger SetKey met PublicKey::Sptr binnen ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_24115].

Gebruik

De methode SetKey configureert de ondertekeningscontext [SWS_CRYPT_50036] voor het gebruik van een sleutel die zich in de doorgegeven KeySlot::Sptr bevindt. De sleutel wordt pas geraadpleegd op het moment waarop de feitelijke handtekeningberekening wordt gestart [SWS_CRYPT_50036]. De aanroep vindt synchroon plaats, is gedeclareerd als noexcept en levert een ara::core::Result<void> op [SWS_CRYPT_50036].

Foutafhandeling

Mislukt de configuratie, dan wordt een fout in het retourobject doorgegeven, waarbij rollback-semantiek geldt [SWS_CRYPT_50036]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Treedt op wanneer de bereitgestelde keySlot niet compatibel is met deze ondertekeningscontext [SWS_CRYPT_50036].
• ara::crypto::CryptoErrc::kUnsupported: Wordt gemeld indien de context uitsluitend het rechtstreeks instellen van een PrivateKey ondersteunt [SWS_CRYPT_50036].

Gelijktijdigheid en wisselwerking

De interface behoort tot de klasse ara::crypto::cryp::SignerPrivateCtx en is gespecificeerd als thread-safe evenals exception-safe [SWS_CRYPT_50036]. Naast deze slotgebaseerde variant biedt SignerPrivateCtx ook een overbelasting die rechtstreeks een PrivateKey::Sptr-object accepteert [SWS_CRYPT_23515]. Analoge slotkoppelingen bestaan voor overige cryptografische contexten, bijvoorbeeld voor handtekeningcontrole met KeySlot in VerifierPublicCtx [SWS_CRYPT_50018] of voor sleutelafleiding in KeyDerivationFunctionCtx [SWS_CRYPT_50010].

De methode Sign ondertekent een bericht synchroon in één enkele stap conform [SWS_CRYPT_23512]. Deze accepteert het te ondertekenen invoerbericht (message), de doelbuffer (signature), het gewenste handtekeningformaat (signatureFormat) en optioneel een contextwaarde (context). Bij succes levert de functie via ara::core::Result<std::size_t> de daadwerkelijke bytegrootte van de gegenereerde handtekening terug, die kleiner kan zijn dan de capaciteit van de doelbuffer [SWS_CRYPT_23512].

Wat betreft gelijktijdigheid en exception-veiligheid is de methode gedeclareerd als noexcept, geldt deze als exception safe en is deze expliciet gespecificeerd als thread-safe [SWS_CRYPT_23512].

Voorafgaand aan de aanroep moet de context correct zijn geïnitialiseerd met een sleutelwaarde; anders wordt UninitializedContext gemeld [SWS_CRYPT_23512]. Wat betreft de invoerlengte staat Sign in samenspel met [SWS_CRYPT_50042]: via GetMaximumChunkSize kan de maximaal ondersteunde buffergrootte voor de éénstapsverwerking worden bepaald om fouten zoals ara::crypto::CryptoErrc::kInvalidInputSize te voorkomen [SWS_CRYPT_23512] [SWS_CRYPT_50042].

De foutafhandeling voorziet in rollback-semantiek voor specifieke foutcodes [SWS_CRYPT_23512]:

• ara::crypto::CryptoErrc::kInsufficientCapacity: De uitvoerbuffer signature is te klein.
• ara::crypto::CryptoErrc::kUnsupported: De éénstapsverwerking wordt niet ondersteund, of de contextopgave context voldoet niet aan de vereisten.
• ara::crypto::CryptoErrc::kUnsupportedFormat: Het opgegeven FormatId is onbekend of wordt niet ondersteund.
• ara::crypto::CryptoErrc::kUsageViolation: Het toegestane sleutelgebruik bevat niet kAllowSig Generation.
• ara::crypto::CryptoErrc::kEmptyKeySlot of ara::crypto::CryptoErrc::kBusyResource: De geconfigureerde KeySlot is leeg resp. een vereiste resource is bezet.

De parameterloze methode Start initialiseert een context van de klasse ara::crypto::cryp::SignerPrivateCtx voor een nieuwe handtekeninggeneratie [SWS_CRYPT_50037]. De aanroep vindt synchroon plaats, is gedeclareerd als noexcept en levert een lege ara::core::Result<void> op bij succesvolle initialisatie of een foutcode in geval van een fout [SWS_CRYPT_50037].

In geval van een fout ondersteunt de bewerking rollback-semantiek [SWS_CRYPT_50037]. Tot de gedefinieerde foutoorzaken uit ara::crypto::CryptoErrc behoren:

• kUninitializedContext: De context is vooraf niet geïnitialiseerd door het bereitstellen van een sleutel [SWS_CRYPT_50037].
• kEmptyKeySlot: Een geconfigureerd sleutelslot is momenteel leeg [SWS_CRYPT_50037].
• kUsageViolation: De machtigingen van de toegewezen sleutel omvatten niet kAllowSigGeneration [SWS_CRYPT_50037].
• kBusyResource: Een voor de bewerking benodigde resource is bezet [SWS_CRYPT_50037].
• kUnsupported: De context ondersteunt geen streaming of het handtekeningalgoritme vereist dwingend de opgave van een contextwaarde [SWS_CRYPT_50037].

Volgens de specificatie is de functie thread-safe evenals exception safe [SWS_CRYPT_50037]. Vereist het algoritme een specifieke contextwaarde, dan moet als alternatief de overbelaste variant Start(ReadOnlyMemRegion context) worden gebruikt [SWS_CRYPT_50038]. Na een succesvolle aanroep van Start kunnen te ondertekenen berichtdelen doorlopend via Update worden verwerkt [SWS_CRYPT_50039].

De methode Start dient voor de synchrone initialisatie van de context ara::crypto::cryp::SignerPrivateCtx voor een nieuwe handtekeninggeneratie onder het bereitstellen van een contextwaarde ([SWS_CRYPT_50038]). Ze accepteert de parameter context van het type ReadOnlyMemRegion en levert een ara::core::Result<void> op. De functie is gespecificeerd als noexcept=0, exception-safe en gedeclareerd als thread-safe ([SWS_CRYPT_50038]).

In een foutgeval blijft de contexttoestand via een rollback-semantiek ongewijzigd ([SWS_CRYPT_50038]). Gespecificeerde foutoorzaken zijn:

• UninitializedContext: wanneer de context vooraf niet is geïnitialiseerd door het bereitstellen van een sleutel.
• ara::crypto::CryptoErrc::kUnsupported: indien de context geen streaming ondersteunt of het algoritme geen contextwaarde toestaat.
• ara::crypto::CryptoErrc::kInvalidInputSize: wanneer de buffergrootte van de doorgegeven contextwaarde ongeldig is.
• ara::crypto::CryptoErrc::kEmptyKeySlot: wanneer een geconfigureerd sleutelslot momenteel leeg is.
• ara::crypto::CryptoErrc::kUsageViolation: indien het toegestane gebruik van de sleutel niet de handtekeninggeneratie (kAllowSig Generation) omvat.
• ara::crypto::CryptoErrc::kBusyResource: indien een vereiste bron bezet is.

In het typische verwerkingsverloop worden de te ondertekenen gegevens na een geslaagde start vermoedelijk opeenvolgend via Update ([SWS_CRYPT_50039]) doorgegeven. Vraag Q-7b821391730c9d38 (open) Voor zover het cryptografische procedé geen contextwaarde vereist, staat als alternatief de parameterloze overload Start() gereed ([SWS_CRYPT_50037]).

De methode Update dient er in [SWS_CRYPT_50039] toe de interne toestand van een handtekeningberekening doorlopend uit te breiden met een volgend deel van het bericht. De aanroep vindt synchroon plaats en verwerkt het doorgegeven geheugengebied data van het type ReadOnlyMemRegion. Als resultaat levert de functie een ara::core::Result<void>, die bij een succesvolle verwerking geen waarde bevat of anders een foutcode inkapselt [SWS_CRYPT_50039].

In geval van een fout bezitten de retourwaarden een rollback-semantiek [SWS_CRYPT_50039]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Treedt op wanneer de handtekeningberekening niet vooraf door de aanroep van de methode Start() is geïnitieerd [SWS_CRYPT_50039].
• ara::crypto::CryptoErrc::kInvalidInputSize: Wordt gemeld indien de grootte van de bereitgestelde invoerdata niet door de context wordt ondersteund [SWS_CRYPT_50039].

Wat betreft concurrency en veiligheid is de methode gedeclareerd als thread-safe evenals exception safe [SWS_CRYPT_50039]. In samenhang met de ondertekeningscontext vereist de berekening dwingend dat het proces met Start() is gestart. De maximaal toelaatbare buffergrootte voor afzonderlijke aanroepen kan via GetMaximumChunkSize() worden opgevraagd [SWS_CRYPT_50042]; deze grenswaarde vormt vermoedelijk de bovengrens waarvan overschrijding tot kInvalidInputSize leidt. Vraag Q-cf204a853a730365 (open)