klasse ara::crypto::cryp::HashFunctionCtx

De methode CalculateHashDigest voert een synchrone one-shot-berekening van een cryptografische hashwaarde uit en schrijft het resultaat in de bereitgestelde uitvoerbuffer [SWS_CRYPT_50060]. Als parameters worden het te verwerken invoerbericht data, de doelbuffer digest evenals optioneel een initialisatievector iv meegegeven. Bij succesvolle uitvoering levert de functie via het resultaatobject ara::core::Result<std::size_t> het werkelijke aantal geschreven digest-bytes terug [SWS_CRYPT_50060].

Foutafhandeling

Mislukt de berekening, dan garandeert de interface rollback-semantiek [SWS_CRYPT_50060]. De volgende foutcodes kunnen in het resultaat zijn opgenomen:

• ara::crypto::CryptoErrc::kInvalidInputSize: De grootte van de meegegeven gegevens of van de initialisatievector wordt niet ondersteund [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported: De single-call-berekening wordt niet ondersteund door de context, of de overdracht van de initialisatievector past niet bij de configuratie van de context (IV vereist, maar ontbreekt, of IV meegegeven hoewel niet ondersteund) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity: De capaciteit van de uitvoerbuffer digest volstaat niet voor de berekende digest [SWS_CRYPT_50060].

Gelijktijdigheid en wisselwerking

De functie is gedeclareerd als exceptieveilig (exception safe) en thread-veilig (thread-safe) [SWS_CRYPT_50060]. Om fouten betreffende ontoelaatbare invoerlengtes vooraf te voorkomen, kan de voor een enkele aanroep maximaal toelaatbare buffergrootte van de context via GetMaximumChunkSize worden bepaald [SWS_CRYPT_50062].

Gebruik

De methode Cancel() dient voor het gericht afbreken van een lopende streamingoperatie die eerder via de methode Start() is gestart en nog niet regulier is voltooid [SWS_CRYPT_50058]. De aanroep geschiedt synchroon en parameterloos op een instantie van ara::crypto::cryp::HashFunctionCtx uit het headerbestand ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. Bij een succesvolle uitvoering retourneert de operatie een lege ara::core::Result<void> [SWS_CRYPT_50058].

Foutafhandeling

Treedt er tijdens de uitvoering een probleem op, dan bevat de geretourneerde ara::core::Result een bijbehorende foutwaarde [SWS_CRYPT_50058]. Werd de verwerking vóór de aanroep van Cancel() niet geïnitieerd door Start(), dan mislukt het afbreken en retourneert deze de specifieke foutcode ara::crypto::CryptoErrc::kProcessingNotStarted met rollback-semantiek [SWS_CRYPT_50058].

Gelijktijdigheid en beperkingen

De interface is gedefinieerd als thread-safe en exception safe en gedeclareerd met noexcept [SWS_CRYPT_50058]. Als essentiële functionele randvoorwaarde geldt dat de gegevensverwerking zich in een actieve toestand moet bevinden die tot stand is gebracht door een voorafgaande Start()-aanroep [SWS_CRYPT_50058].

Samenspel

Het door Cancel() geïmplementeerde patroon is gestandaardiseerd over diverse streamingcontexten van de cryptostack heen. Een exact overeenkomende semantiek en foutsignalering vertonen ook de contexten VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] en EncryptorPublicCtx [SWS_CRYPT_50089].

De methode Compare van de klasse ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) vergelijkt grootte en inhoud van een vooraf berekende hash-digest synchroon met een verwachte referentiewaarde. De gewenste waarde wordt doorgegeven via de parameter expected van het type ReadOnlyMemRegion. Bij succes retourneert de functie een ara::core::Result<bool> die precies dan true bevat wanneer de verwachte bytereeks identiek is aan de berekende digest.

Voorwaarde voor de aanroep is dat de digest-berekening vooraf met de methode Finish() is afgesloten. Is dit niet het geval, dan mislukt de aanroep en levert deze de fout ara::crypto::CryptoErrc::kProcessingNotFinished op met rollback-semantiek ([SWS_CRYPT_50154]). Interpretatie: Een afwijkende lengte of een ongelijke inhoud van expected leidt vermoedelijk niet tot een foutcode, maar tot een reguliere false in het resultaatobject. Vraag Q-fdd0ecaec22f6985 (open)

Wat betreft gelijktijdigheid is de methode gespecificeerd als thread-safe en exception safe ([SWS_CRYPT_50154]). Ze werpt vanwege de declaratie als noexcept geen C++-exceptions op.

In verwante cryptocontexten wordt hetzelfde controlepatroon toegepast: Voor Message Authentication Codes vergelijkt ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) grootte en inhoud van de berekende MAC-waarde, terwijl CompareSubspan ([SWS_CRYPT_50028]) de meest significante bits controleert. Beide methoden vereisen eveneens een vooraf beëindigde berekening.

De methode [SWS_CRYPT_50064] van de klasse ara::crypto::cryp::HashFunctionCtx schrijft de actuele toestand van een hash-context synchroon naar de meegegeven uitvoerbuffer contextState van het type ReadWriteMem Region. Dit stelt applicaties in staat om een lopende cryptografische hash-bewerking te onderbreken en op een later tijdstip weer te hervatten. Bij een succesvolle uitvoering levert de aanroep een leeg ara::core::Result<void> op.

Interactie en bufferdimensionering

Om geheugenfouten te voorkomen, moet de dwingend benodigde buffergrootte in bytes vooraf worden opgevraagd via de functie [SWS_CRYPT_50063]. De geëxporteerde toestand kan later met behulp van [SWS_CRYPT_50065] weer in een hash-context worden ingelezen. Voorwaarde hiervoor is dat de doelcontext dezelfde AlgorithmId vertoont en door dezelfde Crypto Provider wordt bereitgesteld als de oorspronkelijke context. Bij het importeren wordt een eventueel bestaande rekentoestand volledig overschreven.

Foutafhandeling

Mislukt de bewerking, dan wordt een fout geretourneerd in het ara::core::Result. De volgende foutcodes uit ara::crypto::CryptoErrc zijn gespecificeerd:

• ara::crypto::CryptoErrc::kUnsupported: De concrete context ondersteunt het exporteren of importeren van toestanden niet.
• ara::crypto::CryptoErrc::kInsufficientCapacity: De capaciteit van de meegegeven buffer contextState is niet toereikend om de toestand op te nemen.

Voor beide foutgevallen is een rollback-semantiek gedefinieerd, zodat de toestand van het object ongewijzigd blijft.

Gelijktijdigheid en uitvoeringsveiligheid

De interface is gedeclareerd als const en noexcept. Conform de specificatie is de aanroep zowel thread-safe als exception-safe.

Gebruik

De synchrone methode Finish() sluit de berekening van een hashwaarde in ara::crypto::cryp::HashFunctionCtx af [SWS_CRYPT_21115]. De parameterloze aanroep levert een ara::core::Result<void> op, die de succesvolle afronding signaleert of een fout inkapselt [SWS_CRYPT_21115]. De interface is gedeclareerd als noexcept en gespecificeerd als exceptieveilig (exception safe) en thread-safe (thread-safe) [SWS_CRYPT_21115].

Foutafhandeling en gelijktijdigheid

Werd de hashberekening voorafgaand aan de aanroep niet succesvol gestart, dan mislukt de methode met de fout ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_21115]. Voor dit foutgeval is een rollback-semantiek gedefinieerd, zodat aanroepers vóór de finalisatie strikt moeten letten op een correct gestarte context [SWS_CRYPT_21115].

Samenspel

Na een succesvolle aanroep van Finish() wordt de berekende hash-digest doorgaans met GetDigest() overgedragen naar een beschikbaar gestelde buffer [SWS_CRYPT_21116], [SWS_CRYPT_50059]. Ter afbakening dient GetIntermediateDigest(): deze functie levert dezelfde hashwaarde op als de opeenvolging van Finish() en GetDigest(), maar staat daarna de doorgifte van verdere gegevens toe [SWS_CRYPT_50059]. Interpretatie: Na de aanroep van Finish() is de berekening vermoedelijk definitief voltooid en accepteert de context geen aanvullende gegevens meer. Vraag Q-f4daf29364f45fd5 (open) Toegestane buffergroottes voor verwerkingsstappen in de context kunnen via GetMaximumChunkSize() worden opgevraagd [SWS_CRYPT_50062].

De methode ImportContextState van de klasse ara::crypto::cryp::HashFunctionCtx (gedefinieerd in ara/crypto/cryp/hash_function_ctx.h) dient ertoe de interne toestand van een hash-context te herstellen vanuit een meegegeven buffer en daarmee een eerder onderbroken hash-bewerking voort te zetten [SWS_CRYPT_50065]. Een eventueel actieve berekeningstoestand van de huidige context wordt daarbij volledig vervangen door de geïmporteerde toestand [SWS_CRYPT_50065].

Aanroep en randvoorwaarden

De synchrone aanroep vindt plaats via de signatuur ImportContextState(ReadOnlyMem Region contextState) noexcept en retourneert een ara::core::Result<void> [SWS_CRYPT_50065]. Voor de parameter contextState gelden de volgende dwingende vereisten:

• De databuffer moet vooraf met de methode ExportContextState() zijn geëxporteerd uit een instantie van HashFunctionCtx [SWS_CRYPT_50065].
• De broncontext moet dezelfde AlgorithmId hebben bezeten en door dezelfde Crypto Provider zijn geleverd als de doelcontext [SWS_CRYPT_50065].

Foutafhandeling en gelijktijdigheid

In het geval van een fout wordt een foutcode met rollback-semantiek geretourneerd, zodat de bestaande toestand van de context bij mislukking ongewijzigd blijft [SWS_CRYPT_50065]:

• ara::crypto::CryptoErrc::kInvalidArgument: Het argument contextState bevat ongeldige gegevens [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported: De specifieke context ondersteunt het exporteren en importeren van contexttoestanden niet [SWS_CRYPT_50065].

De bewerking is gespecificeerd als thread-safe en exception safe [SWS_CRYPT_50065].

De methode Start() van de interface ara::crypto::cryp::HashFunctionCtx initialiseert de context voor de stapsgewijze berekening van een hashwaarde zonder initialisatievector (IV) [SWS_CRYPT_50152]. Een hernieuwde aanroep breekt een eventueel reeds lopende hashberekening af en stelt de context in voor een nieuwe berekening [SWS_CRYPT_50152].

De functie is synchroon, accepteert geen parameters en retourneert een ara::core::Result<void> [SWS_CRYPT_50152]. Treedt bij de initialisatie een fout op, dan is de rollback-semantiek van kracht met de volgende specifieke foutcodes [SWS_CRYPT_50152]:

• ara::crypto::CryptoErrc::kUnsupported: De gebruikte hashfunctie verwacht dwingend een initialisatievector [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource: Een voor de operatie dwingend vereiste interne bron is bezet [SWS_CRYPT_50152].

Wat betreft gelijktijdigheid is de methode gespecificeerd als thread-safe en exception safe en gedeclareerd als noexcept [SWS_CRYPT_50152]. Na succesvolle initialisatie kunnen berichtdelen sequentieel worden ingevoerd via de methode Update() van de context [SWS_CRYPT_21113]. Aangezien de aanroep lopende berekeningen afbreekt, dient de functie in de praktijk vermoedelijk ook als resetmechanisme vóór een herstart. Vraag Q-9c369489a6c6e8cb (open)

Gebruik

De functie Start van de interface ara::crypto::cryp::HashFunctionCtx initialiseert de context voor de berekening van een hash-digest met behulp van een initialisatievector (IV) [SWS_CRYPT_50153]. Als parameter wordt de initialisatievector iv via een ReadOnlyMemRegion doorgegeven [SWS_CRYPT_50153]. De synchrone aanroep retourneert een ara::core::Result<void>, die bij succes geen retourwaarde bevat [SWS_CRYPT_50153]. Een aanroep breekt bovendien een eventueel al lopende hashberekening op deze context af [SWS_CRYPT_50153].

Foutafhandeling

Als er bij de initialisatie een fout optreedt, wordt een bijbehorende foutcode geretourneerd, waarbij voor alle foutgevallen een rollback-semantiek wordt gegarandeerd [SWS_CRYPT_50153]:

• ara::crypto::CryptoErrc::kInvalidInputSize: De grootte van de verstrekte initialisatievector wordt niet ondersteund [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported: De onderliggende hashfunctie gebruikt geen initialisatievector [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource: Een voor de initialisatie benodigde bron is bezet [SWS_CRYPT_50153].

Gelijktijdigheid en wisselwerking

De interface is gedeclareerd als noexcept en gespecificeerd als thread-safe en exception-safe [SWS_CRYPT_50153]. In de typische flow vormt de aanroep de voorwaarde voor de daaropvolgende stapsgewijze verwerking van het invoerbericht via de methode Update [SWS_CRYPT_21113].

De synchrone methode Update dient in [SWS_CRYPT_21113] voor het incrementeel bijwerken van een lopende hashberekeningscontext (ara::crypto::cryp::HashFunctionCtx). Via de parameter data (ReadOnlyMemRegion) wordt een deel van het te verwerken invoerbericht doorgegeven. De functie retourneert een ara::core::Result<void>, die bij succes leeg is of een overeenkomstige foutcode inkapselt.

Wat betreft het foutgedrag biedt de methode rollback-semantiek bij twee specifieke fouttoestanden:

• ara::crypto::CryptoErrc::kProcessingNotStarted: de berekening is vooraf niet geïnitieerd door een aanroep van de methode Start() [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize: de grootte van de meegegeven gegevens wordt niet ondersteund door de context [SWS_CRYPT_21113].

Voor de aanroepcontext gelden duidelijke volgorde- en groottevoorwaarden: vóór de gegevensoverdracht moet de hashoperatie zijn geïnitialiseerd [SWS_CRYPT_21113]. Om kInvalidInputSize te vermijden, kan de maximaal toegestane blokgrootte voor een enkele Update-aanroep vooraf worden vastgesteld via GetMaximumChunkSize [SWS_CRYPT_50062]. Conform de specificatie is de functie gedeclareerd als uitzonderingsveilig (exception safe) en thread-veilig (thread-safe) [SWS_CRYPT_21113].

In samenspel met andere interfaces bestaat binnen HashFunctionCtx een overbelasting voor het doorgeven van sleutelobjecten via Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. Na het toevoeren van alle datablokken vindt de finalisering van de controlesom vermoedelijk plaats via Finish() [SWS_CRYPT_50062]. Vraag Q-dcac20f353ca55f4 (open)

De synchrone methode Update dient er in [SWS_CRYPT_50057] voor om de context van een hashwaarde-berekening in ara::crypto::cryp::HashFunctionCtx stapsgewijs uit te breiden met een nieuw berichtgedeelte in de vorm van een sleutelobject. Als parameter wordt een smart pointer naar het sleutelobject (CryptoObject::Sptr key) doorgegeven. De aanroep levert als retourwaarde een ara::core::Result<void> op, die bij succesvolle verwerking leeg is of bij een fout een overeenkomstige foutcode inkapselt [SWS_CRYPT_50057].

Als volgordevoorwaarde geldt dat de berekening vooraf dwingend moet zijn geïnitieerd door de aanroep van Start(); anders wordt de fout ProcessingNotStarted gemeld [SWS_CRYPT_50057]. Verdere specifieke foutgevallen omvatten (telkens met rollback-semantiek) [SWS_CRYPT_50057]:

• ara::crypto::CryptoErrc::kUnsupported, wanneer de hash-context het hashen van sleutels over het algemeen niet ondersteunt,
• ara::crypto::CryptoErrc::kIncompatibleObject, indien het doorgegeven sleutelobject niet compatibel is met de context,
• ara::crypto::CryptoErrc::kUsageViolation, voor zover het toegestane gebruik van de sleutel niet kAllowHash Calculation omvat,
• ara::crypto::CryptoErrc::kInvalidInputSize, wanneer de gegevensgrootte van de doorgegeven sleutel niet wordt ondersteund.

De methode is gedeclareerd als thread-safe en als exception safe (noexcept) [SWS_CRYPT_50057]. In wisselwerking met andere interfaces van de module kan de maximaal toegestane buffergrootte voor afzonderlijke Update-aanroepen via GetMaximumChunkSize() worden bepaald [SWS_CRYPT_50062]. Voor reguliere berichtdelen zonder sleutelobject bestaat in HashFunctionCtx parallel de overload Update(ReadOnlyMemRegion data) [SWS_CRYPT_21113].