class ara::crypto::cryp::CryptoObject

The interface ara::crypto::cryp::CryptoObject defines the common abstraction for all cryptographic objects in the Adaptive crypto stack and governs their lifecycle via Sptr [SWS_CRYPT_20501]. It enables the thread-safe retrieval of algorithm identifiers as well as usage flags and supports the persistent overwriting of key material in a WriteableKeySlot [SWS_CRYPT_20505], [SWS_CRYPT_20517]. During the storage operation, defined error codes with rollback semantics ensure the data integrity of the underlying storage slot [SWS_CRYPT_20517].

more ›

Context

The interface ara::crypto::cryp::CryptoObject forms the common abstraction for all cryptographic objects that can be recognized and managed by a crypto provider. The class extends ara::crypto::Serializable and defines fundamental properties such as algorithm identification, usage restrictions, and mechanisms for persistent storage. Typical interaction partners are calling applications, the providing crypto provider, and target storages in the form of WriteableKeySlot instances.

Lifecycle

Cryptographic objects are primarily managed within the platform via shared ownership. For this purpose, the class defines the canonical smart pointer alias ara::crypto::cryp::CryptoObject::Sptr as std::shared_ptr<CryptoObject> [SWS_CRYPT_20501]. Concrete instances are likely instantiated by the specialized factory and loader routines of a crypto provider and made available to the caller via this pointer type. Question Q-36e2bd12d7dc8b98 (open) All declared methods of the interface are specified as thread-safe and exception-safe (exception safe, noexcept), thereby ensuring safe concurrent read and store access across multiple threads [SWS_CRYPT_20505], [SWS_CRYPT_50092], [SWS_CRYPT_20517]. The release of the object and the associated key material occurs automatically as soon as the last Sptr reference expires.

Usage Path

A typical usage path comprises the identification of an object's cryptographic properties and its subsequent persistent storage. First, the application queries the algorithm identifier of the object as ara::crypto::AlgIdString via GetAlgId() [SWS_CRYPT_20505]. Subsequently, the permitted usage flags (AllowedUsageFlags) are determined via GetAllowedUsage() [SWS_CRYPT_50092] to ensure that the object is authorized for the intended operation. For permanent preservation, the application passes a writable key slot to the method Save() [SWS_CRYPT_20517]. The key material as well as associated metadata are then stored in the destination slot, overwriting previously existing data in the slot [SWS_CRYPT_20517].

Sequence diagram: Typical sequence for inspecting and persisting a cryptographic object in a KeySlot. Sources: [SWS_CRYPT_20505], [SWS_CRYPT_50092], [SWS_CRYPT_20517].

Error Scenarios

While GetAlgId() [SWS_CRYPT_20505] and GetAllowedUsage() [SWS_CRYPT_50092] specify no standardized error codes and return the respective result in a ara::core::Result in case of success, the persistence operation Save() defines specific error conditions with mandatory rollback semantics [SWS_CRYPT_20517]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Occurs if the object is incompatible with the passed WriteableKeySlot, for example because the algorithm identifiers (AlgId) differ from each other or the key slot belongs to a different crypto provider [SWS_CRYPT_20517].
• ara::crypto::CryptoErrc::kUsageViolation: Signals unauthorized usage if the key's usage flags declared via GetAllowedUsage() do not include the permission for persistence (kAllowPersist) [SWS_CRYPT_50092], [SWS_CRYPT_20517].
• ara::crypto::CryptoErrc::kBusyResource: Is returned if the underlying storage resource is temporarily busy and the operation cannot be executed immediately [SWS_CRYPT_20517].

Thanks to the rollback semantics, the state of the WriteableKeySlot remains intact upon any of these errors, ensuring that no partially written or corrupted key data remains in storage [SWS_CRYPT_20517].