class ara::crypto::cryp::RandomGeneratorCtx

Die Methode AddEntropy der Klasse ara::crypto::cryp::RandomGeneratorCtx dient dazu, den internen Zustand eines Zufallszahlengenerators (RNG) durch Einmischen zusätzlich übergebener Entropiewerte zu aktualisieren [SWS_CRYPT_22914]. Die Deklaration ist über die Header-Datei ara/crypto/cryp/random_generator_ctx.h verfügbar [SWS_CRYPT_22914]. Als Eingabeparameter erwartet die Funktion ein Objekt vom Typ ReadOnlyMemRegion namens entropy, welches den Speicherbereich mit dem hinzuzufügenden Entropiewert kapselt [SWS_CRYPT_22914].

Der Aufruf wird synchron ausgeführt (Interpretation: die Schnittstelle liefert das Ergebnis direkt ohne asynchronen Ergebnistyp zurück). Frage Q-6e56e1daaa526bf8 (offen) Das Resultat wird als ara::core::Result<void> zurückgegeben, welches im Erfolgsfall leer ist, wenn die Methode unterstützt wird und die Entropie erfolgreich eingemischt werden konnte [SWS_CRYPT_22914]. Unterstützt der konkrete Zufallsgenerator-Kontext das Hinzufügen von Entropie hingegen nicht, schlägt der Aufruf fehl und liefert den Fehlercode ara::crypto::CryptoErrc::kUnsupported mit garantierter Rollback-Semantik [SWS_CRYPT_22914].

In Bezug auf Nebenläufigkeit und Fehlersicherheit ist die Schnittstelle als threadsicher (thread-safe) sowie ausnahmesicher (exception safe) spezifiziert und mit dem Bezeichner noexcept versehen [SWS_CRYPT_22914]. Aufrufer können die Funktion somit sicher aus mehreren Threads aufrufen, sollten jedoch stets das zurückgegebene ara::core::Result auswerten, um eine fehlende Unterstützung der Entropiezufuhr im jeweiligen Kontext abzufangen [SWS_CRYPT_22914].

Die Funktion Generate der Schnittstelle ara::crypto::cryp::RandomGeneratorCtx dient dazu, einen bereitgestellten Ausgabepuffer mit einer (pseudo-)zufälligen Sequenz zu befüllen [SWS_CRYPT_22915]. Als Übergabeparameter nimmt die Methode den beschreibbaren Speicherbereich output vom Typ ReadWriteMemRegion entgegen, in den die erzeugten Zufallsbytes direkt geschrieben werden [SWS_CRYPT_22915].

Hinsichtlich Ausführungssicherheit und Nebenläufigkeit ist die Methode als noexcept deklariert, gilt als Exception-safe und ist explizit als thread-safe spezifiziert [SWS_CRYPT_22915]. Dies gestattet den nebenläufigen Aufruf aus mehreren Threads.

Fehlerbehandlung

Der Rückgabetyp ara::core::Result<void> signalisiert den Erfolg der Operation durch ein leeres Ergebnis oder liefert im Fehlerfall einen entsprechenden Fehlercode mit Rollback-Semantik [SWS_CRYPT_22915]:

• ara::crypto::CryptoErrc::kUninitializedContext: Tritt auf, falls der Kontext zuvor durch die Applikation initialisiert bzw. mit Entropie („seeded“) versorgt werden muss [SWS_CRYPT_22915].
• ara::crypto::CryptoErrc::kBusyResource: Wird zurückgegeben, wenn dem Kontext derzeit die Entropie ausgegangen ist („out-of-entropy“) und dieser daher die angeforderte Menge an Zufallsbytes nicht bereitstellen kann [SWS_CRYPT_22915].

Zusammenspiel und Abgrenzung

Während RandomGeneratorCtx::Generate rohe Zufallsdatenbytes in Puffer schreibt [SWS_CRYPT_22915], existieren im Modul crypt weitere Erzeugungsfunktionen mit abweichendem Fokus: So dient CryptoProvider::GenerateSymmetricKey [SWS_CRYPT_20721] der Instanziierung symmetrischer Schlüssel und CryptoProvider::GeneratePrivateKey [SWS_CRYPT_20722] der Generierung asymmetrischer Schlüsselpaare. Zudem ist die Methode nicht mit der gleichnamigen Funktion Generate des MessageAuthnCodeCtx zu verwechseln, welche der Berechnung eines MAC-Digests dient [SWS_CRYPT_50029].

Verwendung

Die rein virtuelle Methode Seed der Schnittstelle ara::crypto::cryp::RandomGeneratorCtx dient dem Setzen des internen Zustands des Zufallszahlengenerators (RNG) über einen bereitgestellten Speicherbereich [SWS_CRYPT_22911]. Die Deklaration erfolgt im Header ara/crypto/cryp/random_generator_ctx.h mit der Signatur virtual ara::core::Result<void> Seed(ReadOnlyMemRegion seed) noexcept = 0; [SWS_CRYPT_22911].

Als Eingabeparameter nimmt die synchrone Funktion seed vom Typ ReadOnlyMemRegion entgegen, der den Speicherbereich mit dem Seed-Wert enthält [SWS_CRYPT_22911]. Bei erfolgreicher Ausführung und Unterstützung durch den Kontext liefert die Methode ein leeres ara::core::Result<void> zurück [SWS_CRYPT_22911].

Fehlerbehandlung

Im Fehlerfall enthält das zurückgegebene ara::core::Result einen entsprechenden Fehlercode [SWS_CRYPT_22911]:

• ara::crypto::CryptoErrc::kUnsupported: Tritt auf, wenn der konkrete RandomGeneratorCtx das Seeding nicht unterstützt; für diesen Fehlerfall ist Rollback-Semantik spezifiziert [SWS_CRYPT_22911].

Nebenläufigkeit und Einschränkungen

Die Schnittstelle ist als noexcept deklariert und hinsichtlich der Ausführungssicherheit als exception safe sowie thread-safe klassifiziert [SWS_CRYPT_22911].

Zusammenspiel

Ergänzend zu dieser speicherbereichsbasierten Funktion definiert [SWS_CRYPT_22912] eine Überladung Seed(SymmetricKey::Sptr seed), welche den Zustand des RNG mittels eines symmetrischen Schlüssels initialisiert und dabei Nutzungsbeschränkungen wie kAllowRngInit auswertet.

Die Methode Seed initialisiert den internen Zustand eines Zufallszahlengenerators im Kontext von ara::crypto::cryp::RandomGeneratorCtx unter Verwendung eines symmetrischen Schlüssels [SWS_CRYPT_22912]. Der Aufruf erfolgt synchron und ist als threadsicher sowie ausnahmesicher (exception safe und noexcept) spezifiziert [SWS_CRYPT_22912]. Als Eingabeparameter dient ein Smart Pointer auf einen Schlüssel (SymmetricKey::Sptr), dessen Schlüsselwert als Seed übernommen wird [SWS_CRYPT_22912].

Bei der Fehlerbehandlung liefert die Funktion ein ara::core::Result<void> zurück, welches im Erfolgsfall leer ist [SWS_CRYPT_22912]. Schlägt die Operation fehl, greift eine Rollback-Semantik; dies betrifft insbesondere folgende Fehlercodes:

• ara::crypto::CryptoErrc::kUsageViolation: Tritt auf, wenn die erlaubte Schlüsselverwendung des übergebenen Schlüssels das Flag kAllowRngInit nicht umfasst [SWS_CRYPT_22912].
• ara::crypto::CryptoErrc::kUnsupported: Wird gemeldet, wenn die konkrete Kontextinstanz das Setzen eines Seeds mittels eines symmetrischen Schlüssels nicht unterstützt [SWS_CRYPT_22912].

Im Zusammenspiel mit der Schnittstellenfamilie stellt diese Funktion die schlüsselbasierte Variante dar, während die Überladung gemäß [SWS_CRYPT_22911] die Initialisierung über einen unstrukturierten Speicherbereich (ReadOnlyMemRegion) abdeckt. Aufgrund der Rollback-Semantik verbleibt der interne Generatorzustand im Fehlerfall vermutlich im vorherigen Zustand (Interpretation). Frage Q-970cbedd1843b26a (offen)