klasse ara::crypto::cryp::CryptoProvider

De methode CreateAuthCipherCtx dient voor het creëren van een context voor symmetrische geauthenticeerde versleuteling ([SWS_CRYPT_20745]). Deze is als puur virtuele interface gedefinieerd in de klasse ara::crypto::cryp::CryptoProvider en dient via het headerbestand ara/crypto/cryp/crypto_provider.h te worden geïntegreerd ([SWS_CRYPT_20745]).

Gebruik en semantiek

Als invoerparameter wordt algId overgedragen, die het doel-cryptoalgoritme identificeert ([SWS_CRYPT_20745]). De functie werkt synchroon en gooit geen excepties (noexcept) ([SWS_CRYPT_20745]). Bij succesvolle uitvoering retourneert zij een ara::core::Result met een smart pointer naar de gecreëerde instantie AuthCipherCtx::Sptr ([SWS_CRYPT_20745]).

Foutafhandeling

In geval van een fout wordt een overeenkomstige foutcode in ara::core::Result met rollback-semantiek geretourneerd ([SWS_CRYPT_20745]):

• ara::crypto::CryptoErrc::kInvalidArgument: Wanneer algId geen algoritme voor een symmetrische geauthenticeerde stroomcijfer specificeert ([SWS_CRYPT_20745]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Wanneer voor algId een niet-ondersteunde waarde is overgedragen ([SWS_CRYPT_20745]).

Concurrency

De aanroep van CreateAuthCipherCtx is thread-safe (thread-safe) en gespecificeerd als uitzonderingsveilig (exception safe) ([SWS_CRYPT_20745]).

Gebruik

De methode CreateDecryptorPrivateCtx van de interface ara::crypto::cryp::CryptoProvider dient voor het aanmaken van een context voor asymmetrische ontsleuteling met gebruikmaking van een privésleutel conform [SWS_CRYPT_20751]. Als invoerparameter verwacht de functie algId, die de identifier van het gewenste asymmetrische versleutelings- resp. ontsleutelingsalgoritme vastlegt. Interpretatie: De aanroep wordt vermoedelijk synchroon uitgevoerd, aangezien de signatuur direct een ara::core::Result retourneert, dat bij succes een smart pointer naar de aangemaakte context (DecryptorPrivateCtx::Sptr) bevat [SWS_CRYPT_20751]. Vraag Q-45d1c4a1b2133f4c (open)

Foutafhandeling

Als de context niet kan worden aangemaakt, wordt de fout getransporteerd in het geretourneerde ara::core::Result. Indien voor de parameter algId een niet-ondersteunde waarde is doorgegeven, resulteert dit specifiek in de foutcode ara::crypto::CryptoErrc::kUnknownIdentifier met rollback-semantiek [SWS_CRYPT_20751].

Gelijktijdigheid en beperkingen

De functie is gedefinieerd als noexcept en waarborgt uitzonderingsveiligheid (exception safe) [SWS_CRYPT_20751]. Voor gelijktijdige toegang vanuit meerdere threads is de methode als thread-safe gespecificeerd [SWS_CRYPT_20751]. Aangezien de signatuur in de header ara/crypto/cryp/crypto_provider.h als puur virtuele methode is gedeclareerd, berust de concrete uitwerking bij de desbetreffende provider-implementatie [SWS_CRYPT_20751].

De puur virtuele interfacemethode CreateEncryptorPublicCtx behoort tot de klasse ara::crypto::cryp::CryptoProvider en wordt gedeclareerd via het headerbestand ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20750]. Haar taak bestaat uit het instantiëren van een nieuwe context voor asymmetrische versleutelingsbewerkingen met een publieke sleutel [SWS_CRYPT_20750].

Gebruik: De aanroep vindt synchroon plaats met opgave van de parameter algId van het type AlgId, die de identifier van het gewenste asymmetrische versleutelings- resp. ontsleutelingsalgoritme vastlegt [SWS_CRYPT_20750]. De methode levert het resultaat in een ara::core::Result op, die in geval van succes een smart pointer van het type EncryptorPublicCtx::Sptr naar de gecreëerde context beschikbaar stelt [SWS_CRYPT_20750].

Foutafhandeling: Indien het argument algId een niet-ondersteunde algoritmewaarde bevat, mislukt de aanroep en levert deze in de ara::core::Result de foutcode ara::crypto::CryptoErrc::kUnknownIdentifier op [SWS_CRYPT_20750]. Voor deze foutsituatie is een expliciete rollback-semantiek gespecificeerd [SWS_CRYPT_20750].

Gelijktijdigheid en uitzonderingsveiligheid: De interface is gedeclareerd als noexcept, geldt als uitzonderingsveilig (exception safe) en is uitdrukkelijk gespecificeerd als thread-safe (thread-safe) [SWS_CRYPT_20750].

De methode CreateHashFunctionCtx dient voor de instantiëring van een cryptografische hash-context ([SWS_CRYPT_20747]). Deze wordt als puur virtuele interface van de klasse ara::crypto::cryp::CryptoProvider aangeboden via de header ara/crypto/cryp/crypto_provider.h.

Gebruik en parameters

De aanroep vindt synchroon plaats en verwacht als invoerparameter algId (van het type AlgId), die het gewenste cryptografische algoritme identificeert ([SWS_CRYPT_20747]). Als retourwaarde levert de functie een ara::core::Result<HashFunctionCtx::Sptr> op, die bij succes een smart pointer naar de gecreëerde context bevat.

Foutafhandeling

Mislukt de creatie, dan bevat de ara::core::Result een overeenkomstige foutcode met rollback-semantiek ([SWS_CRYPT_20747]):

• ara::crypto::CryptoErrc::kInvalidArgument: Wordt geretourneerd wanneer de overgedragen algId voor een ander algoritmetype dan een hashfunctie is gespecificeerd ([SWS_CRYPT_20747]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Treedt op indien voor algId een niet-ondersteunde identifier is overgedragen ([SWS_CRYPT_20747]).

Gelijktijdigheid en beperkingen

De functie is gedeclareerd als noexcept en gespecificeerd als uitzonderingsveilig (“exception safe”) ([SWS_CRYPT_20747]). Bovendien is de aanroep thread-safe (“thread-safe”), zodat gelijktijdige aanroepen vanuit meerdere threads op dezelfde instantie van CryptoProvider zijn toegestaan ([SWS_CRYPT_20747]).

De methode CreateKeyAgreementPrivateCtx van de klasse ara::crypto::cryp::CryptoProvider dient voor het aanmaken van een privésleutelcontext voor sleutelovereenkomsten (KeyAgreementPrivateCtx) conform [SWS_CRYPT_20758]. De declaratie wordt bereitgesteld via het headerbestand #include "ara/crypto/cryp/crypto_provider.h".

Gebruik en aanroep

Als overdrachtsparameter verwacht de synchrone methode de identifier algId van het type AlgId, die het gewenste crypto-algoritme voor de key-agreement specificeert. Als retourwaarde levert de functie een ara::core::Result<KeyAgreementPrivateCtx::Sptr> op, dat bij succes een smart pointer naar de nieuw aangemaakte contextinstantie inkapselt [SWS_CRYPT_20758].

Foutafhandeling

Mislukt de instantiëring, dan bevat het geretourneerde ara::core::Result een foutcode met rollback-semantiek [SWS_CRYPT_20758]:

• ara::crypto::CryptoErrc::kInvalidArgument: Treedt op wanneer het argument algId een crypto-algoritme aangeeft dat verschilt van sleutelovereenkomstprocedures.
• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt geretourneerd indien de identifier algId een niet-ondersteunde waarde bevat.

Concurrency en veiligheid

De interface is gedeclareerd als noexcept en gedefinieerd als uitzonderingsveilig (exception safe). Bovendien is de aanroep gespecificeerd als thread-safe (thread-safe), zodat gelijktijdige aanroepen op dezelfde instantie van CryptoProvider zijn toegestaan [SWS_CRYPT_20758].

Gebruik

De methode CreateKeyDecapsulatorPrivateCtx van de interface ara::crypto::cryp::CryptoProvider dient voor het aanmaken van een privécontext voor sleuteldecapsulatie voor een Key Encapsulation Mechanism (KEM) [SWS_CRYPT_20753]. Als invoerparameter verwacht zij algId van het type AlgId, die het gewenste KEM-crypto-algoritme identificeert [SWS_CRYPT_20753]. De functie werkt synchroon en levert het resultaat terug in een ara::core::Result<KeyDecapsulatorPrivateCtx::Sptr>, dat bij succes een smart pointer naar de nieuw geïnstantieerde context inkapselt [SWS_CRYPT_20753].

Foutafhandeling

Treedt er bij het aanmaken van de context een fout op, dan wordt deze gemeld via het ara::core::Result met rollback-semantiek [SWS_CRYPT_20753]:

• ara::crypto::CryptoErrc::kInvalidArgument: Het argument algId specificeert een crypto-algoritme dat geen asymmetrische KEM-methode is [SWS_CRYPT_20753].
• ara::crypto::CryptoErrc::kUnknownIdentifier: Het argument algId vertoont een niet-ondersteunde waarde [SWS_CRYPT_20753].

Gelijktijdigheid en uitvoeringsveiligheid

De interface is gedeclareerd als noexcept en gespecificeerd als exceptieveilig (exception safe) [SWS_CRYPT_20753]. Bovendien is de uitvoering thread-veilig (thread-safe) ontworpen [SWS_CRYPT_20753].

De methode CreateKeyDerivationFunctionCtx van de klasse ara::crypto::cryp::CryptoProvider dient voor het aanmaken van een uitvoeringscontext voor sleutelafleidingsfuncties ([SWS_CRYPT_20748]). Als invoerparameter wordt de identifier algId van het type AlgId meegegeven, die het gewenste cryptografische doelalgoritme bepaalt. De synchrone aanroep levert een ara::core::Result op, die bij succesvolle uitvoering een smart pointer naar de gegenereerde context (KeyDerivationFunctionCtx::Sptr) bereitstelt ([SWS_CRYPT_20748]).

Treedt er bij de instantiëring een fout op, dan wordt het resultaat geretourneerd met een overeenkomstige foutcode onder rollback-semantiek ([SWS_CRYPT_20748]):

• ara::crypto::CryptoErrc::kInvalidArgument: Het argument algId specificeert een cryptografisch algoritme dat geen sleutelafleidingsfunctie is ([SWS_CRYPT_20748]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: De meegegeven identifier algId heeft een niet-ondersteunde waarde ([SWS_CRYPT_20748]).

De interface is gedeclareerd als zuiver virtuele functie, aangeduid als noexcept en dwingend ingedeeld als thread-safe en exception safe ([SWS_CRYPT_20748]). De opname vindt plaats via het headerbestand #include "ara/crypto/cryp/crypto_provider.h". De functie adresseert de overkoepelende eisen [RS_CRYPTO_02103] en [RS_AP_00144].

Gebruik

De methode CreateKeyEncapsulatorPublicCtx van de interface ara::crypto::cryp::CryptoProvider dient voor het aanmaken van een openbare context voor een Key Encapsulation Mechanism (KEM) [SWS_CRYPT_20752]. Hiervoor moet het headerbestand #include "ara/crypto/cryp/crypto_provider.h" worden ingevoegd [SWS_CRYPT_20752]. De aanroep vindt synchroon plaats: als invoerparameter wordt algId doorgegeven, die het doel-cryptoalgoritme van het KEM specificeert. Bij succesvolle uitvoering retourneert de methode een smart pointer naar de aangemaakte context (KeyEncapsulatorPublicCtx::Sptr), ingekapseld in een ara::core::Result [SWS_CRYPT_20752].

Foutafhandeling

Als tijdens het aanmaken een fout optreedt, treedt er een rollback-semantiek in werking en bevat het ara::core::Result een specifieke foutcode uit ara::crypto::CryptoErrc [SWS_CRYPT_20752]:

• ara::crypto::CryptoErrc::kInvalidArgument: Wordt geretourneerd wanneer het argument algId een cryptografisch algoritme aanduidt dat geen asymmetrisch KEM is [SWS_CRYPT_20752].
• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt gemeld indien het argument algId een niet-ondersteunde waarde bevat [SWS_CRYPT_20752].

Concurrency en veiligheid

De interfacefunctie is gedeclareerd met noexcept en geclassificeerd als uitzonderingsveilig (exception safe) en thread-safe (thread-safe) [SWS_CRYPT_20752]. Ze kan zodoende veilig worden aangeroepen vanuit gelijktijdige contexten zonder externe synchronisatie [SWS_CRYPT_20752].

Gebruik

De puur virtuele methode CreateMessageAuthnCodeCtx van de interface ara::crypto::cryp::CryptoProvider vereist het headerbestand ara/crypto/cryp/crypto_provider.h en dient voor het synchroon creëren van een context voor symmetrische Message Authentication Codes [SWS_CRYPT_20746]. Als invoerwaarde accepteert de functie de parameter algId van het type AlgId, die het doel-cryptoalgoritme specificeert [SWS_CRYPT_20746]. Bij succesvolle uitvoering levert de methode een ara::core::Result<MessageAuthnCodeCtx::Sptr> op, die een smart pointer naar de nieuw geïnstantieerde context-instantie inkapselt [SWS_CRYPT_20746].

Foutafhandeling

In geval van een fout stelt het geretourneerde Result-object specifieke foutcodes met rollback-semantiek beschikbaar [SWS_CRYPT_20746]:

• ara::crypto::CryptoErrc::kInvalidArgument: Het argument algId specificeert een cryptografisch algoritme dat geen symmetrische Message Authentication Code is [SWS_CRYPT_20746].
• ara::crypto::CryptoErrc::kUnknownIdentifier: Voor het argument algId is een onbekende of niet-ondersteunde identifier overgedragen [SWS_CRYPT_20746].

Gelijktijdigheid en uitvoeringsveiligheid

De interface is voorzien van de specificator noexcept en garandeert volledige uitzonderingsveiligheid (exception safe) [SWS_CRYPT_20746]. Voorts is de functie expliciet als thread-safe (thread-safe) gespecificeerd, zodat aanroepen parallel en zonder externe synchronisatie vanuit concurrente threads kunnen plaatsvinden [SWS_CRYPT_20746].

Gebruik

De interface CreateProtectedKeyImportCtx van de klasse ara::crypto::cryp::CryptoProvider (gedefinieerd in ara/crypto/cryp/crypto_provider.h) dient voor het synchroon creëren van een context voor de beveiligde sleutelimport ([SWS_CRYPT_50017]). Via de invoerparameter algId wordt de identifier van het gewenste wrapping-algoritme doorgegeven ([SWS_CRYPT_50017]). Bij succesvolle instantiëring levert de methode een ara::core::Result terug, die een smart pointer ProtectedKeyImportCtx::Sptr naar de gemaakte context beschikbaar stelt ([SWS_CRYPT_50017]).

Foutafhandeling

Als het creëren mislukt, retourneert de methode in de ara::core::Result een foutcode met rollback-semantiek ([SWS_CRYPT_50017]):

• ara::crypto::CryptoErrc::kInvalidArgument: Treedt op wanneer het door algId gespecificeerde cryptoalgoritme door de CryptoProvider niet voor wrapping wordt ondersteund ([SWS_CRYPT_50017]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt gemeld wanneer het argument algId een onbekende of niet-ondersteunde identifierwaarde bevat ([SWS_CRYPT_50017]).

Gelijktijdigheid en beperkingen

De zuiver virtuele methode is gedeclareerd als noexcept, biedt exceptieveiligheid en is expliciet gespecificeerd als thread-safe ([SWS_CRYPT_50017]). Ze kan zodoende zonder externe synchronisatie parallel vanuit meerdere threads worden aangeroepen ([SWS_CRYPT_50017]).

De methode CreateRandomGeneratorCtx dient voor het creëren van een context voor random number generators (RNG) binnen de klasse ara::crypto::cryp::CryptoProvider [SWS_CRYPT_20741].

Gebruik en aanroepcontext

De functie wordt synchroon aangeroepen en vereist het headerbestand ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20741]:

• Parameter: Overgedragen wordt algId van het type AlgId, die het gewenste RNG-algoritme identificeert. Wordt er geen specifieke algId opgegeven, dan levert de methode de standaard-RNG [SWS_CRYPT_20741].
• Retourwaarde: Een ara::core::Result<RandomGeneratorCtx::Sptr> die in geval van succes een shared pointer naar de gecreëerde instantie van RandomGeneratorCtx bevat [SWS_CRYPT_20741].

Foutafhandeling

De methode gooit geen excepties (noexcept) en is gespecificeerd als uitzonderingsveilig [SWS_CRYPT_20741]. Mislukt de bewerking, dan levert de ara::core::Result een foutcode op:

• ara::crypto::CryptoErrc::kUnknownIdentifier: Treedt op wanneer het argument algId een niet-ondersteunde waarde bevat (met rollback-semantiek) [SWS_CRYPT_20741].

Gelijktijdigheid en beperkingen

De methode is geclassificeerd als thread-safe (thread-safe), zodat parallelle aanroepen via dezelfde instantie van de CryptoProvider zijn toegestaan [SWS_CRYPT_20741].

De methode CreateSignerPrivateCtx van de klasse ara::crypto::cryp::CryptoProvider dient voor het aanmaken van een context voor signatuuroperaties met een privésleutel ([SWS_CRYPT_20756]).

Gebruik en parameters: De aanroep vereist het invoegen van het headerbestand ara/crypto/cryp/crypto_provider.h. Via de invoerparameter algId wordt het cryptografische doel-signatuuralgoritme gespecificeerd. Bij succes retourneert de functie via het retourtype ara::core::Result<SignerPrivateCtx::Sptr> een smart pointer naar de aangemaakte contextinstantie ([SWS_CRYPT_20756]). Interpretatie: Aangezien de methode direct een ara::core::Result retourneert, wordt de aanroep vermoedelijk synchroon uitgevoerd. Vraag Q-8480f3cf5cef5f49 (open)

Gelijktijdigheid en veiligheid: De methode is gespecificeerd als thread-safe (thread-safe) en uitzonderingsveilig (exception safe) en is gedeclareerd met noexcept ([SWS_CRYPT_20756]). Ze kan zodoende zonder aanvullende synchronisatie worden aangeroepen vanuit gelijktijdige contexten.

Foutafhandeling: In geval van een fout levert het resultaat een foutcode van het type ara::crypto::CryptoErrc op met rollback-semantiek ([SWS_CRYPT_20756]):

• ara::crypto::CryptoErrc::kInvalidArgument: Treedt op wanneer het argument algId een cryptografisch algoritme aangeeft dat verschilt van een signatuur met een privésleutel ([SWS_CRYPT_20756]).
• ara::crypto::CryptoErrc::kUnknownIdentifier: Treedt op wanneer algId een onbekende of niet-ondersteunde waarde bevat ([SWS_CRYPT_20756]).

Gebruik

De virtuele methode CreateSymmetricCipherCtx van de interface ara::crypto::cryp::CryptoProvider dient voor het creëren van een context voor symmetrische versleutelingsbewerkingen ([SWS_CRYPT_20742]). Deze wordt geïntegreerd via het headerbestand #include "ara/crypto/cryp/crypto_provider.h" ([SWS_CRYPT_20742]).

Als invoerparameter verwacht de functie algId van het type AlgId, die de aanduiding van het gewenste cryptografische doelalgoritme specificeert ([SWS_CRYPT_20742]). De aanroep geschiedt synchroon en levert als resultaat een ara::core::Result<SymmetricCipherCtx::Sptr> op, die bij succes een smart pointer naar de nieuw geïnstantieerde contextinstantie beschikbaar stelt ([SWS_CRYPT_20742]).

Foutafhandeling

Mislukt het creëren, dan bevat de geretourneerde ara::core::Result een overeenkomstige foutcode ([SWS_CRYPT_20742]):

• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt met rollback-semantiek gemeld indien de overgedragen waarde voor algId naar een niet-ondersteund algoritme verwijst ([SWS_CRYPT_20742]).

Gelijktijdigheid en beperkingen

De functie is gedeclareerd als noexcept en expliciet gespecificeerd als uitzonderingsveilig (exception safe) ([SWS_CRYPT_20742]). Bovendien is de aanroep thread-safe (thread-safe), zodat parallelle context-creaties via dezelfde CryptoProvider-instantie zijn toegestaan ([SWS_CRYPT_20742]).

Gebruik

De methode CreateSymmetricKeyWrapperCtx van de klasse ara::crypto::cryp::CryptoProvider dient voor het creëren van een context voor symmetrische key-wrap-algoritmen ([SWS_CRYPT_20743]). Als invoerparameter wordt algId doorgegeven, die het doel-cryptoalgoritme eenduidig identificeert ([SWS_CRYPT_20743]). De aanroep is synchroon en levert bij succes een ara::core::Result terug, die een smart pointer naar de gemaakte context (SymmetricKeyWrapperCtx::Sptr) inkapselt ([SWS_CRYPT_20743]).

Foutafhandeling

Als het creëren mislukt, retourneert de functie het foutobject binnen de ara::core::Result ([SWS_CRYPT_20743]):

• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt gemeld wanneer het argument algId een niet-ondersteunde waarde heeft; hierbij zijn rollback-semantieken van toepassing ([SWS_CRYPT_20743]).

Gelijktijdigheid en beperkingen

De interface is gedeclareerd als noexcept, geldt als exceptieveilig (exception safe) en is thread-safe ([SWS_CRYPT_20743]). Ze kan zodoende veilig vanuit gelijktijdige contexten worden aangeroepen, mits de verstrekte algId door de onderliggende CryptoProvider wordt ondersteund ([SWS_CRYPT_20743]).

Gebruik en aanroepcontext

De puur virtuele methode CreateVerifierPublicCtx van de klasse ara::crypto::cryp::CryptoProvider wordt gedeclareerd via het headerbestand ara/crypto/cryp/crypto_provider.h [SWS_CRYPT_20757]. Ze dient voor het synchroon aanmaken van een context voor signatuurcontrole met openbare sleutels (public-key-signatuurverificatie) [SWS_CRYPT_20757].

De aanroeper geeft via de parameter algId (type AlgId) de identifier van het gewenste crypto-signatuuralgoritme door [SWS_CRYPT_20757]. Bij succes retourneert de functie een ara::core::Result dat een smart pointer naar de aangemaakte verificatiecontext (VerifierPublicCtx::Sptr) bevat [SWS_CRYPT_20757].

Foutafhandeling

In geval van een fout treedt een rollback-semantiek in werking en transporteert het resulterende ara::core::Result een bijbehorende foutcode [SWS_CRYPT_20757]:

• ara::crypto::CryptoErrc::kInvalidArgument: Wordt gemeld wanneer het argument algId een cryptografisch algoritme noemt dat niet is bedoeld voor signatuurcontrole met openbare sleutels [SWS_CRYPT_20757].
• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt gemeld wanneer voor algId een onbekende resp. niet-ondersteunde identifier is doorgegeven [SWS_CRYPT_20757].

Gelijktijdigheid en beperkingen

De methode is gedeclareerd als noexcept, volledig uitzonderingsveilig (exception safe) en expliciet gespecificeerd als thread-safe (thread-safe) [SWS_CRYPT_20757]. Parallelle aanroepen vanuit meerdere uitvoeringscontexten zijn zodoende zonder externe synchronisatie toegestaan.

De methode ExportSecuredKey van de interface ara::crypto::cryp::CryptoProvider exporteert een cryptografisch sleutelobject naar een beveiligd, geserialiseerd formaat [SWS_CRYPT_20728]. Het overgedragen sleutelobject key wordt voorbereid volgens het impliciet door algId vastgelegde formaat, cryptografisch verpakt (“wrapped”) en geserialiseerd naar de uitvoerbuffer resultBuffer [SWS_CRYPT_20728]. Voor het inpakken kan optioneel een Key Encryption Key (kek) worden overgedragen; wordt er geen kek verstrekt, dan valt de methode terug op een impliciet door de algId bepaalde KEK of de standaard-KEK van de CryptoProvider [SWS_CRYPT_20728].

De functie is geclassificeerd als thread-safe en exception safe en geannoteerd met noexcept [SWS_CRYPT_20728]. Interpretatie: Aangezien de signatuur direct een ara::core::Result levert zonder asynchrone retourtypen zoals futures, wordt het gehele inpak- en serialisatieproces vermoedelijk synchroon in de context van de aanroeper uitgevoerd. Vraag Q-3fb89afcc9300695 (open)

Bij een succesvolle afronding levert de geretourneerde ara::core::Result<std::size_t> het aantal in resultBuffer geschreven bytes op [SWS_CRYPT_20728]. Mislukt de bewerking, dan treedt een rollback-semantiek in werking en wordt een van de volgende fouten gemeld [SWS_CRYPT_20728]:

• UnknownIdentifier: De overgedragen algId-waarde wordt niet ondersteund [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kInvalidArgument: Het sleutelobject kan niet worden verpakt (bijv. ongeldige grootte of ongeschikt type) of een verplicht verwachte kek is niet overgedragen [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kUsageViolation: Het toegestane gebruik van key of kek is incompatibel met het gekozen algoritme [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kIncompatibleArguments: De overgedragen kek is incompatibel met het exportalgoritme [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kInsufficientCapacity: De uitvoerbuffer resultBuffer is te klein voor het resultaat [SWS_CRYPT_20728].
• ara::crypto::CryptoErrc::kBusyResource: Een voor de export benodigde resource is bezet [SWS_CRYPT_20728].

De methode GeneratePrivateKey van de klasse ara::crypto::cryp::CryptoProvider (gedeclareerd in ara/crypto/cryp/crypto_provider.h) genereert synchroon een nieuw asymmetrisch sleutelpaar en retourneert de aangemaakte privésleutel als PrivateKey::Sptr binnen een ara::core::Result [SWS_CRYPT_20722]. De bijbehorende openbare sleutel wordt niet direct geretourneerd, maar kan achteraf worden opgevraagd via de methode PrivateKey::GetPublicKey() van de resulterende sleutel [SWS_CRYPT_20722].

Bij de aanroep specificeert de parameter algId het crypto-algoritme, terwijl privateKeyAllowedUsage de toegestane transformatiesoorten voor de privésleutel vastlegt [SWS_CRYPT_20722]. De toegestane gebruiksvlaggen van de openbare sleutel worden daarbij aan de hand van de machtigingen van de privésleutel als volgt gemapt [SWS_CRYPT_20722]:

• kAllowDataDecryption leidt tot kAllowDataEncryption
• kAllowSigGeneration leidt tot kAllowSigVerification
• kAllowKeyAgreement leidt tot kAllowKeyAgreement
• kAllowKeyUnwrapping leidt tot kAllowKeyWrapping

Bovendien worden aan de openbare sleutel automatisch de gebruiksvlaggen kAllowPlaintextExport en kAllowPersist toegewezen [SWS_CRYPT_20722].

Wat betreft gelijktijdigheid en uitvoering is de functie gespecificeerd als thread-safe en exception-safe [SWS_CRYPT_20722]. Treedt tijdens de sleutelgeneratie een fout op, dan wordt het resultaat afgehandeld met rollback-semantiek [SWS_CRYPT_20722]. De volgende foutcodes kunnen worden geretourneerd:

• ara::crypto::CryptoErrc::kUnknownIdentifier, wanneer voor algId een niet-ondersteund algoritme wordt doorgegeven,
• ara::crypto::CryptoErrc::kIncompatibleArguments, indien de opgegeven privateKeyAllowedUsage-vlaggen incompatibel zijn met het gekozen algoritme of sleuteltype,
• ara::crypto::CryptoErrc::kBusyResource, wanneer de generatie vanwege tijdelijk bezette bronnen voorbijgaand niet mogelijk is [SWS_CRYPT_20722].

De puur virtuele methode GenerateRandomData van de interface ara::crypto::cryp::CryptoProvider dient ertoe een door de aanroeper beschikbaar gesteld geheugengebied te vullen met cryptografische toevalsgegevens [SWS_CRYPT_30098]. De declaratie bevindt zich in het headerbestand ara/crypto/cryp/crypto_provider.h.

Als uitvoerparameter wordt randomData van het type ReadWriteMem Region overgedragen, die de te vullen buffer vertegenwoordigt en waarvan de grootte het aantal gegenereerde toevalsbytes bepaalt [SWS_CRYPT_30098]. Interpretatie: Aangezien de functie als retourtype rechtstreeks ara::core::Result<void> en geen Future-object gebruikt, verloopt het genereren van de gegevens vermoedelijk synchroon blokkerend [SWS_CRYPT_30098]. Vraag Q-315c0492dcf7f37d (open) De retourwaarde is bij succes leeg of bevat bij een fout een overeenkomstige foutcode [SWS_CRYPT_30098].

Als er tijdens de uitvoering een probleem optreedt, wordt een rollback-semantiek toegepast, zodat er geen partiële of ongeldige toestanden achterblijven [SWS_CRYPT_30098]. De volgende fouttoestanden zijn gespecificeerd:

• ara::crypto::CryptoErrc::kBusyResource: De onderliggende toevalsgenerator (RNG) beschikt momenteel over onvoldoende entropie en kan de gevraagde hoeveelheid toevalsbytes niet leveren [SWS_CRYPT_30098].
• ara::crypto::CryptoErrc::kUnsupported: De concrete implementatie van de CryptoProvider ondersteunt geen standaard toevalsgenerator [SWS_CRYPT_30098].

Wat betreft gelijktijdigheid en robuustheid is de methode gespecificeerd als thread-safe en exception safe [SWS_CRYPT_30098]. Meerdere threads kunnen de functie zodoende parallel aanroepen, en de noexcept-specificatie garandeert dat er geen C++-excepties over de interfacegrens worden geworpen.

Gebruik

De zuiver virtuele methode GenerateSymmetricKey wordt beschikbaar gesteld via de interface ara::crypto::cryp::CryptoProvider (headerbestand #include "ara/crypto/cryp/crypto_provider.h") en dient voor het genereren van een nieuwe symmetrische sleutel [SWS_CRYPT_20721]. De synchrone aanroep verwacht als parameter algId de identificatie van het symmetrische doel-cryptoalgoritme en als allowedUsage bitflags die de toegestane transformatietypen voor de gegenereerde sleutel vastleggen [SWS_CRYPT_20721]. Bij succesvolle uitvoering levert de methode een ara::core::Result op met een SymmetricKey::Sptr, oftewel een shared pointer naar het nieuw gegenereerde symmetrische sleutelobject [SWS_CRYPT_20721].

Foutafhandeling

Als er tijdens het genereren van de sleutel een fout optreedt, wordt deze doorgegeven in de ara::core::Result. Voor alle gespecificeerde foutgevallen geldt een rollback-semantiek [SWS_CRYPT_20721]:

• ara::crypto::CryptoErrc::kUnknownIdentifier: Wordt gemeld wanneer voor algId een niet-ondersteunde waarde is doorgegeven [SWS_CRYPT_20721].
• ara::crypto::CryptoErrc::kIncompatibleArguments: Treedt op wanneer de opgegeven allowedUsage-flags incompatibel zijn met het gekozen algId-algoritme of het sleuteltype [SWS_CRYPT_20721].
• ara::crypto::CryptoErrc::kBusyResource: Geeft aan dat de bewerking wegens tijdelijk bezette resources tijdelijk niet kan worden uitgevoerd [SWS_CRYPT_20721].

Gelijktijdigheid en beperkingen

De bewerking is gedeclareerd als noexcept en bezit de eigenschappen exceptieveilig (exception safe) en thread-safe (thread-safe) te zijn [SWS_CRYPT_20721]. Zij kan daarom concurrent vanuit meerdere threads worden aangeroepen, waarbij bij hoge systeembelasting de fout kBusyResource kan optreden om tijdelijke knelpunten te signaleren [SWS_CRYPT_20721].

De methode GetSecureCounter() van de klasse ara::crypto::cryp::CryptoProvider (gedeclareerd in #include "ara/crypto/cryp/crypto_provider.h") vraagt de actuele tellerstand van de beveiligde teller van de provider-instantie op [SWS_CRYPT_20098]. De functie werkt synchroon en vereist geen invoerparameters [SWS_CRYPT_20098]. Bij succes retourneert zij via ara::core::Result<SecureCounter> de structuur SecureCounter, die bestaat uit twee niet-ondertekende 64-bit-waarden (LSQW voor Least Significant Quad Word en MSQW voor Most Significant Quad Word) [SWS_CRYPT_20098]. Er wordt gegarandeerd dat elke geretourneerde tellerstand strikt groter is dan alle eerder via deze instantie geleverde waarden [SWS_CRYPT_20098].

Kan de tellerstand niet worden bepaald, dan mislukt de aanroep en levert deze een foutcode met rollback-semantiek op in het Result-object [SWS_CRYPT_20098]:

• ara::crypto::CryptoErrc::kUnsupported: De specifieke CryptoProvider ondersteunt geen beveiligde teller [SWS_CRYPT_20098].
• ara::crypto::CryptoErrc::kBusyResource: Een voor de toegang tot of het bijwerken van de teller benodigde resource is momenteel bezet [SWS_CRYPT_20098].

Wat betreft gelijktijdigheid en robuustheid is de functie gespecificeerd als thread-safe (thread-safe) en als uitzonderingsveilig (exception safe) gedeclareerd met noexcept [SWS_CRYPT_20098]. Parallelle aanroepen vanuit meerdere threads zijn derhalve toegestaan zonder externe synchronisatie, waarbij de strikte monotoniciteit van de geleverde tellerwaarden gewaarborgd blijft [SWS_CRYPT_20098].

Gebruik

De methode ImportPrivateKey van de klasse ara::crypto::cryp::CryptoProvider dient voor het synchroon importeren van een geserialiseerde privésleutel [SWS_CRYPT_50132]. Bij de aanroep worden de payloadgegevens via het geheugengebied serialized (ReadOnlyMemRegion) doorgegeven, aangevuld met de gewenste gebruiksbeperkingen (allowedUsage) en het serialisatieformaat (formatId). De parameter algId is optioneel (ara::core::Optional<AlgId>) en hoeft alleen te worden ingesteld als het gekozen formaat de vereiste sleuteleigenschappen niet reeds zelf eenduidig definieert [SWS_CRYPT_50132]. Als retourwaarde levert de functie een ara::core::Result<PrivateKey::Sptr>, die bij succes een shared pointer naar het aangemaakte sleutelobject bevat.

Foutafhandeling

In geval van een fout waarborgt de methode dat rollback-semantiek van kracht is [SWS_CRYPT_50132]. De volgende foutcodes kunnen via de Result worden geretourneerd:

• InvalidArgument: De geserialiseerde gegevens in serialized komen niet overeen met het opgegeven formaat [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kIncompatibleArguments: De doorgegeven allowedUsage zijn incompatibel met de algId [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kUnsupported: De functie wordt niet ondersteund door de concrete provider [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kBusyResource: De operatie kan tijdelijk niet worden uitgevoerd vanwege bezette bronnen [SWS_CRYPT_50132].
• ara::crypto::CryptoErrc::kUnsupportedFormat: De formatId wordt niet ondersteund voor dit objecttype [SWS_CRYPT_50132].

Gelijktijdigheid en beperkingen

De interface is gedeclareerd als noexcept en biedt uitzonderingsveiligheid (exception safe) en thread-veiligheid (thread-safe) [SWS_CRYPT_50132]. Aanroepen kunnen derhalve parallel vanuit verschillende threads plaatsvinden.

Gebruik

De methode ImportPublicKey dient voor het importeren van een geserialiseerde publieke sleutel in de desbetreffende ara::crypto::cryp::CryptoProvider [SWS_CRYPT_20732]. De aanroep vindt synchroon plaats en levert een ara::core::Result<PublicKey::Sptr> op, die in geval van succes een smart pointer naar het gecreëerde sleutelobject bevat [SWS_CRYPT_20732].

Bij de aanroep worden de volgende parameters doorgegeven [SWS_CRYPT_20732]:

• serialized: Een ReadOnlyMemRegion-geheugengebied dat de ruwe gegevens van de geserialiseerde sleutel levert.
• allowedUsage: De toegestane gebruiksvlaggen (AllowedUsageFlags) voor de geïmporteerde sleutel.
• formatId: De identifier van het serialisatieformaat (FormatId).
• algId: Een optionele algoritme-ID (ara::core::Optional<AlgId>). Deze is niet vereist wanneer het serialisatieformaat de eigenschappen van de sleutel reeds eenduidig bepaalt.

Foutafhandeling

Treedt er bij de verwerking een fout op, dan wordt deze ingekapseld in de geretourneerde ara::core::Result. De volgende foutcodes zijn gespecificeerd [SWS_CRYPT_20732]:

• InvalidArgument: De overgedragen gegevens in serialized komen niet overeen met het opgegeven formaat.
• ara::crypto::CryptoErrc::kIncompatibleArguments: De gebruiksvlaggen allowedUsage zijn incompatibel met algId.
• ara::crypto::CryptoErrc::kUnsupportedFormat: De opgegeven formatId wordt voor dit objecttype niet ondersteund.
• ara::crypto::CryptoErrc::kUnsupported: De gevraagde functie wordt niet ondersteund door de CryptoProvider.
• ara::crypto::CryptoErrc::kBusyResource: De bewerking kan tijdelijk niet worden uitgevoerd.

Concurrency en veiligheid

De methode is gedeclareerd als noexcept, geldt als exception-safe en is volgens de specificatie thread-safe gespecificeerd [SWS_CRYPT_20732]. Foutsituaties volgen gedefinieerde rollback-semantieken [SWS_CRYPT_20732].

Gebruik

De methode ImportSymmetricKey van de interface ara::crypto::cryp::CryptoProvider dient voor het importeren van een geserialiseerde symmetrische sleutel [SWS_CRYPT_50014]. Als teruggeefwaarde levert zij een ara::core::Result<SymmetricKey::Sptr> op, die bij succes een smart pointer naar het nieuw geïnstantieerde sleutelobject levert [SWS_CRYPT_50014]. Aangezien er geen asynchroon teruggeeftype zoals een Future wordt gebruikt, vindt de uitvoering vermoedelijk synchroon plaats. Vraag Q-720a495b07c4f31d (open)

Bij het aanroepen moeten de volgende parameters worden meegegeven [SWS_CRYPT_50014]:

• serialized (ReadOnlyMemRegion): Het geheugengebied dat de geserialiseerde sleutelgegevens bevat.
• allowedUsage (AllowedUsageFlags): Bitmasker van de voor deze sleutel toegestane operaties en toepassingen.
• formatId (FormatId): Identifier van het serialisatieformaat van de sleutelgegevens.
• algId (ara::core::Optional<AlgId>): Optionele algoritme-identifier; deze is niet vereist indien het opgegeven serialisatieformaat alle vereiste eigenschappen van de sleutel al eenduidig bepaalt.

Foutafhandeling en randvoorwaarden

De methode is gespecificeerd als thread-safe en exception safe [SWS_CRYPT_50014]. Bij een fout waarborgt de implementatie een rollback-semantiek en retourneert zij een overeenkomstige foutcode in ara::core::Result [SWS_CRYPT_50014]:

• InvalidArgument: De meegegeven binaire gegevens in serialized komen niet overeen met het opgegeven formaat.
• ara::crypto::CryptoErrc::kIncompatibleArguments: De vastgelegde allowedUsage-vlaggen zijn incompatibel met de opgegeven algId.
• ara::crypto::CryptoErrc::kUnsupported: De functie wordt niet ondersteund door de concrete instantie van de CryptoProvider.
• ara::crypto::CryptoErrc::kUnsupportedFormat: Het gespecificeerde formaat wordt niet ondersteund voor dit sleuteltype.
• ara::crypto::CryptoErrc::kBusyResource: De operatie kan momenteel niet worden uitgevoerd wegens tijdelijk bezette resources.

Gebruik

De methode LoadPrivateKey van de interface ara::crypto::cryp::CryptoProvider laadt een privésleutel uit een bereitgesteld sleutelslot ([SWS_CRYPT_20764]). De aanroep wordt synchroon uitgevoerd en neemt als parameter een shared pointer naar de bronresource (keySlot) aan. Bij succes stelt de functie een shared pointer naar het geladen sleutelobject (PrivateKey::Sptr) bereit, die binnen een ara::core::Result wordt geretourneerd ([SWS_CRYPT_20764]).

Foutafhandeling

Treedt er tijdens de bewerking een fout op, dan treedt een rollback-semantiek in werking en bevat het ara::core::Result een specifieke foutcode ([SWS_CRYPT_20764]):

• ara::crypto::CryptoErrc::kEmptyKeySlot: Het meegegeven sleutelslot is leeg ([SWS_CRYPT_20764]).
• ara::crypto::CryptoErrc::kIncompatibleObject: De onderliggende resource behoort tot een andere, incompatibele CryptoProvider of bevat een afwijkend sleuteltype ([SWS_CRYPT_20764]).
• ara::crypto::CryptoErrc::kBusyResource: De bewerking kan tijdelijk niet worden uitgevoerd ([SWS_CRYPT_20764]).

Concurrency en veiligheid

De specificatie classificeert de functie als thread-safe en exception safe; de signatuur is gedeclareerd als noexcept ([SWS_CRYPT_20764]). Meerdere threads kunnen de methode parallel aanroepen, maar moeten in het geval van tijdelijke resourceconflicten een mogelijke teruggave van kBusyResource afhandelen.

Gebruik

De methode LoadPublicKey van de interface ara::crypto::cryp::CryptoProvider laadt een openbare sleutel uit de bereitgestelde sleutelopslaglocatie [SWS_CRYPT_20763]. Als parameter keySlot verwacht zij een KeySlot::Sptr, die refereert naar de opslaglocatie met de te laden sleutel [SWS_CRYPT_20763]. Als retourwaarde levert de functie een ara::core::Result<PublicKey::Sptr> op, die bij succes een shared pointer naar het geladen openbare-sleutelobject bevat [SWS_CRYPT_20763]. Het direct bereitstellen van de Result-waarde duidt daarbij vermoedelijk op synchroon aanroepgedrag. Vraag Q-e0d2480909b1398a (open)

Foutafhandeling

Mislukt het laadproces, dan bevat het ara::core::Result een overeenkomstige foutcode van het domein ara::crypto::CryptoErrc, waarbij voor alle gespecificeerde foutgevallen een rollback-semantiek is gedefinieerd [SWS_CRYPT_20763]:

• ara::crypto::CryptoErrc::kEmptyKeySlot: Treedt op wanneer de meegegeven KeySlot leeg is [SWS_CRYPT_20763].
• ara::crypto::CryptoErrc::kIncompatibleObject: Wordt geretourneerd wanneer de onderliggende resource tot een andere, incompatibele CryptoProvider behoort of een afwijkend sleuteltype bevat [SWS_CRYPT_20763].
• ara::crypto::CryptoErrc::kBusyResource: Treedt op indien de bewerking tijdelijk niet kan worden uitgevoerd omdat de resource anderszins bezet is [SWS_CRYPT_20763].

Concurrency en veiligheid

De methode is gedeclareerd met noexcept en gespecificeerd als exception-safe [SWS_CRYPT_20763]. Wat betreft concurrency is de bewerking uitdrukkelijk ingedeeld als thread-safe, waardoor parallelle aanroepen vanuit meerdere threads zijn toegestaan [SWS_CRYPT_20763].

De zuiver virtuele methode LoadSymmetricKey van de klasse ara::crypto::cryp::CryptoProvider dient voor het laden van een symmetrische sleutel uit een bereitgestelde sleutelopslaglocatie [SWS_CRYPT_20762]. Als parameter neemt de functie een shared pointer naar de desbetreffende opslaglocatie (keySlot) aan en levert synchroon een ara::core::Result<SymmetricKey::Sptr> terug, die bij succesvolle uitvoering een shared pointer naar het geladen sleutelobject bereitstelt [SWS_CRYPT_20762].

Met betrekking tot concurrency en uitvoeringsveiligheid is de methode gespecificeerd als thread-safe en exception safe en gedeclareerd met noexcept [SWS_CRYPT_20762].

Treedt bij het laden een fout op, dan retourneert de methode via het Result-object specifieke foutcodes uit het domein ara::crypto::CryptoErrc met gedefinieerde rollback-semantiek [SWS_CRYPT_20762]:

• ara::crypto::CryptoErrc::kEmptyKeySlot: Treedt op wanneer de meegegeven KeySlot leeg is [SWS_CRYPT_20762].
• ara::crypto::CryptoErrc::kIncompatibleObject: Wordt geretourneerd indien de onderliggende resource tot een andere, incompatibele Crypto-Provider behoort of een ander sleuteltype bevat [SWS_CRYPT_20762].
• ara::crypto::CryptoErrc::kBusyResource: Signaleert dat de bewerking tijdelijk niet kan worden uitgevoerd [SWS_CRYPT_20762].