class ara::crypto::cryp::KeyAgreementPrivateCtx

The interface ara::crypto::cryp::KeyAgreementPrivateCtx serves to execute cryptographic key agreement procedures based on a local private key and the public key of a peer [SWS_CRYPT_21312]. After setting its own key and optional parameters, the method AgreeKey calculates a shared secret and returns it as a symmetric key object. A central constraint is complete initialization prior to execution, as missing parameters or missing permissions for kAllowKeyAgreement lead to an abort with corresponding error codes [SWS_CRYPT_21312]. All operations are designed to be thread-safe.

more ›

Context

The interface ara::crypto::cryp::KeyAgreementPrivateCtx is used in the crypto module of the Adaptive Platform to execute asymmetric key agreement procedures. Its central responsibility lies in computing a shared symmetric key from a local private key and the public key of a communication partner [SWS_CRYPT_21312]. As a specialized crypto context, the class interacts with several key and storage abstractions: Its own private key can either be bound directly as an PrivateKey object [SWS_CRYPT_21313] or referenced via a KeySlot [SWS_CRYPT_50053]. The peer contributes its public key in the form of a PublicKey, while the result is provided as an independent SymmetricKey object [SWS_CRYPT_21312]. In addition, algorithm-specific configuration parameters can be passed as a memory buffer or integer [SWS_CRYPT_50051], [SWS_CRYPT_50052].

Context diagram: Interaction of KeyAgreementPrivateCtx with keys, key slots, and result object. Sources: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50053].

Lifecycle

The lifecycle and ownership of KeyAgreementPrivateCtx are based on shared pointers; the specification provides the type alias KeyAgreementPrivateCtx::Sptr for this purpose [SWS_CRYPT_21301]. Interpretation: Instantiation is likely done via a higher-level factory of a CryptoProvider, as the class represents a pure virtual interface without a constructor specification. Question Q-22dca518675fba51 (open) After creation, the instance is in a non-operational base state. The context is only initialized once a private key has been configured using SetKey [SWS_CRYPT_21313], [SWS_CRYPT_50053] and all parameters required for the chosen scheme have been assigned [SWS_CRYPT_50051], [SWS_CRYPT_50052].

If a key calculation is initiated before these configuration steps are completed, the call fails [SWS_CRYPT_21312]. Regarding concurrency, all member functions are specified as thread-safe (thread-safe) as well as exception-safe (exception safe) [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Because the execution function AgreeKey is declared as const [SWS_CRYPT_21312], the same initialized context can be used in parallel for agreements with different peers.

Usage Path

Practical usage is divided into a sequential series of configuration and calculation steps:

• Key assignment: First, the application binds its own private key to the context. This is done either via SetKey(PrivateKey::Sptr) [SWS_CRYPT_21313] for a loaded key object or via SetKey(KeySlot::Sptr) [SWS_CRYPT_50053] for a key slot whose content is only evaluated at the time of the agreement.
• Parameter definition: If the target algorithm requires additional initialization data, this is passed via SetParameter as a buffer ReadOnlyMemRegion [SWS_CRYPT_50051] or as a 64-bit integer std::uint64_t [SWS_CRYPT_50052].
• Key agreement: With AgreeKey, the cryptographic algorithm is executed [SWS_CRYPT_21312]. The calling component passes the public key of the peer (otherSideKey), the identifier of the desired target algorithm (targetAlgId), and the permitted usage flags (allowedUsage).
• Result retrieval: Upon successful completion, AgreeKey returns a SymmetricKey object containing the calculated shared secret [SWS_CRYPT_21312].

Sequence diagram: Typical sequence of key agreement from key allocation to generation of the symmetric key. Sources: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051].

Error Scenarios

Methods of KeyAgreementPrivateCtx return errors via ara::core::Result and ensure rollback semantics [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Typical error scenarios include:

• CryptoErrc::kUninitializedContext: Occurs on AgreeKey if no key was set beforehand or required parameters are missing [SWS_CRYPT_21312].
• CryptoErrc::kIncompatibleObject: Reported if a passed PrivateKey or KeySlot does not match the type of the context [SWS_CRYPT_21313], [SWS_CRYPT_50053], or if the peer key otherSideKey is incompatible [SWS_CRYPT_21312].
• CryptoErrc::kUsageViolation: Signals that the permission kAllowKeyAgreement was not granted for the private key or the peer key [SWS_CRYPT_21312], [SWS_CRYPT_21313].
• CryptoErrc::kUnsupported: Indicates that the context implementation exclusively supports the respective other SetKey variant [SWS_CRYPT_21313], [SWS_CRYPT_50053], or that a requested parameter name is not supported [SWS_CRYPT_50051], [SWS_CRYPT_50052].
• CryptoErrc::kInvalidArgument: Arises with invalid values in SetParameter [SWS_CRYPT_50051], [SWS_CRYPT_50052] or impermissible allowedUsage flags for the target key [SWS_CRYPT_21312].
• CryptoErrc::kUnknownIdentifier: Triggered if the identifier targetAlgId for the target algorithm is unknown [SWS_CRYPT_21312].
• CryptoErrc::kEmptyKeySlot and CryptoErrc::kBusyResource: Returned by AgreeKey if the configured KeySlot contains no key at execution time or a required resource is busy [SWS_CRYPT_21312].