class ara::crypto::cryp::KeyDerivationFunctionCtx

Interface ara::crypto::cryp::KeyDerivationFunctionCtx serves to derive new symmetric keys from existing key material and configurable context parameters such as salts or counters [SWS_CRYPT_21515]. Prior to key generation using DeriveKey, the context must be initialized with a key or KeySlot via SetKey and optionally configured via SetParameter [SWS_CRYPT_21525]. As an essential security condition, derivation may take place only if the source key material is explicitly authorized for KDF operations and the required usage flags of the target key are compatible.

more ›

Context

Class ara::crypto::cryp::KeyDerivationFunctionCtx provides the interface for Key Derivation Functions (KDF) in the crypto module of AUTOSAR Adaptive. Its primary task is to derive new symmetric keys from provided key material and configurable context parameters [SWS_CRYPT_21515].

Typical interaction partners are calling application services, the underlying source material in the form of a SymmetricKey [SWS_CRYPT_21525] or a KeySlot [SWS_CRYPT_50010], and the result of the derivation in the form of a new SymmetricKey::Sptr [SWS_CRYPT_21515]. Additional cryptographic parameters can be passed as memory regions, integers, or auxiliary keys [SWS_CRYPT_50007] [SWS_CRYPT_50008] [SWS_CRYPT_50009].

Lifecycle

The lifetime and ownership of instances are controlled via the typed smart pointer ara::crypto::cryp::KeyDerivationFunctionCtx::Sptr [SWS_CRYPT_21501]. The creation of a concrete implementation instance is likely performed via a specialized factory or the responsible CryptoProvider, since the class defines a pure virtual interface. Question Q-8ba3d498c9921ab1 (open)

A newly created context is initially in an incomplete state. Only after successful assignment of a key via SetKey [SWS_CRYPT_21525] [SWS_CRYPT_50010] and the setting of required KDF parameters via SetParameter [SWS_CRYPT_50007] [SWS_CRYPT_50008] [SWS_CRYPT_50009] is the context ready for computation. Regarding concurrency, the interface methods are declared thread-safe and exception-safe ([SWS_CRYPT_21515], [SWS_CRYPT_21525], [SWS_CRYPT_50007]).

Usage Path

The typical call sequence for key derivation comprises three consecutive phases:

1. Assign base key: The source key material is configured via SetKey. Either an existing key object (SymmetricKey::Sptr) [SWS_CRYPT_21525] or a persistent key slot (KeySlot::Sptr) [SWS_CRYPT_50010] can be passed here.
2. Configure context parameters: KDF-specific values such as salt, initialization vectors, or iteration counters are defined via SetParameter. Supported types include memory buffers (ReadOnlyMemRegion) [SWS_CRYPT_50007], 64-bit integers (std::uint64_t) [SWS_CRYPT_50008], and additional symmetric keys (SymmetricKey::Sptr) [SWS_CRYPT_50009].
3. Derive target key: Calling DeriveKey performs the cryptographic computation [SWS_CRYPT_21515]. The method expects the target algorithm identifier (AlgId) as well as the allowed usage flags (AllowedUsageFlags) and, in case of success, returns a SymmetricKey::Sptr.

Sequence diagram: Typical call sequence for deriving a symmetric key via KeyDerivationFunctionCtx. Sources: [SWS_CRYPT_21525], [SWS_CRYPT_50007], [SWS_CRYPT_21515].

Error Scenarios

The interface methods signal error cases via ara::core::Result using defined error codes:

• Incomplete initialization: If DeriveKey is called without sufficient configuration, the call fails with ara::crypto::CryptoErrc::kUninitializedContext [SWS_CRYPT_21515]. If an assigned KeySlot is empty at execution time, ara::crypto::CryptoErrc::kEmptyKeySlot is reported [SWS_CRYPT_21515].
• Violation of usage rights: The source key must permit the operation kAllowKeyDerivation; otherwise, ara::crypto::CryptoErrc::kUsageViolation is triggered ([SWS_CRYPT_21525], [SWS_CRYPT_21515], [SWS_CRYPT_50009]). If the target includes kAllowPlaintextExport, the source key must additionally exhibit kAllowDerivedPlaintextExport; otherwise, kUsageViolation likewise results [SWS_CRYPT_21515].
• Incompatibility and invalid arguments: An unsupported target algorithm yields UnknownIdentifier, and mutually incompatible usage flags produce ara::crypto::CryptoErrc::kIncompatibleArguments [SWS_CRYPT_21515]. SetKey acknowledges key objects or KeySlots that are unsuitable for the context with ara::crypto::CryptoErrc::kIncompatibleObject ([SWS_CRYPT_21525], [SWS_CRYPT_50010]). Invalid parameter values lead to ara::crypto::CryptoErrc::kInvalidArgument ([SWS_CRYPT_50007], [SWS_CRYPT_50008]).
• Unsupported interface functions: If a concrete implementation exclusively supports KeySlot or exclusively supports SymmetricKey, the respective other SetKey call leads to ara::crypto::CryptoErrc::kUnsupported ([SWS_CRYPT_21525], [SWS_CRYPT_50010]). Unknown parameter names for SetParameter likewise produce kUnsupported ([SWS_CRYPT_50007], [SWS_CRYPT_50008], [SWS_CRYPT_50009]).
• Resource conflicts: If a crypto resource required for the computation is locked, DeriveKey signals the error code ara::crypto::CryptoErrc::kBusyResource [SWS_CRYPT_21515].