class ara::crypto::Serializable

The interface ara::crypto::Serializable defines the uniform standard for publicly exporting cryptographic objects into format-specific byte sequences. Applications determine the required buffer size in advance via GetExportSize() and subsequently execute the actual serialization via ExportPublicly() into a provided buffer [SWS_CRYPT_10711]. All operations are exception-safe as well as thread-safe, where exporting keys strictly requires the permission kAllowPlaintextExport and errors are always subject to rollback semantics [SWS_CRYPT_50006].

more ›

Context

The interface ara::crypto::Serializable defines the abstract contract for cryptographic objects in module crypto that can be converted into a standardized byte representation. As a pure interface, it encapsulates the ability to serialize an object into an output format specified by a format identifier (FormatId) [SWS_CRYPT_10711]. Typical interaction partners include application or platform components that need to persistently store cryptographic artifacts such as keys or certificates, transmit them over communication channels, or exchange them in plain text. The interface ensures that the export is carried out in a controlled manner and in consideration of formats as well as security restrictions.

Lifecycle

Since ara::crypto::Serializable represents a purely virtual interface with pure virtual methods, the class has no instantiation logic of its own. The lifetime and creation depend entirely on the derived concrete crypto classes that implement the interface. Both specified methods of the interface, GetExportSize() [SWS_CRYPT_50006] and ExportPublicly() [SWS_CRYPT_10711], are declared as const and do not modify the internal state of the object during serialization. According to the specification, the operations are designed to be exception-safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_10711], [SWS_CRYPT_50006], so that concurrent read accesses to the same object instance are permitted.

Usage Path

The regular flow of an export is divided into a two-stage sequence of size determination and actual serialization. To avoid buffer overflows or failing allocations, the caller queries the exact required buffer size in bytes for the desired target format in advance via the method GetExportSize() [SWS_CRYPT_50006]. Following successful feedback, the caller provides a writable memory area of type ReadWriteMemRegion. In most implementations, this memory area is presumably allocated dynamically based on the determined number of bytes or provided from a pre-reserved memory pool. Question Q-0c04ba0a352f0a37 (open)

In the subsequent step, the application calls ExportPublicly() and passes both the provided buffer and the previously selected FormatId [SWS_CRYPT_10711]. The object serializes its payload into the passed memory area and, in the success case, returns the number of bytes actually written within the return type ara::core::Result<std::size_t> [SWS_CRYPT_10711].

Sequence diagram: Typical call sequence for serializing an object via size query and subsequent export. Sources: [SWS_CRYPT_50006], [SWS_CRYPT_10711]

Error Scenarios

The operations of the interface signal error conditions via the return type ara::core::Result, with all specified errors guaranteeing strict rollback semantics (rollback_semantics) [SWS_CRYPT_10711], [SWS_CRYPT_50006]. If a call fails, the overall system remains in a consistent state. The following error cases are defined:

• ara::crypto::CryptoErrc::kUnsupportedFormat: Returned by both GetExportSize() [SWS_CRYPT_50006] and ExportPublicly() [SWS_CRYPT_10711] if the specified FormatId is not supported for the concrete object type.
• ara::crypto::CryptoErrc::kInsufficientCapacity: Occurs in ExportPublicly() if the capacity of the passed ReadWriteMemRegion buffer is insufficient for the serialized data [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUnsupported: Reported by ExportPublicly() if export is fundamentally not supported for the specific object [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUsageViolation: Occurs with ExportPublicly() if the object is a key whose usage rules do not permit plaintext export (the permitted usage does not include kAllowPlaintextExport) [SWS_CRYPT_10711].