class ara::crypto::cryp::KeyDecapsulatorPrivateCtx

The interface ara::crypto::cryp::KeyDecapsulatorPrivateCtx serves for the asymmetric decapsulation of key data (Key Encapsulation Mechanism, KEM) to generate symmetric target keys [SWS_CRYPT_21412]. Prior to decapsulation, the context must mandatorily be initialized with a private key or a matching key storage slot via SetKey [SWS_CRYPT_21413]. Subsequently, the method Decapsulate transforms the encapsulated data in a thread-safe and exception-safe manner into a new symmetric key instance [SWS_CRYPT_21412]. All interface calls ensure strict rollback semantics in the event of an error.

more ›

Context

The class ara::crypto::cryp::KeyDecapsulatorPrivateCtx forms the standardized interface for asymmetric key decapsulation mechanisms (Key Encapsulation Mechanism, KEM) based on private keys. As a specialized crypto context, it inherits from CryptoContext and serves to decapsulate previously transmitted encapsulated key data using an asymmetric private key and transform it into a new symmetric key object (SymmetricKey) [SWS_CRYPT_21412].

At least three components participate in the decapsulation operation: the requesting application, the decapsulation context itself, and the key sources in the form of a PrivateKey [SWS_CRYPT_21413] or a referenced storage slot via KeySlot [SWS_CRYPT_50083]. After successful decapsulation, the context provides the generated symmetric key object as a smart pointer [SWS_CRYPT_21412].

Context diagram: Integration of the decapsulation context between key provisioning and target key generation. Sources: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Lifecycle

The context is typically referenced and shared via the type alias KeyDecapsulatorPrivateCtx::Sptr as std::shared_ptr [SWS_CRYPT_21401]. Since the interface defines pure virtual member functions, the instantiation of the concrete object presumably takes place via a higher-level crypto factory (interpretation). Question Q-870e12aabbad8472 (open) Destruction and resource cleanup are tied to the lifecycle of the smart pointer.

Initially, the context is in an uninitialized state in which no decapsulation key has yet been assigned. A direct call to Decapsulate fails in this state with the error UninitializedContext [SWS_CRYPT_21412]. Only upon the successful call of one of the two overloaded methods SetKey does the context transition to the operational state [SWS_CRYPT_21413], [SWS_CRYPT_50083]. If a KeySlot is assigned, the private key contained therein is only retrieved dynamically at the time of actual decapsulation; thus, modifications to the slot content presumably have an immediate effect on future decapsulation calls (interpretation). Question Q-0b0dfc1fd3ebbc6f (open)

Regarding concurrency and fault tolerance, all methods are specified as thread-safe (thread-safe) and exception-safe (exception safe) [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]. Since the transformation method Decapsulate is declared as const, multiple threads can trigger decapsulations in parallel on the same configured context [SWS_CRYPT_21412].

Usage Path

The regular sequence for decapsulating a session key is divided into two consecutive phases:

1. Configuration of the decapsulation key: The application configures the context via SetKey by either passing a PrivateKey::Sptr [SWS_CRYPT_21413] or providing a KeySlot::Sptr [SWS_CRYPT_50083]. The result is a ara::core::Result<void> whose status must be checked before the next step.
2. Execution of the decapsulation: The application calls Decapsulate and passes the buffer data of the encapsulated key (ReadOnlyMemRegion encapsulatedKey), the algorithm identifier of the target key (AlgId algId), and its permitted usage types (AllowedUsageFlags allowedUsage) [SWS_CRYPT_21412].
3. Result processing: Upon successful transformation, the function returns a ara::core::Result<SymmetricKey::Sptr> through which the new symmetric key can be used directly for subsequent cryptographic operations [SWS_CRYPT_21412].

Sequence diagram: Typical sequence of key configuration and decapsulation of a target key. Sources: [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083]

Error Scenarios

All operations return error states via ara::core::Result and guarantee strict rollback semantics (rollback_semantics), whereby the context remains in a valid state in case of failures [SWS_CRYPT_21412], [SWS_CRYPT_21413], [SWS_CRYPT_50083].

Within the scope of key configuration via SetKey, the following errors can occur:

• CryptoErrc::kIncompatibleObject: The passed PrivateKey object or the KeySlot is incompatible with the context [SWS_CRYPT_21413], [SWS_CRYPT_50083].
• CryptoErrc::kUsageViolation: The permission flags of the private key do not include the permission to unwrap (kAllowKeyUnwrapping) [SWS_CRYPT_21413].
• CryptoErrc::kUnsupported: The implementation of the context supports only the respective other configuration variant (e.g., exclusive binding via KeySlot or exclusively via PrivateKey) [SWS_CRYPT_21413], [SWS_CRYPT_50083].

When calling Decapsulate, the following error causes are specified:

• UninitializedContext: No key has been assigned to the context previously [SWS_CRYPT_21412].
• CryptoErrc::kInvalidArgument: The data format of the passed buffer encapsulatedKey is invalid [SWS_CRYPT_21412].
• CryptoErrc::kUnknownIdentifier: The passed algId identifier is not supported [SWS_CRYPT_21412].
• CryptoErrc::kIncompatibleArguments: Either the target permissions allowedUsage do not match algId or the key type, or algId is incompatible with the KEM data in encapsulatedKey [SWS_CRYPT_21412].
• CryptoErrc::kUsageViolation: The usage rules of the configured key do not allow unwrapping (kAllowKeyUnwrapping missing) [SWS_CRYPT_21412].
• CryptoErrc::kEmptyKeySlot: A KeySlot previously bound via SetKey does not contain a key at the time of execution [SWS_CRYPT_21412].
• CryptoErrc::kBusyResource: A system resource required for the cryptographic computation is temporarily busy [SWS_CRYPT_21412].