Enables the secure wrapping and unwrapping of keys by means of symmetric key encryption.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 16126e8d9692ProvenanceOpen questions (1)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
Enables the secure wrapping and unwrapping of keys by means of symmetric key encryption.
The context SymmetricKeyWrapperCtx serves for the cryptographic wrapping and unwrapping of keys using symmetric algorithms. Prior to executing Wrap or UnwrapSymmetricKey, the context must be configured with a compatible key encryption key (KEK) via SetKey[SWS_CRYPT_24018]. All operations require corresponding usage permissions of the involved key objects and report errors via ara::core::Result with rollback semantics [SWS_CRYPT_24014]. The interface is exception-safe and specified as thread-safe for concurrent operation.
Context
The class SymmetricKeyWrapperCtx defines the standardized interface for symmetric key wrapping algorithms within the AUTOSAR Adaptive Platform. Its central responsibility consists in the cryptographic protection of keys during export as well as in restoring wrapped keys for internal use. In doing so, the class primarily interacts with key encryption keys (KEK) that are provided either as a volatile key object of type SymmetricKey or persistently via a KeySlot[SWS_CRYPT_24018], [SWS_CRYPT_50034]. During wrapping, the context accepts a generic CryptoObject[SWS_CRYPT_24014], whereas the unwrapping operation creates and returns a new, ready-to-use SymmetricKey object [SWS_CRYPT_24016].
Lifecycle
Instances of SymmetricKeyWrapperCtx are managed via the typed smart pointer Sptr (an alias for std::shared_ptr<SymmetricKeyWrapperCtx>) [SWS_CRYPT_24001]. The actual object creation is likely performed via a responsible provider factory, as the class represents an abstract interface with pure virtual methods. Question Q-7b9a1007da43ddcd (open) All member functions of the interface are specified as exception-safe as well as thread-safe, which enables safe use in concurrent software components [SWS_CRYPT_24014], [SWS_CRYPT_24016].
During its lifecycle, the context passes through two main phases: Immediately after instantiation, it is in an uninitialized state. In this phase, cryptographic operations and buffer calculations fail with the error kUninitializedContext[SWS_CRYPT_50035], [SWS_CRYPT_24014]. Only upon the successful call of SetKey with a compatible KEK or KeySlot does the context transition to the operational state in which keys can be securely wrapped or unwrapped [SWS_CRYPT_24018], [SWS_CRYPT_50034].
Usage Path
The regular procedure for wrapping a key requires a coordinated sequence of configuration, buffer verification, and execution. First, the application configures the context via SetKey with the desired KEK object [SWS_CRYPT_24018] or binds a corresponding KeySlot[SWS_CRYPT_50034]. In the second step, the application determines the maximum required output buffer size for the target object to be wrapped via GetRequiredWrappedKeyBufferSize[SWS_CRYPT_50035]. After a correspondingly sized memory area (ReadWriteMemRegion) has been provided, Wrap is called, which writes the serialized and encrypted key data into the buffer and returns the exact number of bytes [SWS_CRYPT_24014].
For the complementary process of unwrapping, the application passes the input buffer containing the wrapped data to UnwrapSymmetricKey after configuration via SetKey[SWS_CRYPT_24016]. In doing so, the target algorithm identifier (targetAlgId) and the permitted usage flags (allowedUsage) for the symmetric key to be newly created must be explicitly specified [SWS_CRYPT_24016].
Error Scenarios
Methods of the class signal errors via the return type ara::core::Result with rollback semantics. Central error scenarios include:
Missing initialization: If GetRequiredWrappedKeyBufferSize, Wrap, or UnwrapSymmetricKey are called before a successful key assignment, they return ara::crypto::CryptoErrc::kUninitializedContext[SWS_CRYPT_50035], [SWS_CRYPT_24014], [SWS_CRYPT_24016].
Violation of usage rights: When setting the KEK, it must possess at least the permission kAllowKeyWrapping or kAllowKeyUnwrapping; otherwise, SetKey fails with ara::crypto::CryptoErrc::kUsageViolation[SWS_CRYPT_24018]. For Wrap, the absence of kAllowKeyWrapping on the KEK or the absence of kAllowSecuredExport on the object to be wrapped likewise leads to kUsageViolation[SWS_CRYPT_24014]. During unwrapping, a check is performed to determine whether the KEK permits kAllowKeyUnwrapping[SWS_CRYPT_24016].
Incompatibilities and buffer errors: If the target buffer for Wrap is too small, ara::crypto::CryptoErrc::kInsufficientCapacity is reported [SWS_CRYPT_24014]. Faulty key formats or incompatible types lead to ara::crypto::CryptoErrc::kInvalidArgument[SWS_CRYPT_24014], [SWS_CRYPT_24016]. If the context only supports slots or only key objects, SetKey reports the error kUnsupported[SWS_CRYPT_24018], [SWS_CRYPT_50034].
Resource conflicts and empty slots: If the operation accesses a busy resource, ara::crypto::CryptoErrc::kBusyResource is returned; if the referenced KeySlot is empty, this results in ara::crypto::CryptoErrc::kEmptyKeySlot[SWS_CRYPT_24014], [SWS_CRYPT_24016].
This guide was created by an AI and relies exclusively on the AUTOSAR specification.
Configure the context to use the provided key as key encryption key.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: d0a83598653dProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
Usage and Semantics
The synchronous member function SetKey configures an instance of ara::crypto::cryp::SymmetricKeyWrapperCtx such that the passed object SymmetricKey::Sptr is used as a Key Encryption Key (KEK) for subsequent key operations [SWS_CRYPT_24018]. The function is specified as a pure virtual method with noexcept and returns an empty ara::core::Result<void> if the assignment was successful [SWS_CRYPT_24018].
Error Handling and Rollback
If an error occurs during configuration, mandatory rollback semantics apply, ensuring that the state of the context remains unchanged [SWS_CRYPT_24018]. Possible error causes are mapped via error codes from ara::crypto::CryptoErrc:
kIncompatibleObject: The passed key object is incompatible with the symmetric context [SWS_CRYPT_24018].
kUsageViolation: The permitted usage of the key includes neither kAllowKeyWrapping nor kAllowKeyUnwrapping[SWS_CRYPT_24018].
kUnsupported: The context implementation exclusively supports setting a key via a KeySlot[SWS_CRYPT_24018].
Concurrency and Interaction
The method is specified as thread-safe and exception safe [SWS_CRYPT_24018]. If keys are managed via slots or the context exclusively supports KeySlots, the alternative overload SetKey with KeySlot::Sptr exists for the same wrapper context [SWS_CRYPT_50034]. This configures the context to load the key stored in the slot at the execution time of the key wrapping [SWS_CRYPT_50034].
This usage note is based on the specification AUTOSAR Adaptive Platform Release R25-11.
Configure the context to use the key stored in the provided KeySlot at the time the key wrapping is performed.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 30d79040bb46Provenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The virtual method SetKey configures the context ara::crypto::cryp::SymmetricKeyWrapperCtx such that the key stored in the provided KeySlot is used as soon as key wrapping is executed [SWS_CRYPT_50034]. The call expects as parameter keySlot a KeySlot::Sptr containing a symmetric key [SWS_CRYPT_50034]. The function is called synchronously, is declared with noexcept, and returns a ara::core::Result<void>[SWS_CRYPT_50034].
Error handling
In case of error, the method ensures rollback semantics and returns one of the following error results [SWS_CRYPT_50034]:
ara::crypto::CryptoErrc::kIncompatibleObject: The passed keySlot is incompatible with this context [SWS_CRYPT_50034].
ara::crypto::CryptoErrc::kUnsupported: The context exclusively supports setting a direct SymmetricKey[SWS_CRYPT_50034].
Concurrency
The operation is thread-safe and offers guaranteed exception safety (exception safe) [SWS_CRYPT_50034].
Interaction
Within SymmetricKeyWrapperCtx, the interface represents the slot-based counterpart to overload SetKey with SymmetricKey::Sptr, which binds a key directly as Key Encryption Key (KEK) [SWS_CRYPT_24018]. Analogous slot-based configuration functions are also used in related cryptographic contexts such as KeyDerivationFunctionCtx[SWS_CRYPT_50010], KeyEncapsulatorPublicCtx[SWS_CRYPT_50012], VerifierPublicCtx[SWS_CRYPT_50018], MessageAuthnCodeCtx[SWS_CRYPT_50026], and SignerPrivateCtx[SWS_CRYPT_50036].
This usage note was generated automatically based on the specification of AUTOSAR Adaptive R25-11.
Unwrap a wrapped key using the previously set key encryption key and return an SymmetricKey.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: fe87df5f5eaeProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The method UnwrapSymmetricKey of interface ara::crypto::cryp::SymmetricKeyWrapperCtx decrypts a wrapped key using the previously set key encryption key (KEK) and returns a new SymmetricKey object [SWS_CRYPT_24016]. As parameters, the synchronous function accepts the input buffer with the protected key data (wrappedKey), the algorithm identifier for the target key (targetAlgId), and bit flags for its permitted transformation types (allowedUsage) [SWS_CRYPT_24016].
Upon successful execution, the return value ara::core::Result<SymmetricKey::Sptr> contains a smart pointer to the generated key or signals an error with rollback semantics [SWS_CRYPT_24016]. Possible error causes are:
InvalidArgument: The passed key data in wrappedKey cannot be unpacked, for instance due to an invalid format or an incorrect buffer size [SWS_CRYPT_24016].
ara::crypto::CryptoErrc::kUninitializedContext: The wrapper context has not yet been initialized with a matching KEK [SWS_CRYPT_24016].
ara::crypto::CryptoErrc::kUsageViolation: The usage restrictions of the KEK prohibit unwrapping (absence of kAllowKeyUnwrapping) [SWS_CRYPT_24016].
ara::crypto::CryptoErrc::kUnknownIdentifier: The passed value for targetAlgId is not known or is not supported [SWS_CRYPT_24016].
ara::crypto::CryptoErrc::kIncompatibleArguments: The specified allowedUsage flags are incompatible with targetAlgId or the key type [SWS_CRYPT_24016].
ara::crypto::CryptoErrc::kBusyResource: A system resource required for the operation is currently busy [SWS_CRYPT_24016].
ara::crypto::CryptoErrc::kEmptyKeySlot: A KeySlot configured for the operation is empty [SWS_CRYPT_24016].
The method is declared as const and noexcept, guarantees exception safety, and is thread-safe for concurrent calls according to the specification [SWS_CRYPT_24016].
This text was created by an AI and serves as an orientation guide. Authoritative is the specification.
Wrap the provided key using the previously set key encryption key.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 8e6ff8198c9dProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The method Wrap of class ara::crypto::cryp::SymmetricKeyWrapperCtx (header file ara/crypto/cryp/symmetric_key_wrapper_ctx.h) packs a provided key using the previously set key encryption key (Key Encryption Key) [SWS_CRYPT_24014].
The synchronous function expects the following parameters [SWS_CRYPT_24014]:
key (CryptoObject::Sptr): The key to be wrapped.
wrappedKey (ReadWriteMemRegion): An output buffer into which the wrapped key is written.
As return value, the operation returns a ara::core::Result<std::size_t> that, in case of success, contains the number of bytes of the wrapped key written to the buffer [SWS_CRYPT_24014].
Error Handling and Semantics
The method is defined as exception safe and implements strict rollback semantics for error cases [SWS_CRYPT_24014]. The following error states can be reported [SWS_CRYPT_24014]:
InvalidArgument: The key object cannot be wrapped (e.g. due to invalid size or incorrect type).
ara::crypto::CryptoErrc::kUninitializedContext: The context has not yet been initialized with a key value.
ara::crypto::CryptoErrc::kUsageViolation: The permitted usage of the KEK does not include kAllowKeyWrapping, or that of the object does not include kAllowSecuredExport.
ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer wrappedKey is too small.
ara::crypto::CryptoErrc::kBusyResource: A required resource is busy.
ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently empty.
Concurrency and Limitations
The interface is specified as thread-safe[SWS_CRYPT_24014]. Prerequisites for execution are a previously initialized context as well as matching usage attributes of the involved keys [SWS_CRYPT_24014].
This usage note was generated automatically based on the specification of AUTOSAR Adaptive R25-11.
rollback_semantics if the allowed usage of the KEK does not include kAllowKey Wrapping or the allowed usage of the object does not include k AllowSecuredExport
gemini-3.8-flash-low· 2026-10-13 · German original