klasse ara::crypto::cryp::VerifierPublicCtx

Gebruik en semantiek

De methode Cancel() breekt een lopende streaming-operatie af die eerder door Start() is geïnitieerd en nog niet is voltooid [SWS_CRYPT_50023]. Deze is in de header ara/crypto/cryp/verifier_public_ctx.h gedefinieerd als pure virtual methode van de context ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023]. De aanroep geschiedt synchroon en zonder argumenten. Als retourwaarde dient een ara::core::Result<void>, die bij succes leeg is en het succesvol afbreken van de operatie bevestigt [SWS_CRYPT_50023].

Foutafhandeling

Indien de gegevensverwerking nog niet is gestart door de aanroep van de methode Start(), mislukt de afbreekoperatie. In dit scenario retourneert de functie een foutresultaat met de foutcode ara::crypto::CryptoErrc::kProcessingNotStarted onder waarborging van rollback-semantiek [SWS_CRYPT_50023].

Gelijktijdigheid en beperkingen

De specificatie wijst de methode aan als thread-safe en uitzonderingsveilig (exception safe) met de markering noexcept [SWS_CRYPT_50023]. Interpretatie: na het succesvol afbreken valt de context vermoedelijk weer terug naar de begintoestand van vóór de start van de verwerking, zodat een nieuwe streaming-bewerking kan worden begonnen. Vraag Q-d80d09c8a8311bbc (open)

Samenspel in de module crypt

Dit uniforme afbreekpatroon met identieke signatuur en foutafhandeling geldt consistent voor alle streaming-contexten van de module crypt:

• MessageAuthnCodeCtx voor Message Authentication Codes [SWS_CRYPT_50027],
• SignerPrivateCtx voor het genereren van digitale handtekeningen [SWS_CRYPT_50041],
• SymmetricCipherCtx voor symmetrische versleuteling en ontsleuteling [SWS_CRYPT_50046],
• HashFunctionCtx voor cryptografische hash-operaties [SWS_CRYPT_50058],
• DecryptorPrivateCtx voor asymmetrische ontsleuteling [SWS_CRYPT_50069],
• AuthCipherCtx voor geauthenticeerde cijfering [SWS_CRYPT_50077] alsook
• EncryptorPublicCtx voor asymmetrische versleuteling [SWS_CRYPT_50089].

De methode Finish in ara::crypto::cryp::VerifierPublicCtx rondt een controle van de signatuur af en levert het verificatieresultaat op [SWS_CRYPT_50022]. Zij accepteert via de invoerbuffer signature (type ReadOnlyMemRegion) de te controleren signatuur en via signatureFormat (type FormatId) het formaat daarvan [SWS_CRYPT_50022]. De aanroep geschiedt synchroon en is conform de specificatie thread-safe en exception-safe verklaard [SWS_CRYPT_50022].

Als retourwaarde dient een ara::core::Result<bool> [SWS_CRYPT_50022]: bij een geslaagde validatie van de handtekening bevat het resultaat true, bij een inhoudelijk ongeldige handtekening false. Treedt daarentegen een verwerkingsfout op, dan wordt een overeenkomstige foutcode geretourneerd [SWS_CRYPT_50022]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: de operatie is vooraf niet met succes gestart (rollback-semantiek) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidInputSize: de buffergrootte van signature is ongeldig (rollback-semantiek) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kUnsupportedFormat: het opgegeven formaat signatureFormat wordt niet ondersteund (rollback-semantiek) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidArgument: de handtekening voldoet niet aan het gespecificeerde formaat (rollback-semantiek) [SWS_CRYPT_50022].

In het cryptografische proces vormt deze functie het tegenstuk van de handtekeninggeneratie via ara::crypto::cryp::SignerPrivateCtx::Finish [SWS_CRYPT_50040], die een handtekening in een uitvoerbuffer schrijft. Alle gemelde fouten hebben rollback-semantiek [SWS_CRYPT_50022], zodat de contexttoestand bij een fout consistent blijft.

De methode SetKey configureert een instantie van VerifierPublicCtx voor het gebruik van een concrete openbare sleutel voor handtekeningverificatie ([SWS_CRYPT_24115]). Via de parameter key wordt een pointer van het type PublicKey::Sptr doorgegeven. De aanroep vindt synchroon plaats en retourneert een ara::core::Result<void>, die bij succes leeg is of een specifieke foutcode inkapselt.

De operatie is volgens de specificatie thread-safe en uitzonderingsveilig (exception safe) ontworpen ([SWS_CRYPT_24115]). Treedt er tijdens de sleutelbinding een fout op, dan geldt voor alle foutgevallen een rollback-semantiek, zodat de context in een consistente toestand blijft:

• CryptoErrc::kIncompatibleObject: de doorgegeven sleutel is incompatibel met de context voor handtekeningverificatie ([SWS_CRYPT_24115]).
• CryptoErrc::kUsageViolation: de machtigingen van de sleutel staan geen handtekeningverificatie toe (ontbreken van de gebruiksvlag voor handtekeningverificatie) ([SWS_CRYPT_24115]).
• ara::crypto::CryptoErrc::kUnsupported: de contextimplementatie ondersteunt uitsluitend het binden van een sleutel via een KeySlot ([SWS_CRYPT_24115]).

In de cryptografische workflow vormt SetKey de openbare tegenhanger van SignerPrivateCtx::SetKey ([SWS_CRYPT_23515]). Voor zover een context de directe sleuteloverdracht via PublicKey::Sptr niet toestaat of sleutels in beveiligde slots worden beheerd, is als alternatief de overload via KeySlot::Sptr beschikbaar ([SWS_CRYPT_50018]).

Gebruik

De methode SetKey van de klasse ara::crypto::cryp::VerifierPublicCtx configureert de verificatiecontext voor het gebruik van een sleutel die is opgeslagen in een meegegeven KeySlot [SWS_CRYPT_50018]. De sleutel wordt gebruikt op het moment dat de handtekeningverificatie wordt gestart [SWS_CRYPT_50018].

Als parameter dient een smart pointer keySlot van het type KeySlot::Sptr, die een openbare sleutel bevat [SWS_CRYPT_50018]. De functie werkt synchroon en retourneert een ara::core::Result<void> om een succesvolle voltooiing of fout aan te geven [SWS_CRYPT_50018].

Foutafhandeling en semantiek

De operatie is gespecificeerd als noexcept en exception safe [SWS_CRYPT_50018]. Als er een fout optreedt, treedt een rollback-semantiek in werking [SWS_CRYPT_50018]:

• ara::crypto::CryptoErrc::kIncompatibleObject: De geleverde KeySlot is incompatibel met deze context [SWS_CRYPT_50018].
• ara::crypto::CryptoErrc::kUnsupported: De context ondersteunt uitsluitend het direct instellen van een PublicKey [SWS_CRYPT_50018].

Gelijktijdigheid en wisselwerking

De methode is thread-safe gespecificeerd [SWS_CRYPT_50018]. Als alternatief voor de KeySlot biedt VerifierPublicCtx een overload om een PublicKey direct in te stellen [SWS_CRYPT_24115]. Een overeenkomstige sleutelconfiguratie via een KeySlot bestaat analoog ook in andere contexten zoals SignerPrivateCtx [SWS_CRYPT_50036] of MessageAuthnCodeCtx [SWS_CRYPT_50026].

Gebruik

De synchrone methode Start() van de interface ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_50019]) initialiseert de context voor een nieuwe cryptografische handtekeningcontrole in streamingbedrijf. De functie accepteert geen overdrachtparameters, is gedeclareerd als noexcept en retourneert een ara::core::Result<void>, die in geval van succes leeg is.

Foutafhandeling en rollback

Treedt bij de uitvoering een fout op, dan treedt de rollback-semantiek ([SWS_CRYPT_50019]) in werking, waardoor de context in een consistente toestand blijft. Mogelijke foutoorzaken zijn:

• UninitializedContext: Aan de context is vooraf geen cryptografische sleutel toegewezen.
• ara::crypto::CryptoErrc::kUsageViolation: De toegewezen sleutel is niet vrijgegeven voor de handtekeningcontrole (kAllowSig Verification).
• ara::crypto::CryptoErrc::kEmptyKeySlot: Een voor de verificatie geconfigureerde KeySlot is momenteel leeg.
• ara::crypto::CryptoErrc::kUnsupported: De context ondersteunt geen streaming of de procedure vereist dwingend een contextwaarde.
• ara::crypto::CryptoErrc::kBusyResource: Een voor de bewerking benodigde resource is momenteel bezet.

Gelijktijdigheid en wisselwerking

Hoewel de specificatie de methode als thread-safe aanmerkt ([SWS_CRYPT_50019]), zou een parallelle aanroep op dezelfde contextinstantie tijdens een lopende verificatie vermoedelijk de bestaande bewerking resetten of op bezette resources kunnen stranden. Vraag Q-af5e08ff9d905a29 (open)

Na succesvolle initialisatie worden de berichtdelen sequentieel via Update() ([SWS_CRYPT_50021]) doorgegeven. Een lopende streamingbewerking kan desgewenst voortijdig met Cancel() ([SWS_CRYPT_50023]) worden afgebroken. Indien het algoritme dwingend een contextwaarde vereist, moet in plaats daarvan de overbelaste functie Start(ReadOnlyMemRegion context) ([SWS_CRYPT_50020]) worden aangeroepen.

Gebruik

De functie Start initialiseert conform [SWS_CRYPT_50020] een verificatiecontext van de klasse ara::crypto::cryp::VerifierPublicCtx voor een nieuwe handtekeningcontrole. Als invoerparameter accepteert deze context van het type ReadOnlyMemRegion, die een applicatiespecifieke contextwaarde verstrekt. Als alternatief zonder contextgegevens bestaat de overbelasting [SWS_CRYPT_50019]. De retourwaarde is ara::core::Result<void>; interpretatie: Aangezien noch callbacks noch future-objecten zijn gedefinieerd, wordt de aanroep vermoedelijk zuiver synchroon afgehandeld. Vraag Q-4e10cdb1a4343a3a (open)

Foutafhandeling

In geval van een fout levert de functie een ara::core::Result met een passende foutcode uit ara::crypto::CryptoErrc, waarbij een rollback-semantiek is gespecificeerd [SWS_CRYPT_50020]:

• kUninitializedContext: De context is nog niet geïnitialiseerd door toewijzing van een sleutel.
• kEmptyKeySlot: Een geconfigureerde KeySlot is momenteel leeg.
• kUsageViolation: Het toegestane gebruik van de toegewezen sleutel omvat niet kAllowSigVerification.
• kInvalidInputSize: De buffergrootte van de doorgegeven contextwaarde is ongeldig voor het algoritme.
• kUnsupported: De context ondersteunt geen streaming of het algoritme ondersteunt het instellen van een contextwaarde niet.
• kBusyResource: Een vereiste resource is bezet.

Gelijktijdigheid en beperkingen

Conform [SWS_CRYPT_50020] is de methode geclassificeerd als thread-safe en exception-safe. Deze genereert geen excepties (noexcept).

Samenspel

Na succesvolle uitvoering van Start kan het invoerbericht via herhaalde aanroepen van Update stapsgewijs worden verzonden [SWS_CRYPT_50021]. Een lopend streamingproces dat door Start is gestart, kan indien nodig via Cancel voortijdig worden afgebroken [SWS_CRYPT_50023].

Gebruik

De methode Update() dient ertoe om de context voor handtekeningcontrole stapsgewijs bij te werken met een volgend deel van het invoerbericht [SWS_CRYPT_50021]. Als parameter wordt een geheugengebied data van het type ReadOnlyMemRegion doorgegeven. De functie retourneert een ara::core::Result<void>; interpretatie: Op grond van dit retourtype vindt de verwerking vermoedelijk synchroon plaats. Vraag Q-f98391030b3b4684 (open)

Foutafhandeling

In geval van een fout wordt een overeenkomstige foutcode met rollback-semantiek geretourneerd [SWS_CRYPT_50021]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: De handtekeningcontrole is niet vooraf geïnitieerd door aanroep van de methode Start() [SWS_CRYPT_50021].
• ara::crypto::CryptoErrc::kInvalidInputSize: De grootte van de verstrekte gegevens in data wordt niet ondersteund [SWS_CRYPT_50021].

Gelijktijdigheid en wisselwerking

De bewerking is in de specificatie geclassificeerd als thread-safe en exception safe [SWS_CRYPT_50021]. Voorafgaand aan de aanroep moet verplicht de initialisatie via Start() hebben plaatsgevonden [SWS_CRYPT_50021]. Om te voorkomen dat kInvalidInputSize optreedt, kan de maximaal toelaatbare buffergrootte voor afzonderlijke aanroepen via de methode GetMaximumChunkSize() van dezelfde context worden opgevraagd [SWS_CRYPT_50025]. De complementaire tegenhanger voor de berichtgewijze handtekeninggeneratie vormt Update() in SignerPrivateCtx [SWS_CRYPT_50039].

Gebruik

De methode Verify van de context ara::crypto::cryp::VerifierPublicCtx dient ertoe de handtekening van een gereedgezet bericht in een enkele aanroep te verifiëren [SWS_CRYPT_24112]. Als parameters worden de berichtbuffer message, de handtekening signature en het formaat signatureFormat doorgegeven [SWS_CRYPT_24112]. De retourwaarde ara::core::Result<bool> bevat bij een succesvolle controle true, bij niet-overeenkomen false of een foutcode [SWS_CRYPT_24112]. Interpretatie: Vanwege het synchrone resultaattype verloopt het controleproces vermoedelijk blokkerend in de aanroepende thread. Vraag Q-671054c6e2b581c6 (open)

Foutafhandeling en gelijktijdigheid

De functie is gespecificeerd als exception safe en thread-safe [SWS_CRYPT_24112]. In geval van een fout geldt voor de foutcodes een rollback-semantiek [SWS_CRYPT_24112]. Mogelijke foutoorzaken omvatten:

• UninitializedContext, wanneer de context niet met een sleutel is geïnitialiseerd [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kEmptyKeySlot bij een leeg sleutelslot of kUsageViolation, wanneer de sleutel het recht kAllowSig Verification ontbreekt [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kInvalidInputSize bij een ontoelaatbare buffergrootte [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kUnsupportedFormat of kInvalidArgument bij een onjuist of incompatibel handtekeningformaat [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kBusyResource, indien benodigde resources bezet zijn [SWS_CRYPT_24112].

Samenspel

De maximale buffergrootte voor afzonderlijke aanroepen kan via GetMaximumChunkSize() worden opgevraagd [SWS_CRYPT_50025]. Vereist het algoritme dwingend een contextwaarde, dan wordt ara::crypto::CryptoErrc::kUnsupported geretourneerd [SWS_CRYPT_24112]; in dit geval moet de overbelasting met extra context-parameter worden gekozen [SWS_CRYPT_50024]. Voor controles van Message Authentication Codes bestaat ter onderscheiding ara::crypto::cryp::MessageAuthnCodeCtx::Verify [SWS_CRYPT_50031].

De synchrone methode Verify controleert de digitale handtekening van een doorgegeven bericht met inachtneming van een door de gebruiker gedefinieerde contextwaarde in een enkele aanroep ([SWS_CRYPT_50024]). Als invoerparameters verwacht de methode de buffers message, context en signature telkens als ReadOnlyMemRegion, alsmede het formaat van de handtekening via signatureFormat ([SWS_CRYPT_50024]). De retourwaarde is een ara::core::Result<bool>: deze bevat true bij succesvolle verificatie, false bij een foutieve handtekening of een overeenkomstige foutcode ([SWS_CRYPT_50024]).

In geval van een fout treedt een rollback-semantiek in werking ([SWS_CRYPT_50024]). Specifieke foutcodes omvatten onder meer:

• UninitializedContext, wanneer de verificatiecontext nog niet is geïnitialiseerd met een sleutelwaarde ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kInvalidInputSize bij een ontoelaatbare buffergrootte ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupported, indien het gekozen handtekeningalgoritme het opgeven van een contextwaarde niet ondersteunt ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupportedFormat respectievelijk ara::crypto::CryptoErrc::kInvalidArgument, wanneer het opgegeven handtekeningformaat niet wordt ondersteund of de handtekening niet overeenkomt met het formaat ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUsageViolation, wanneer het toegestane sleutelgebruik niet kAllowSigVerification omvat, evenals ara::crypto::CryptoErrc::kEmptyKeySlot en ara::crypto::CryptoErrc::kBusyResource ([SWS_CRYPT_50024]).

De methode is gedeclareerd als const noexcept, geldt als uitzonderingsveilig en is gespecificeerd als thread-safe ([SWS_CRYPT_50024]). In samenspel met de context kan de maximale buffergrootte voor afzonderlijke aanroepen via GetMaximumChunkSize worden bepaald ([SWS_CRYPT_50025]). Voor verificaties zonder context is de alternatieve overbelasting van Verify beschikbaar ([SWS_CRYPT_24112]).