class ara::crypto::Formatter

The interface ara::crypto::Formatter enables thread-safe conversion and serialization of cryptographic data between raw, DER, and PEM formats [SWS_CRYPT_50197]. After determining the target format and determining the required buffer size, the method Convert transfers the source data into the prepared output buffer [SWS_CRYPT_50198]. An essential prerequisite for successful execution is a sufficiently dimensioned target memory and the formal compliance of the input data with the configured source format.

more ›

Context

The interface ara::crypto::Formatter defines the uniform interface for the formatting, transformation, and serialization of cryptographic data structures in the module crypto. Its primary task is to convert payload data and cryptographic objects between representations such as pure raw data (kFormatRawValueOnly), ASN.1 DER encodings (kFormatDerEncoded), and textual PEM formats (kFormatPemEncoded) taking into account an algorithm identifier (AlgId) [SWS_CRYPT_50197]. In doing so, the formatter acts as a link between cryptographic objects and memory buffers by reading data via ReadOnlyMemRegion and outputting it to ReadWriteMemRegion [SWS_CRYPT_50198].

Lifecycle

Since ara::crypto::Formatter is declared as a pure virtual interface, it provides the canonical smart pointer type alias Sptr, defined as std::shared_ptr<Formatter>, for referencing and lifecycle management [SWS_CRYPT_50191]. In practice, concrete instances of the interface are presumed to be provided via factory methods of higher-level crypto components. Question Q-99e96992d02b9c13 (open) After creation, a formatter is initially in an unconfigured initial state before it is prepared for conversions via configuration calls.

With regard to the execution environment, the interface guarantees full exception safety (exception safe) through the consistent use of noexcept and error handling via result types [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. All member functions are also specified as thread-safe (thread-safe) [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. This allows concurrent read and transforming access of multiple threads to a shared formatter instance, as long as no competing reconfigurations take place.

Usage Path

Regular usage of ara::crypto::Formatter follows a fixed sequence of parameterization, capacity check, and transformation:

1. Format configuration: Via SetFormatConfiguration, the expected input format (inputFormat), the desired output format (outputFormat), and the algorithm identifier (algId) of the data to be processed are bindingly specified [SWS_CRYPT_50197].
2. Size determination: Prior to the actual conversion, the application calls GetExportSize to determine the exact memory size in bytes required by the serialized object under the current configuration [SWS_CRYPT_50199]. This enables the tailored allocation of the target memory.
3. Data conversion: Finally, Convert transforms the source data from a ReadOnlyMemRegion into the destination buffer ReadWriteMemRegion in accordance with the established configuration [SWS_CRYPT_50198].

Sequence diagram: Typical conversion sequence from format selection and buffer size determination to the actual transformation. Sources: [SWS_CRYPT_50197], [SWS_CRYPT_50199], [SWS_CRYPT_50198]

Error Scenarios

Methods of ara::crypto::Formatter signal error states deterministically via return values of type ara::core::Result. In this context, clear rollback semantics are defined for failing operations:

• Unsupported formats: If the underlying implementation does not support the specified conversion pair or algorithm identifier, SetFormatConfiguration returns the error code ara::crypto::CryptoErrc::kUnsupportedFormat [SWS_CRYPT_50197].
• Invalid input data: If the raw data passed in the buffer does not match the configured format or is syntactically invalid, Convert fails with ara::crypto::CryptoErrc::kInvalidArgument [SWS_CRYPT_50198].
• Insufficient destination buffer: If the provided ReadWriteMemRegion is too small for the serialized result, Convert aborts with ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50198]. This issue can be specifically prevented by prior querying via GetExportSize [SWS_CRYPT_50199].
• Missing pre-configuration: While no standardized error codes are listed for GetExportSize [SWS_CRYPT_50199], a valid configuration must presumably be established in advance via SetFormatConfiguration so that consistent size determination or conversion can take place. Question Q-e7cf4306bc7cfb49 (open)