Serves for the secure unpacking and importing of protected cryptographic keys and data in an application.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: a42cd9e6f52bProvenanceOpen questions (2)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
Serves for the secure unpacking and importing of protected cryptographic keys and data in an application.
The interface enables the secure unpacking and importing of protected cryptographic data and keys using a configured transport key [SWS_CRYPT_50205]. The unpacked key material can either be written directly to a persistent key slot or loaded into memory as a typed key object [SWS_CRYPT_50207]. All methods operate thread-safely and follow strict rollback error semantics, while Reset ensures the residue-free erasure of internal buffers [SWS_CRYPT_50212].
Context
The interface ara::crypto::cryp::ProtectedKeyImportCtx provides a cryptographic context to securely import and unpack protected data structures such as secret key material into the system. The context acts as an intermediary between a requesting application, a protection mechanism based on a transport key, and the target structures of AUTOSAR cryptography. Incoming serialized data packets are authenticated, decrypted, and parsed by the context [SWS_CRYPT_50207]. Either standalone symmetric key objects [SWS_CRYPT_50205] or key slots of a key storage [SWS_CRYPT_50206] serve as sources for the required transport key. As a sink, unpacked key objects can be passed directly to the calling application or serialized directly into a writable key slot [SWS_CRYPT_50207].
Lifecycle
The context is usually managed for shared access via the provided smart pointer type Sptr[SWS_CRYPT_50085]; instances are likely provided by a responsible crypto driver component. Question Q-3517b24b5eec4529 (open) Prior to actual processing, the context is in an unconfigured initial state in which no transport key is assigned yet. The assignment of a transport key takes place via the method SetKey, whereby the context transitions into the operational state [SWS_CRYPT_50205][SWS_CRYPT_50206].
After successful execution of the operation Import, the context maintains the unpacked data and metadata in internal buffers so that the object type can be identified and key objects can be read out [SWS_CRYPT_50207][SWS_CRYPT_50208]. Via the method Reset, the context is reset back to its initial state: all internal buffers with previously imported data are completely cleared and the stored transport key is removed [SWS_CRYPT_50212]. All interface methods are specified as exception-safe and thread-safe, whereby concurrent accesses from multiple execution contexts remain manageable [SWS_CRYPT_50207].
The regular workflow begins with the configuration of the transport key. For this purpose, the application calls SetKey either with a SymmetricKey::Sptr[SWS_CRYPT_50205] or with a KeySlot::Sptr[SWS_CRYPT_50206]. In the next step, the method Import is executed, to which the serialized data packet is passed as ReadOnlyMemRegion[SWS_CRYPT_50207]. If the key is to be stored persistently, a WriteableKeySlot::Sptr into which the unpacked material is written can optionally be passed directly [SWS_CRYPT_50207].
If no target slot was specified or if the key is to be used transiently, the application determines the category of the most recently imported object via GetCryptoObjectType[SWS_CRYPT_50208]. Based on this type, the application calls the type-appropriate retrieval method: GetPrivateKey for private keys [SWS_CRYPT_50209], GetPublicKey for public keys [SWS_CRYPT_50211], or GetSymmetricKey for symmetric key material [SWS_CRYPT_50210]. If the used import protocol requires a response to the sender—such as with the control blocks M4 and M5 of a SHE LoadKey sequence—this can be written into a provided buffer via GetResponse[SWS_CRYPT_41020]. After completion of the processing sequence, a call to Reset resets the context back to the initial state [SWS_CRYPT_50212].
If an error occurs during a method call, strict rollback semantics take effect that preserve the state prior to the call. During configuration via SetKey, the call fails with CryptoErrc::kUsageViolation if the key's usage flag does not contain the permission kAllowKeyUnwrapping[SWS_CRYPT_50205][SWS_CRYPT_50206]. If the key object or the referenced slot cannot fundamentally be used as a transport key, CryptoErrc::kIncompatibleObject is reported [SWS_CRYPT_50205][SWS_CRYPT_50206].
When calling Import, size discrepancies of the input data lead to CryptoErrc::kInvalidInputSize and format violations lead to CryptoErrc::kInvalidArgument[SWS_CRYPT_50207]. If the integrity or authenticity check of the protection layer fails (e.g. due to an invalid message authentication code or a faulty signature), the call returns CryptoErrc::kAuthTagNotValid[SWS_CRYPT_50207]. If the crypto component is temporarily busy, this is signaled via CryptoErrc::kBusyResource[SWS_CRYPT_50207].
A precondition for reading out imported keys is the successful execution of Import; otherwise GetPrivateKey, GetPublicKey, and GetSymmetricKey respond with CryptoErrc::kProcessingNotFinished[SWS_CRYPT_50209][SWS_CRYPT_50210][SWS_CRYPT_50211]. If the requested key type does not match the actually unpacked object or if no object has been imported yet, the retrieval methods acknowledge this with CryptoErrc::kNoSuchValue[SWS_CRYPT_50208][SWS_CRYPT_50209][SWS_CRYPT_50210][SWS_CRYPT_50211]. If the output buffer does not provide sufficient capacity in GetResponse, this results in CryptoErrc::kInsufficientCapacity[SWS_CRYPT_41020]. If the concrete implementation does not support a sub-function (e.g. certain key types or resetting), CryptoErrc::kUnsupported is consistently returned [SWS_CRYPT_50205][SWS_CRYPT_50208][SWS_CRYPT_50212].
This class guide is based on the specification AUTOSAR Adaptive Platform Release R25-11.
The interface shall write the response of the CryptoProvider to the last invocation of Import into the provided output buffer. E.g., this interface could return M4/M5 of a SHE LoadKey operation.
virtual ara::core::Result< std::size_t > GetResponse (ReadWriteMem Region responseBuffer) const noexcept=0; DIRECTION NOT responseBuffer -- DEFINED
The interface shall unwrap the protected data provided, parse the content, and make the parsed content (key-material and meta-data) available for retrieval by the application. If optionally a Key Slot is specified, the unwrapped key material shall be directly serialized into the KeySlot.
The interface shall restore the context to its initial state by ensuring that no key-import-key is set and all previously imported data is deleted from the ProtectedKeyImportCtx’s internal buffers.
The interface shall return a shared pointer to the unwrapped PrivateKey.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 569ddfa8ee2aProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The method GetPrivateKey of class ara::crypto::cryp::ProtectedKeyImportCtx (provided via the header #include "ara/crypto/cryp/protected_key_import_ctx.h") serves to retrieve a shared pointer to a previously imported and unpacked private key (PrivateKey::Sptr) ([SWS_CRYPT_50209]). The interface has no input parameters and returns the result synchronously as ara::core::Result<PrivateKey::Sptr> ([SWS_CRYPT_50209]).
Binding requirements regarding sequence, concurrency, and exception safety apply to the execution: The method is specified as thread-safe as well as exception safe and declared with noexcept ([SWS_CRYPT_50209]). A mandatory prerequisite for successful retrieval is that an import operation within the context was previously executed successfully ([SWS_CRYPT_50209]).
If an error occurs during provision, rollback semantics apply to all error situations ([SWS_CRYPT_50209]). In this case, the returned Result contains one of the following specific error codes:
ara::crypto::CryptoErrc::kProcessingNotFinished: The preceding import step has not yet been executed successfully ([SWS_CRYPT_50209]).
ara::crypto::CryptoErrc::kNoSuchValue: The most recently imported CryptoObject is not a private key ([SWS_CRYPT_50209]).
ara::crypto::CryptoErrc::kUnsupported: The context generally does not support the import of private keys ([SWS_CRYPT_50209]).
This usage note was created by an AI based on the AUTOSAR specification R25-11.
The interface shall return a shared pointer to the unwrapped PublicKey.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: b41e5e96382cProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The method GetPublicKey of the class ara::crypto::cryp::ProtectedKeyImportCtx serves to synchronously retrieve a pointer to a previously imported, unpacked public key ([SWS_CRYPT_50211]). The function accepts no input parameters and returns the result type-safely as ara::core::Result<PublicKey::Sptr> ([SWS_CRYPT_50211]).
Before the call, an import operation must have completed successfully; otherwise, the call fails and returns the error code ara::crypto::CryptoErrc::kProcessingNotFinished ([SWS_CRYPT_50211]). If the most recently imported crypto object was not a public key, this results in the error ara::crypto::CryptoErrc::kNoSuchValue ([SWS_CRYPT_50211]). If the concrete import context fundamentally does not support introducing public keys, ara::crypto::CryptoErrc::kUnsupported is reported ([SWS_CRYPT_50211]). For all specified errors, the interface guarantees rollback semantics ([SWS_CRYPT_50211]).
Regarding concurrency and error safety, the method is specified as thread-safe as well as exception-safe and does not throw any C++ exceptions (noexcept) ([SWS_CRYPT_50211]).
Functionally, this import mechanism is distinguished from other interfaces: While a protected object is unpacked here, the function of the same name on ara::crypto::cryp::PrivateKey ([SWS_CRYPT_22511]) returns the public key of an existing private key that was, for example, previously generated by means of GeneratePrivateKey ([SWS_CRYPT_20722]).
This text was generated by an AI based on the specification requirements.
virtual ara::core::Result< std::size_t > GetResponse (ReadWriteMem Region responseBuffer) const noexcept=0; DIRECTION NOT responseBuffer -- DEFINED
The interface shall write the response of the CryptoProvider to the last invocation of Import into the provided output buffer. E.g., this interface could return M4/M5 of a SHE LoadKey operation.
The interface shall return a shared pointer to the unwrapped SymmetricKey.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: cefc876d47dbProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The method GetSymmetricKey of class ara::crypto::cryp::ProtectedKeyImportCtx returns a shared pointer to an unpacked symmetric key (SymmetricKey::Sptr) [SWS_CRYPT_50210]. The call is synchronous, is declared as const as well as noexcept, and accepts no parameters [SWS_CRYPT_50210].
Specific preconditions and sequences must be observed for successful retrieval [SWS_CRYPT_50210]:
An import procedure must have been completed successfully beforehand; otherwise, the call fails with the error code ara::crypto::CryptoErrc::kProcessingNotFinished[SWS_CRYPT_50210].
If the most recently imported cryptographic object is not a symmetric key, the method returns ara::crypto::CryptoErrc::kNoSuchValue[SWS_CRYPT_50210].
If the selected import context generally does not support importing symmetric keys, the error ara::crypto::CryptoErrc::kUnsupported is reported [SWS_CRYPT_50210].
Regarding execution safety, the interface is specified as thread-safe and exception-safe [SWS_CRYPT_50210]. All defined error cases provide rollback semantics so that the state of the context remains unchanged in case of error [SWS_CRYPT_50210].
This text was generated by an AI based on the AUTOSAR R25-11 specification.
The interface shall unwrap the protected data provided, parse the content, and make the parsed content (key-material and meta-data) available for retrieval by the application. If optionally a Key Slot is specified, the unwrapped key material shall be directly serialized into the KeySlot.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 89f9277cd6aaProvenanceOpen questions (1)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The synchronous method Import of class ara::crypto::cryp::ProtectedKeyImportCtx unpacks protected key data from memory area serialized ([SWS_CRYPT_50207]). It analyzes the data content and provides the extracted key material as well as metadata for subsequent retrieval. If a WriteableKeySlot is optionally passed, the key material is serialized directly into this slot ([SWS_CRYPT_50207]). Interpretation: If no keySlot is passed, the key material presumably remains exclusively in the state of the import context. Question Q-130f11475af1bb33 (open)
Error handling
The function returns a ara::core::Result<void>. If the operation fails, rollback semantics take effect for all error codes ([SWS_CRYPT_50207]):
ara::crypto::CryptoErrc::kInvalidInputSize: The input size of serialized is unexpected ([SWS_CRYPT_50207]).
ara::crypto::CryptoErrc::kInvalidArgument: The serialized data does not correspond to the expected format ([SWS_CRYPT_50207]).
ara::crypto::CryptoErrc::kAuthTagNotValid: Authentication check (MAC or signature) fails ([SWS_CRYPT_50207]).
ara::crypto::CryptoErrc::kBusyResource: The operation cannot be executed temporarily ([SWS_CRYPT_50207]).
Concurrency and Interaction
The method is thread-safe and exception-safe (noexcept) ([SWS_CRYPT_50207]). After a successful call, the unpacked key object can be retrieved from the context via GetPrivateKey ([SWS_CRYPT_50209]), GetSymmetricKey ([SWS_CRYPT_50210]), or GetPublicKey ([SWS_CRYPT_50211]). If the underlying protocol requires feedback to the sender, GetResponse ([SWS_CRYPT_41020]) provides the response of the crypto provider. For unprotected key formats, methods ImportPublicKey ([SWS_CRYPT_20732]), ImportSymmetricKey ([SWS_CRYPT_50014]), and ImportPrivateKey ([SWS_CRYPT_50132]) of factory class CryptoProvider serve alternatively.
This text was generated by an AI based on the AUTOSAR R25-11 specification.
The interface shall restore the context to its initial state by ensuring that no key-import-key is set and all previously imported data is deleted from the ProtectedKeyImportCtx’s internal buffers.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: 21bf97fcdbf3Provenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
Method Reset resets the instance of ara::crypto::cryp::ProtectedKeyImportCtx to its initial state [SWS_CRYPT_50212]. In doing so, the interface ensures that no Key Import Key (KIK) is set anymore and that all previously imported data is completely cleared from the internal buffers of the context [SWS_CRYPT_50212].
The call is synchronous and, according to the specification, classified as thread-safe as well as exception safe[SWS_CRYPT_50212]. The method declares the signature virtual ara::core::Result<void> Reset() const noexcept = 0; and requires including header ara/crypto/cryp/protected_key_import_ctx.h[SWS_CRYPT_50212].
Error handling
The result is returned via ara::core::Result<void>[SWS_CRYPT_50212]. If the operation fails, the interface returns an error code:
ara::crypto::CryptoErrc::kUnsupported: Occurs when the specific context does not support resetting its state (rollback semantics) [SWS_CRYPT_50212].
This usage note was generated automatically based on specification SWS_CRYPT_50212.
The interface shall configure the context to use the provided symmetric key as transport key.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: bb7a4eb711eaProvenanceOpen questions (1)
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
The method SetKey of class ara::crypto::cryp::ProtectedKeyImportCtx configures the context so that the passed symmetric key object key (SymmetricKey::Sptr) is used as a transport key [SWS_CRYPT_50205]. The call is synchronous and returns a ara::core::Result<void>[SWS_CRYPT_50205].
Error handling
If an error occurs during configuration, it is reported with rollback semantics so that the previous state of the context remains unchanged [SWS_CRYPT_50205]. The following error codes are defined:
ara::crypto::CryptoErrc::kUnsupported: Returned if the context exclusively supports the assignment of a KeySlot[SWS_CRYPT_50205].
ara::crypto::CryptoErrc::kIncompatibleObject: The provided key object cannot be used as a transport key [SWS_CRYPT_50205].
ara::crypto::CryptoErrc::kUsageViolation: The usage flags of the key do not contain the required permission kAllowKeyUnwrapping[SWS_CRYPT_50205].
Concurrency and Interaction
The operation is specified as thread-safe (thread-safe) and exception-safe (exception safe) and throws no exceptions (noexcept) [SWS_CRYPT_50205]. While contexts such as SymmetricKeyWrapperCtx bind a key for protecting or wrapping [SWS_CRYPT_24018], the key here serves for importing protected keys. Error condition kUnsupported also points to architectures in which contexts are alternatively configured via a KeySlot[SWS_CRYPT_50034]. Interpretation: The assignment of the transport key is likely required to be completed prior to subsequent import operations. Question Q-f1f3eab5ab896b1b (open)
This usage note was generated automatically based on the AUTOSAR specification R25-11.
The interface shall configure the context to use the key stored in the provided KeySlot at the time the import operation is started as the transport key.
AI-GENERATEDunreviewedModel: gemini-3.8-flash-medium · Effort: medium · Temperature: not controllable · Prompt: e6e7bd1f753cProvenance
translated from the German guidegemini-3.8-flash-low · 2026-10-13 · German original
use
The method SetKey configures the context [SWS_CRYPT_50206] (ara::crypto::cryp::ProtectedKeyImportCtx) such that the symmetric key stored in the passed KeySlot::Sptr keySlot is used as a transport key at the start time of the import process. The call is synchronous and returns a ara::core::Result<void>.
Error handling
If an error occurs during configuration, rollback semantics take effect [SWS_CRYPT_50206]. Specific error codes include:
ara::crypto::CryptoErrc::kUnsupported: When the context exclusively supports setting a direct SymmetricKey object [SWS_CRYPT_50206].
ara::crypto::CryptoErrc::kIncompatibleObject: When the key contained in the slot cannot be used as a transport key [SWS_CRYPT_50206].
ara::crypto::CryptoErrc::kUsageViolation: When the allowed usage flags of the key in KeySlot do not contain flag kAllowKeyUnwrapping[SWS_CRYPT_50206].
Concurrency and Interaction
The function is specified as exception-safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_50206]. The key is only evaluated from the slot upon the start of the subsequent import [SWS_CRYPT_50206]. While other cryptographic contexts such as SymmetricKeyWrapperCtx[SWS_CRYPT_50034] or KeyDerivationFunctionCtx[SWS_CRYPT_50010] can also integrate slots as a key source, ProtectedKeyImportCtx::SetKey explicitly requires permission to unpack keys.
This text was generated by an AI-assisted documentation tool and does not replace consulting the official AUTOSAR specifications.
gemini-3.8-flash-low· 2026-10-13 · German original