class ara::crypto::cryp::HashFunctionCtx

Die Methode CalculateHashDigest führt eine synchrone One-Shot-Berechnung eines kryptografischen Hash-Werts durch und schreibt das Ergebnis in den bereitgestellten Ausgabepuffer [SWS_CRYPT_50060]. Als Parameter werden die zu verarbeitende Eingabenachricht data, der Zielpuffer digest sowie optional ein Initialisierungsvektor iv übergeben. Bei erfolgreicher Ausführung liefert die Funktion über das Ergebnisobjekt ara::core::Result<std::size_t> die tatsächliche Anzahl der geschriebenen Digest-Bytes zurück [SWS_CRYPT_50060].

Fehlerbehandlung

Schlägt die Berechnung fehl, garantiert die Schnittstelle Rollback-Semantik [SWS_CRYPT_50060]. Folgende Fehlercodes können im Ergebnis enthalten sein:

• ara::crypto::CryptoErrc::kInvalidInputSize: Die Größe der übergebenen Daten oder des Initialisierungsvektors wird nicht unterstützt [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported: Die Single-Call-Berechnung wird vom Kontext nicht unterstützt, oder die Übergabe des Initialisierungsvektors passt nicht zur Konfiguration des Kontexts (IV erforderlich, aber fehlt, bzw. IV übergeben, obwohl nicht unterstützt) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity: Die Kapazität des Ausgabepuffers digest reicht für den berechneten Digest nicht aus [SWS_CRYPT_50060].

Nebenläufigkeit und Zusammenspiel

Die Funktion ist als ausnahmesicher (exception safe) und threadsicher (thread-safe) deklariert [SWS_CRYPT_50060]. Um Fehler bezüglich unzulässiger Eingabelängen vorab zu vermeiden, kann die für einen Einzelaufruf maximal zulässige Puffergröße des Kontexts über GetMaximumChunkSize ermittelt werden [SWS_CRYPT_50062].

Verwendung

Die Methode Cancel() dient dem gezielten Abbruch einer laufenden Streaming-Operation, die zuvor über die Methode Start() begonnen und noch nicht regulär fertiggestellt wurde [SWS_CRYPT_50058]. Der Aufruf erfolgt synchron und parameterlos auf einer Instanz von ara::crypto::cryp::HashFunctionCtx aus der Header-Datei ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. Bei erfolgreicher Durchführung liefert die Operation ein leeres ara::core::Result<void> zurück [SWS_CRYPT_50058].

Fehlerbehandlung

Tritt während der Ausführung ein Problem auf, enthält das zurückgegebene ara::core::Result einen entsprechenden Fehlerwert [SWS_CRYPT_50058]. Wurde die Verarbeitung vor dem Aufruf von Cancel() nicht durch Start() initiiert, schlägt der Abbruch fehl und gibt den spezifischen Fehlercode ara::crypto::CryptoErrc::kProcessingNotStarted mit Rollback-Semantik zurück [SWS_CRYPT_50058].

Nebenläufigkeit und Einschränkungen

Die Schnittstelle ist als thread-safe und exception safe definiert und mit noexcept deklariert [SWS_CRYPT_50058]. Als wesentliche funktionale Vorbedingung gilt, dass sich die Datenverarbeitung in einem aktiven Zustand befinden muss, der durch einen vorherigen Start()-Aufruf erzeugt wurde [SWS_CRYPT_50058].

Zusammenspiel

Das durch Cancel() umgesetzte Muster ist über diverse Streaming-Kontexte des Crypto-Stacks hinweg standardisiert. Eine exakt übereinstimmende Semantik und Fehlersignalisierung weisen auch die Kontexte VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] und EncryptorPublicCtx [SWS_CRYPT_50089] auf.

Die Methode Compare der Klasse ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) vergleicht Größe und Inhalt eines zuvor berechneten Hash-Digests synchron mit einem erwarteten Referenzwert. Der Sollwert wird über den Parameter expected vom Typ ReadOnlyMemRegion übergeben. Im Erfolgsfall liefert die Funktion ein ara::core::Result<bool> zurück, das genau dann true enthält, wenn die erwartete Bytesequenz mit dem berechneten Digest identisch ist.

Voraussetzung für den Aufruf ist, dass die Digest-Berechnung zuvor mit der Methode Finish() abgeschlossen wurde. Ist dies nicht der Fall, schlägt der Aufruf fehl und liefert den Fehler ara::crypto::CryptoErrc::kProcessingNotFinished mit Rollback-Semantik ([SWS_CRYPT_50154]). Interpretation: Eine abweichende Länge oder ein ungleicher Inhalt von expected führt vermutlich nicht zu einem Fehlercode, sondern zu einem regulären false im Ergebnisobjekt. Frage Q-fdd0ecaec22f6985 (offen)

Hinsichtlich der Nebenläufigkeit ist die Methode als thread-safe und exception safe spezifiziert ([SWS_CRYPT_50154]). Sie wirft aufgrund der Deklaration als noexcept keine C++-Ausnahmen.

In verwandten Krypto-Kontexten kommt dasselbe Prüfungsmuster zum Einsatz: Für Message Authentication Codes vergleicht ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) Größe und Inhalt des berechneten MAC-Werts, während CompareSubspan ([SWS_CRYPT_50028]) die höchstwertigen Bits prüft. Beide Methoden verlangen gleichermaßen eine zuvor beendete Berechnung.

Die Methode [SWS_CRYPT_50064] der Klasse ara::crypto::cryp::HashFunctionCtx schreibt den aktuellen Zustand eines Hash-Kontexts synchron in den übergebenen Ausgabepuffer contextState vom Typ ReadWriteMem Region. Dies ermöglicht es Anwendungen, eine laufende kryptografische Hash-Operation zu unterbrechen und zu einem späteren Zeitpunkt wieder aufzunehmen. Bei erfolgreicher Durchführung liefert der Aufruf ein leeres ara::core::Result<void> zurück.

Zusammenspiel und Pufferdimensionierung

Um Speicherfehler zu verhindern, sollte die zwingend benötigte Puffergröße in Bytes vorab über die Funktion [SWS_CRYPT_50063] abgefragt werden. Der exportierte Zustand kann später mittels [SWS_CRYPT_50065] wieder in einen Hash-Kontext eingespielt werden. Voraussetzung hierfür ist, dass der Zielkontext dieselbe AlgorithmId aufweist und von demselben Crypto Provider bereitgestellt wird wie der Ursprungskontext. Beim Import wird ein eventuell bestehender Rechenzustand vollständig überschrieben.

Fehlerbehandlung

Schlägt die Operation fehl, wird ein Fehler im ara::core::Result zurückgegeben. Folgende Fehlercodes aus ara::crypto::CryptoErrc sind spezifiziert:

• ara::crypto::CryptoErrc::kUnsupported: Der konkrete Kontext unterstützt das Exportieren oder Importieren von Zuständen nicht.
• ara::crypto::CryptoErrc::kInsufficientCapacity: Die Kapazität des übergebenen Puffers contextState reicht nicht aus, um den Zustand aufzunehmen.

Für beide Fehlerfälle ist eine Rollback-Semantik definiert, sodass der Zustand des Objekts unverändert bleibt.

Nebenläufigkeit und Ausführungssicherheit

Die Schnittstelle ist als const und noexcept deklariert. Spezifikationsgemäß ist der Aufruf sowohl thread-safe als auch exception-safe.

Verwendung

Die synchrone Methode Finish() schließt die Berechnung eines Hash-Werts in ara::crypto::cryp::HashFunctionCtx ab [SWS_CRYPT_21115]. Der parameterlose Aufruf liefert ein ara::core::Result<void> zurück, das den erfolgreichen Abschluss signalisiert oder einen Fehler kapselt [SWS_CRYPT_21115]. Die Schnittstelle ist als noexcept deklariert sowie als ausnahmesicher (exception safe) und threadsicher (thread-safe) spezifiziert [SWS_CRYPT_21115].

Fehlerbehandlung und Nebenläufigkeit

Wurde die Hash-Berechnung vor dem Aufruf nicht erfolgreich gestartet, schlägt die Methode mit dem Fehler ara::crypto::CryptoErrc::kInvalidUsageOrder fehl [SWS_CRYPT_21115]. Für diesen Fehlerfall ist eine Rollback-Semantik definiert, sodass Aufrufer vor der Finalisierung zwingend auf einen ordnungsgemäß gestarteten Kontext achten müssen [SWS_CRYPT_21115].

Zusammenspiel

Nach erfolgreichem Aufruf von Finish() wird der berechnete Hash-Digest typischerweise mit GetDigest() in einen bereitgestellten Puffer übertragen [SWS_CRYPT_21116], [SWS_CRYPT_50059]. Zur Abgrenzung dient GetIntermediateDigest(): Diese Funktion liefert denselben Hash-Wert wie die Abfolge von Finish() und GetDigest(), erlaubt danach jedoch die Übergabe weiterer Daten [SWS_CRYPT_50059]. Interpretation: Nach dem Aufruf von Finish() dürfte die Berechnung endgültig abgeschlossen sein und der Kontext keine zusätzlichen Daten mehr annehmen. Frage Q-f4daf29364f45fd5 (offen) Zulässige Puffergrößen für Verarbeitungsschritte im Kontext lassen sich über GetMaximumChunkSize() abfragen [SWS_CRYPT_50062].

Die Methode ImportContextState der Klasse ara::crypto::cryp::HashFunctionCtx (definiert in ara/crypto/cryp/hash_function_ctx.h) dient dazu, den internen Zustand eines Hash-Kontexts aus einem übergebenen Puffer wiederherzustellen und damit eine zuvor unterbrochene Hash-Operation fortzuführen [SWS_CRYPT_50065]. Ein etwaig laufender Berechnungszustand des aktuellen Kontexts wird dabei vollständig durch den importierten Zustand ersetzt [SWS_CRYPT_50065].

Aufruf und Vorbedingungen

Der synchrone Aufruf erfolgt über die Signatur ImportContextState(ReadOnlyMem Region contextState) noexcept und gibt ein ara::core::Result<void> zurück [SWS_CRYPT_50065]. An den Parameter contextState gelten folgende zwingende Voraussetzungen:

• Der Datenpuffer muss zuvor mit der Methode ExportContextState() aus einer Instanz von HashFunctionCtx exportiert worden sein [SWS_CRYPT_50065].
• Der Quellkontext muss dieselbe AlgorithmId besessen haben und vom selben Crypto Provider bereitgestellt worden sein wie der Zielkontext [SWS_CRYPT_50065].

Fehlerbehandlung und Nebenläufigkeit

Im Fehlerfall wird ein Fehlercode mit Rollback-Semantik zurückgegeben, sodass der bestehende Zustand des Kontexts bei Misserfolg unverändert bleibt [SWS_CRYPT_50065]:

• ara::crypto::CryptoErrc::kInvalidArgument: Das Argument contextState enthält ungültige Daten [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported: Der spezifische Kontext unterstützt das Exportieren und Importieren von Kontextzuständen nicht [SWS_CRYPT_50065].

Die Operation ist als thread-safe und exception safe spezifiziert [SWS_CRYPT_50065].

Die Methode Start() der Schnittstelle ara::crypto::cryp::HashFunctionCtx initialisiert den Kontext für die schrittweise Berechnung eines Hash-Werts ohne Initialisierungsvektor (IV) [SWS_CRYPT_50152]. Ein erneuter Aufruf bricht eine eventuell bereits laufende Hash-Berechnung ab und setzt den Kontext für eine neue Berechnung auf [SWS_CRYPT_50152].

Die Funktion ist synchron, nimmt keine Parameter entgegen und gibt ein ara::core::Result<void> zurück [SWS_CRYPT_50152]. Tritt bei der Initialisierung ein Fehler auf, greift Rollback-Semantik mit folgenden spezifischen Fehlercodes [SWS_CRYPT_50152]:

• ara::crypto::CryptoErrc::kUnsupported: Die verwendete Hash-Funktion erwartet zwingend einen Initialisierungsvektor [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource: Eine für die Operation zwingend erforderliche interne Ressource ist belegt [SWS_CRYPT_50152].

Hinsichtlich der Nebenläufigkeit ist die Methode als thread-safe sowie exception safe spezifiziert und als noexcept deklariert [SWS_CRYPT_50152]. Nach erfolgreicher Initialisierung können Nachrichtenteile sequenziell über die Methode Update() des Kontexts eingespeist werden [SWS_CRYPT_21113]. Da der Aufruf laufende Berechnungen abbricht, dürfte die Funktion in der Praxis auch als Reset-Mechanismus vor einem Neustart dienen. Frage Q-9c369489a6c6e8cb (offen)

Verwendung

Die Funktion Start der Schnittstelle ara::crypto::cryp::HashFunctionCtx initialisiert den Kontext für die Berechnung eines Hash-Digests unter Verwendung eines Initialisierungsvektors (IV) [SWS_CRYPT_50153]. Als Parameter wird der Initialisierungsvektor iv über eine ReadOnlyMemRegion übergeben [SWS_CRYPT_50153]. Der synchrone Aufruf liefert ein ara::core::Result<void> zurück, das im Erfolgsfall keinen Rückgabewert enthält [SWS_CRYPT_50153]. Ein Aufruf bricht zudem eine eventuell bereits laufende Hash-Berechnung auf diesem Kontext ab [SWS_CRYPT_50153].

Fehlerbehandlung

Tritt bei der Initialisierung ein Fehler auf, wird ein entsprechender Fehlercode zurückgegeben, wobei für alle Fehlerfälle eine Rollback-Semantik garantiert wird [SWS_CRYPT_50153]:

• ara::crypto::CryptoErrc::kInvalidInputSize: Die Größe des bereitgestellten Initialisierungsvektors wird nicht unterstützt [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported: Die zugrundeliegende Hash-Funktion verwendet keinen Initialisierungsvektor [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource: Eine für die Initialisierung benötigte Ressource ist belegt [SWS_CRYPT_50153].

Nebenläufigkeit und Zusammenspiel

Die Schnittstelle ist als noexcept deklariert sowie als threadsicher (thread-safe) und ausnahmesicher (exception safe) spezifiziert [SWS_CRYPT_50153]. Im typischen Ablauf bildet der Aufruf die Vorbedingung für die nachfolgende schrittweise Verarbeitung der Eingabenachricht über die Methode Update [SWS_CRYPT_21113].

Die synchrone Methode Update dient in [SWS_CRYPT_21113] der inkrementellen Aktualisierung eines laufenden Hash-Berechnungskontexts (ara::crypto::cryp::HashFunctionCtx). Über den Parameter data (ReadOnlyMemRegion) wird ein Teil der zu verarbeitenden Eingabenachricht übergeben. Die Funktion liefert ein ara::core::Result<void> zurück, das im Erfolgsfall leer ist oder einen entsprechenden Fehlercode kapselt.

Hinsichtlich des Fehlerverhaltens bietet die Methode Rollback-Semantik bei zwei spezifischen Fehlerzuständen:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Die Berechnung wurde zuvor nicht durch einen Aufruf der Methode Start() initiiert [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize: Die Größe der übergebenen Daten wird vom Kontext nicht unterstützt [SWS_CRYPT_21113].

Für den Aufrufkontext gelten klare Reihenfolge- und Größenbedingungen: Vor der Datenübergabe muss der Hash-Vorgang initialisiert worden sein [SWS_CRYPT_21113]. Um kInvalidInputSize zu vermeiden, kann die maximal zulässige Blockgröße für einen einzelnen Update-Aufruf vorab über GetMaximumChunkSize ermittelt werden [SWS_CRYPT_50062]. Gemäß Spezifikation ist die Funktion als ausnahmesicher (exception safe) und threadsicher (thread-safe) deklariert [SWS_CRYPT_21113].

Im Zusammenspiel mit anderen Schnittstellen existiert innerhalb von HashFunctionCtx eine Überladung zur Übergabe von Schlüsselobjekten via Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. Nach der Zufuhr aller Datenblöcke dürfte die Finalisierung der Prüfsumme vermutlich über Finish() erfolgen [SWS_CRYPT_50062]. Frage Q-dcac20f353ca55f4 (offen)

Die synchrone Methode Update dient in [SWS_CRYPT_50057] dazu, den Kontext einer Hashwert-Berechnung in ara::crypto::cryp::HashFunctionCtx schrittweise um einen neuen Nachrichtenabschnitt in Form eines Schlüsselobjekts zu erweitern. Als Parameter wird ein Smart Pointer auf das Schlüsselobjekt (CryptoObject::Sptr key) übergeben. Der Aufruf liefert als Rückgabewert ein ara::core::Result<void>, das bei erfolgreicher Verarbeitung leer ist oder im Fehlerfall einen entsprechenden Fehlercode kapselt [SWS_CRYPT_50057].

Als Reihenfolgebedingung gilt, dass die Berechnung zuvor zwingend durch den Aufruf von Start() initiiert worden sein muss; andernfalls wird der Fehler ProcessingNotStarted gemeldet [SWS_CRYPT_50057]. Weitere spezifische Fehlerfälle umfassen (jeweils mit Rollback-Semantik) [SWS_CRYPT_50057]:

• ara::crypto::CryptoErrc::kUnsupported, wenn der Hash-Kontext das Hashen von Schlüsseln generell nicht unterstützt,
• ara::crypto::CryptoErrc::kIncompatibleObject, falls das übergebene Schlüsselobjekt nicht kompatibel mit dem Kontext ist,
• ara::crypto::CryptoErrc::kUsageViolation, sofern die zulässige Verwendung des Schlüssels nicht kAllowHash Calculation umfasst,
• ara::crypto::CryptoErrc::kInvalidInputSize, wenn die Datengröße des übergebenen Schlüssels nicht unterstützt wird.

Die Methode ist als thread-safe sowie als exception safe (noexcept) deklariert [SWS_CRYPT_50057]. Im Zusammenspiel mit anderen Schnittstellen des Moduls kann die maximal zulässige Puffergröße für einzelne Update-Aufrufe über GetMaximumChunkSize() ermittelt werden [SWS_CRYPT_50062]. Für reguläre Nachrichtenteile ohne Schlüsselobjekt existiert in HashFunctionCtx parallel die Überladung Update(ReadOnlyMemRegion data) [SWS_CRYPT_21113].