klasse ara::crypto::cryp::SymmetricKeyWrapperCtx

Gebruik en semantiek

De synchrone lidfunctie SetKey configureert een instantie van ara::crypto::cryp::SymmetricKeyWrapperCtx zodanig dat het doorgegeven object SymmetricKey::Sptr als Key Encryption Key (KEK) voor opeenvolgende sleutelbewerkingen wordt gebruikt [SWS_CRYPT_24018]. De functie is gespecificeerd als pure virtuele methode met noexcept en retourneert een lege ara::core::Result<void>, mits de toewijzing succesvol was [SWS_CRYPT_24018].

Foutafhandeling en rollback

Treedt bij de configuratie een fout op, dan geldt een bindende rollback-semantiek, zodat de toestand van de context ongewijzigd blijft [SWS_CRYPT_24018]. Mogelijke foutoorzaken worden via foutcodes uit ara::crypto::CryptoErrc weergegeven:

• kIncompatibleObject: Het doorgegeven sleutelobject is incompatibel met de symmetrische context [SWS_CRYPT_24018].
• kUsageViolation: Het toegestane gebruik van de sleutel omvat noch kAllowKeyWrapping noch kAllowKeyUnwrapping [SWS_CRYPT_24018].
• kUnsupported: De contextimplementatie ondersteunt uitsluitend het instellen van een sleutel via een KeySlot [SWS_CRYPT_24018].

Gelijktijdigheid en wisselwerking

De methode is gespecificeerd als thread-safe en uitzonderingsveilig (exception safe) [SWS_CRYPT_24018]. Indien sleutels via slots worden beheerd of de context uitsluitend KeySlots ondersteunt, bestaat voor dezelfde wrapper-context de alternatieve overbelasting SetKey met KeySlot::Sptr [SWS_CRYPT_50034]. Deze configureert de context zodanig dat de in het slot opgeslagen sleutel op het uitvoeringstijdstip van de key-wrapping wordt geladen [SWS_CRYPT_50034].

Gebruik

De virtuele methode SetKey configureert de context ara::crypto::cryp::SymmetricKeyWrapperCtx zodanig dat de in het beschikbaar gestelde KeySlot opgeslagen sleutel wordt gebruikt zodra de key wrapping wordt uitgevoerd [SWS_CRYPT_50034]. De aanroep verwacht als parameter keySlot een KeySlot::Sptr die een symmetrische sleutel bevat [SWS_CRYPT_50034]. De functie wordt synchroon aangeroepen, is gedeclareerd met noexcept en retourneert een ara::core::Result<void> [SWS_CRYPT_50034].

Foutafhandeling

In geval van een fout waarborgt de methode rollback-semantiek en retourneert een van de volgende foutresultaten [SWS_CRYPT_50034]:

• ara::crypto::CryptoErrc::kIncompatibleObject: De doorgegeven keySlot is incompatibel met deze context [SWS_CRYPT_50034].
• ara::crypto::CryptoErrc::kUnsupported: De context ondersteunt uitsluitend het instellen van een directe SymmetricKey [SWS_CRYPT_50034].

Concurrency

De bewerking is thread-veilig (thread-safe) en biedt gegarandeerde exception-veiligheid (exception safe) [SWS_CRYPT_50034].

Samenspel

De interface vormt binnen SymmetricKeyWrapperCtx de slotgebaseerde tegenhanger van de overbelasting SetKey met SymmetricKey::Sptr, die een sleutel direct bindt als Key Encryption Key (KEK) [SWS_CRYPT_24018]. Analoge slotgebaseerde configuratiefuncties worden ook gebruikt in verwante cryptografische contexten zoals KeyDerivationFunctionCtx [SWS_CRYPT_50010], KeyEncapsulatorPublicCtx [SWS_CRYPT_50012], VerifierPublicCtx [SWS_CRYPT_50018], MessageAuthnCodeCtx [SWS_CRYPT_50026] en SignerPrivateCtx [SWS_CRYPT_50036].

De methode UnwrapSymmetricKey van de interface ara::crypto::cryp::SymmetricKeyWrapperCtx ontsleutelt een verpakte sleutel met gebruikmaking van de vooraf ingestelde Key Encryption Key (KEK) en levert een nieuw SymmetricKey-object terug [SWS_CRYPT_24016]. Als parameters accepteert de synchrone functie de invoerbuffer met de beschermde sleutelgegevens (wrappedKey), de algoritme-identificatie voor de doelsleutel (targetAlgId) en bit-flags voor de toegestane transformatiesoorten daarvan (allowedUsage) [SWS_CRYPT_24016].

De retourwaarde ara::core::Result<SymmetricKey::Sptr> bevat bij succesvolle uitvoering een smart pointer naar de gegenereerde sleutel of signaleert een fout met rollback-semantiek [SWS_CRYPT_24016]. Mogelijke foutoorzaken zijn:

• InvalidArgument: De overgedragen sleutelgegevens in wrappedKey kunnen niet worden uitgepakt, bijvoorbeeld vanwege een ongeldig formaat of een onjuiste buffergrootte [SWS_CRYPT_24016].
• ara::crypto::CryptoErrc::kUninitializedContext: De wrapper-context is nog niet geïnitialiseerd met een passende KEK [SWS_CRYPT_24016].
• ara::crypto::CryptoErrc::kUsageViolation: De gebruiksbeperkingen van de KEK verbieden het uitpakken (ontbreken van kAllowKeyUnwrapping) [SWS_CRYPT_24016].
• ara::crypto::CryptoErrc::kUnknownIdentifier: De overgedragen waarde voor targetAlgId is niet bekend of wordt niet ondersteund [SWS_CRYPT_24016].
• ara::crypto::CryptoErrc::kIncompatibleArguments: De opgegeven allowedUsage-flags zijn incompatibel met targetAlgId of het sleuteltype [SWS_CRYPT_24016].
• ara::crypto::CryptoErrc::kBusyResource: Een voor de operatie benodigde systeemresource is momenteel bezet [SWS_CRYPT_24016].
• ara::crypto::CryptoErrc::kEmptyKeySlot: Een voor de operatie geconfigureerde KeySlot is leeg [SWS_CRYPT_24016].

De methode is gedeclareerd als const en noexcept, garandeert exception-veiligheid en is volgens de specificatie thread-safe voor gelijktijdige aanroepen [SWS_CRYPT_24016].

Gebruik

De methode Wrap van de klasse ara::crypto::cryp::SymmetricKeyWrapperCtx (headerbestand ara/crypto/cryp/symmetric_key_wrapper_ctx.h) verpakt een beschikbaar gestelde sleutel met gebruikmaking van de vooraf ingestelde sleutelversleutelingssleutel (Key Encryption Key) [SWS_CRYPT_24014].

De synchrone functie verwacht de volgende parameters [SWS_CRYPT_24014]:

• key (CryptoObject::Sptr): De in te pakken sleutel.
• wrappedKey (ReadWriteMemRegion): Een uitvoerbuffer waarin de verpakte sleutel wordt geschreven.

Als retourwaarde levert de operatie een ara::core::Result<std::size_t> op, die bij succes het aantal in de buffer geschreven bytes van de verpakte sleutel bevat [SWS_CRYPT_24014].

Foutafhandeling en semantiek

De methode is gedefinieerd als exception safe en implementeert voor foutgevallen een strikte rollback-semantiek [SWS_CRYPT_24014]. De volgende fouttoestanden kunnen worden gemeld [SWS_CRYPT_24014]:

• InvalidArgument: Het sleutelobject kan niet worden verpakt (bijv. vanwege een ongeldige grootte of een onjuist type).
• ara::crypto::CryptoErrc::kUninitializedContext: De context is nog niet geïnitialiseerd met een sleutelwaarde.
• ara::crypto::CryptoErrc::kUsageViolation: Het toegestane gebruik van de KEK omvat niet kAllowKeyWrapping of dat van het object omvat niet kAllowSecuredExport.
• ara::crypto::CryptoErrc::kInsufficientCapacity: De uitvoerbuffer wrappedKey is te klein.
• ara::crypto::CryptoErrc::kBusyResource: Een benodigde resource is bezet.
• ara::crypto::CryptoErrc::kEmptyKeySlot: Een geconfigureerde KeySlot is momenteel leeg.

Gelijktijdigheid en beperkingen

De interface is gespecificeerd als thread-safe [SWS_CRYPT_24014]. Voorwaarde voor de uitvoering is een vooraf geïnitialiseerde context alsmede passende gebruiksattributen van de betrokken sleutels [SWS_CRYPT_24014].