klasse ara::crypto::cryp::KeyDecapsulatorPrivateCtx

De interface ara::crypto::cryp::KeyDecapsulatorPrivateCtx dient voor de asymmetrische ontkapseling van sleutelgegevens (Key Encapsulation Mechanism, KEM) voor het genereren van symmetrische doelsleutels [SWS_CRYPT_21412]. Voorafgaand aan de ontkapseling moet de context via SetKey verplicht met een privésleutel of een passend sleutelgeheugenslot worden geïnitialiseerd [SWS_CRYPT_21413]. Aansluitend transformeert de methode Decapsulate de gekapselde gegevens thread- en uitzonderingsveilig naar een nieuwe symmetrische sleutelinstantie [SWS_CRYPT_21412]. Alle interface-aanroepen waarborgen in geval van een fout een strikte rollback-semantiek.

meer ›

Context

De klasse ara::crypto::cryp::KeyDecapsulatorPrivateCtx vormt de gestandaardiseerde interface voor asymmetrische sleutelontkapselingsmechanismen (Key Encapsulation Mechanism, KEM) op basis van privésleutels. Als gespecialiseerde cryptocontext erft zij van CryptoContext en dient zij ertoe om eerder verzonden gekapselde sleutelgegevens met gebruikmaking van een asymmetrische privésleutel te ontkapselen en naar een nieuw symmetrisch sleutelobject (SymmetricKey) te transformeren [SWS_CRYPT_21412].

Bij de ontkapselingsoperatie zijn ten minste drie componenten betrokken: de verzoekende applicatie, de ontkapselingscontext zelf en de sleutelbronnen in de vorm van een PrivateKey [SWS_CRYPT_21413] of een gereferentieerd geheugenslot via KeySlot [SWS_CRYPT_50083]. Na succesvolle ontkapseling stelt de context het gegenereerde symmetrische sleutelobject als smart pointer beschikbaar [SWS_CRYPT_21412].

Contextdiagram: Inpassing van de ontkapselingscontext tussen sleutelverstrekking en generatie van de doelsleutel. Bronnen: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Levenscyclus

De context wordt typisch via de typealias KeyDecapsulatorPrivateCtx::Sptr gereferentieerd en gedeeld als std::shared_ptr [SWS_CRYPT_21401]. Aangezien de interface puur virtuele lidfuncties definieert, vindt de instantiëring van het concrete object vermoedelijk plaats via een bovenliggende cryptofabriek (interpretatie). Vraag Q-870e12aabbad8472 (open) De vernietiging en het opschonen van resources wordt gekoppeld aan de levenscyclus van de smart pointer.

Aanvankelijk bevindt de context zich in een ongeïnitialiseerde toestand, waarin nog geen ontkapselingssleutel is toegewezen. Een directe aanroep van Decapsulate mislukt in deze toestand met de fout UninitializedContext [SWS_CRYPT_21412]. Pas door de succesvolle aanroep van een van de twee overladen methoden SetKey gaat de context over naar de bedrijfsklare toestand [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Wordt een KeySlot toegewezen, dan wordt de daarin aanwezige privésleutel pas dynamisch geraadpleegd op het moment van de daadwerkelijke ontkapseling; wijzigingen in de slotinhoud zijn zodoende vermoedelijk direct van invloed op toekomstige ontkapselingsaanroepen (interpretatie). Vraag Q-0b0dfc1fd3ebbc6f (open)

Wat betreft concurrency en fouttolerantie zijn alle methoden gespecificeerd als thread-veilig (thread-safe) en uitzonderingsveilig (exception safe) [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Omdat de transformatiemethode Decapsulate gedeclareerd is als const, kunnen meerdere threads parallel ontkapselingen op dezelfde geconfigureerde context initiëren [SWS_CRYPT_21412].

Gebruikspad

Het reguliere verloop voor het ontkapselen van een sessiesleutel valt uiteen in twee opeenvolgende fasen:

1. Configuratie van de ontkapselingssleutel: De applicatie configureert de context via SetKey door hetzij een PrivateKey::Sptr over te dragen [SWS_CRYPT_21413] hetzij een KeySlot::Sptr vast te leggen [SWS_CRYPT_50083]. Het resultaat is een ara::core::Result<void> waarvan de status vóór de volgende stap moet worden gecontroleerd.
2. Uitvoering van de ontkapseling: De applicatie roept Decapsulate aan en geeft de buffergegevens van de gekapselde sleutel (ReadOnlyMemRegion encapsulatedKey), de algoritme-identificatie van de doelsleutel (AlgId algId) en de toegestane gebruiksvormen daarvan (AllowedUsageFlags allowedUsage) door [SWS_CRYPT_21412].
3. Resultaatverwerking: Bij een succesvolle transformatie levert de functie een ara::core::Result<SymmetricKey::Sptr> op, waarmee de nieuwe symmetrische sleutel direct bruikbaar is voor opvolgende cryptografische operaties [SWS_CRYPT_21412].

Sequentiediagram: Typisch verloop van sleutelconfiguratie en ontkapseling van een doelsleutel. Bronnen: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Foutscenario's

Alle operaties retourneren fouttoestanden via ara::core::Result en garanderen een strikte rollback-semantiek (rollback_semantics), waardoor de context bij mislukkingen in een geldige toestand blijft [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083].

In het kader van de sleutelconfiguratie via SetKey kunnen de volgende fouten optreden:

• CryptoErrc::kIncompatibleObject: Het overgedragen PrivateKey-object of het KeySlot is incompatibel met de context [SWS_CRYPT_21413], [SWS_CRYPT_50083].
• CryptoErrc::kUsageViolation: De machtigingsflags van de privésleutel bevatten niet het recht op uitpakken (kAllowKeyUnwrapping) [SWS_CRYPT_21413].
• CryptoErrc::kUnsupported: De implementatie van de context ondersteunt uitsluitend de telkens andere configuratievariant (bijv. exclusieve binding via KeySlot of uitsluitend via PrivateKey) [SWS_CRYPT_21413], [SWS_CRYPT_50083].

Bij het aanroepen van Decapsulate zijn de volgende foutoorzaken gespecificeerd:

• UninitializedContext: Aan de context is vooraf geen sleutel toegewezen [SWS_CRYPT_21412].
• CryptoErrc::kInvalidArgument: Het gegevensformaat van de meegegeven buffer encapsulatedKey is ongeldig [SWS_CRYPT_21412].
• CryptoErrc::kUnknownIdentifier: De meegegeven algId-aanduiding wordt niet ondersteund [SWS_CRYPT_21412].
• CryptoErrc::kIncompatibleArguments: Ofwel passen de doelmachtigingen allowedUsage niet bij algId respectievelijk het sleuteltype, ofwel is algId incompatibel met de KEM-gegevens in encapsulatedKey [SWS_CRYPT_21412].
• CryptoErrc::kUsageViolation: De gebruiksregels van de geconfigureerde sleutel staan geen uitpakken toe (kAllowKeyUnwrapping ontbreekt) [SWS_CRYPT_21412].
• CryptoErrc::kEmptyKeySlot: Een eerder via SetKey gekoppeld KeySlot bevat op het moment van uitvoering geen sleutel [SWS_CRYPT_21412].
• CryptoErrc::kBusyResource: Een systeembron die vereist is voor de cryptografische berekening is tijdelijk bezet [SWS_CRYPT_21412].