klasse ara::crypto::cryp::RandomGeneratorCtx

De methode AddEntropy van de klasse ara::crypto::cryp::RandomGeneratorCtx dient ertoe de interne toestand van een toevalsgenerator (RNG) te actualiseren door het inmengen van extra meegegeven entropiewaarden [SWS_CRYPT_22914]. De declaratie is beschikbaar via het headerbestand ara/crypto/cryp/random_generator_ctx.h [SWS_CRYPT_22914]. Als invoerparameter verwacht de functie een object van het type ReadOnlyMemRegion genaamd entropy, dat het geheugengebied met de toe te voegen entropiewaarde inkapselt [SWS_CRYPT_22914].

De aanroep wordt synchroon uitgevoerd (interpretatie: de interface levert het resultaat direct terug zonder asynchroon resultaattype). Vraag Q-6e56e1daaa526bf8 (open) Het resultaat wordt geretourneerd als ara::core::Result<void>, dat bij succes leeg is wanneer de methode wordt ondersteund en de entropie met succes kon worden ingemengd [SWS_CRYPT_22914]. Ondersteunt de concrete toevalsgeneratorcontext het toevoegen van entropie daarentegen niet, dan mislukt de aanroep en levert deze de foutcode ara::crypto::CryptoErrc::kUnsupported met gegarandeerde rollback-semantiek op [SWS_CRYPT_22914].

Wat betreft concurrency en foutbestendigheid is de interface gespecificeerd als thread-veilig (thread-safe) en exceptieveilig (exception safe) en voorzien van de identifier noexcept [SWS_CRYPT_22914]. Oproepers kunnen de functie zodoende veilig aanroepen vanuit meerdere threads, maar dienen steeds het geretourneerde ara::core::Result te evalueren om een ontbrekende ondersteuning van de entropietoevoer in de desbetreffende context af te vangen [SWS_CRYPT_22914].

De functie Generate van de interface ara::crypto::cryp::RandomGeneratorCtx dient ertoe een bereitgestelde uitvoerbuffer te vullen met een (pseudo)willekeurige sequentie [SWS_CRYPT_22915]. Als overdrachtsparameter neemt de methode het beschrijfbare geheugengebied output van het type ReadWriteMemRegion aan, waarin de gegenereerde willekeurige bytes direct worden geschreven [SWS_CRYPT_22915].

Met betrekking tot uitvoeringsveiligheid en concurrency is de methode gedeclareerd als noexcept, geldt als exception-safe en is expliciet gespecificeerd als thread-safe [SWS_CRYPT_22915]. Dit staat de concurrente aanroep vanuit meerdere threads toe.

Foutafhandeling

Het retourtype ara::core::Result<void> signaleert het succes van de bewerking door een leeg resultaat of levert in geval van een fout een overeenkomstige foutcode met rollback-semantiek op [SWS_CRYPT_22915]:

• ara::crypto::CryptoErrc::kUninitializedContext: Treedt op indien de context vooraf door de applicatie moet worden geïnitialiseerd respectievelijk van entropie moet worden voorzien („seeded”) [SWS_CRYPT_22915].
• ara::crypto::CryptoErrc::kBusyResource: Wordt geretourneerd wanneer de context momenteel door zijn entropie heen is („out-of-entropy”) en deze daarom de gevraagde hoeveelheid willekeurige bytes niet kan bereitstellen [SWS_CRYPT_22915].

Interactie en afbakening

Terwijl RandomGeneratorCtx::Generate ruwe toevalsdatabytes naar buffers schrijft [SWS_CRYPT_22915], bestaan er in de module crypt aanvullende generatiefuncties met een afwijkende focus: zo dient CryptoProvider::GenerateSymmetricKey [SWS_CRYPT_20721] voor de instantiëring van symmetrische sleutels en CryptoProvider::GeneratePrivateKey [SWS_CRYPT_20722] voor het genereren van asymmetrische sleutelparen. Bovendien moet de methode niet worden verward met de gelijknamige functie Generate van de MessageAuthnCodeCtx, die dient voor de berekening van een MAC-digest [SWS_CRYPT_50029].

Gebruik

De puur virtuele methode Seed van de interface ara::crypto::cryp::RandomGeneratorCtx dient voor het instellen van de interne toestand van de toevalsgenerator (RNG) via een beschikbaar gesteld geheugengebied [SWS_CRYPT_22911]. De declaratie vindt plaats in de header ara/crypto/cryp/random_generator_ctx.h met de signatuur virtual ara::core::Result<void> Seed(ReadOnlyMemRegion seed) noexcept = 0; [SWS_CRYPT_22911].

Als invoerparameter accepteert de synchrone functie seed van het type ReadOnlyMemRegion, die het geheugengebied met de seed-waarde bevat [SWS_CRYPT_22911]. Bij succesvolle uitvoering en ondersteuning door de context levert de methode een lege ara::core::Result<void> terug [SWS_CRYPT_22911].

Foutafhandeling

In geval van een fout bevat de geretourneerde ara::core::Result een overeenkomstige foutcode [SWS_CRYPT_22911]:

• ara::crypto::CryptoErrc::kUnsupported: Treedt op wanneer de concrete RandomGeneratorCtx het seeden niet ondersteunt; voor dit foutgeval is rollback-semantiek gespecificeerd [SWS_CRYPT_22911].

Gelijktijdigheid en beperkingen

De interface is gedeclareerd als noexcept en wat betreft uitvoeringsveiligheid geclassificeerd als exception safe en thread-safe [SWS_CRYPT_22911].

Samenspel

In aanvulling op deze op geheugengebieden gebaseerde functie definieert [SWS_CRYPT_22912] een overbelading Seed(SymmetricKey::Sptr seed), die de toestand van de RNG initialiseert met behulp van een symmetrische sleutel en daarbij gebruiksbeperkingen zoals kAllowRngInit evalueert.

De methode Seed initialiseert de interne toestand van een toevalsgenerator in de context van ara::crypto::cryp::RandomGeneratorCtx met gebruikmaking van een symmetrische sleutel [SWS_CRYPT_22912]. De aanroep geschiedt synchroon en is gespecificeerd als thread-safe en uitzonderingsveilig (exception safe en noexcept) [SWS_CRYPT_22912]. Als invoerparameter dient een smart pointer naar een sleutel (SymmetricKey::Sptr), waarvan de sleutelwaarde als seed wordt overgenomen [SWS_CRYPT_22912].

Bij de foutafhandeling levert de functie een ara::core::Result<void> terug, die bij succes leeg is [SWS_CRYPT_22912]. Als de operatie mislukt, treedt een rollback-semantiek in werking; dit betreft in het bijzonder de volgende foutcodes:

• ara::crypto::CryptoErrc::kUsageViolation: Treedt op wanneer het toegestane sleutelgebruik van de overgedragen sleutel de vlag kAllowRngInit niet omvat [SWS_CRYPT_22912].
• ara::crypto::CryptoErrc::kUnsupported: Wordt gemeld wanneer de concrete contextinstantie het instellen van een seed met behulp van een symmetrische sleutel niet ondersteunt [SWS_CRYPT_22912].

In samenspel met de interfacefamilie vormt deze functie de sleutelgebaseerde variant, terwijl de overbelading conform [SWS_CRYPT_22911] de initialisatie via een ongestructureerd geheugengebied (ReadOnlyMemRegion) afdekt. Vanwege de rollback-semantiek blijft de interne generatortoestand bij een fout vermoedelijk in de vorige toestand (interpretatie). Vraag Q-970cbedd1843b26a (open)