class ara::crypto::cryp::MessageAuthnCodeCtx

The pure virtual method Cancel in interface ara::crypto::cryp::MessageAuthnCodeCtx serves to abort an ongoing streaming operation that was previously initiated via Start() and has not yet completed [SWS_CRYPT_50027]. The call is synchronous, takes no arguments, and returns an empty ara::core::Result<void> on success, confirming the successful abort of the operation [SWS_CRYPT_50027].

If data processing was not properly initiated by the Start() method prior to the call, execution fails. In this case, the function returns a result with the specific error code ara::crypto::CryptoErrc::kProcessingNotStarted while ensuring rollback semantics [SWS_CRYPT_50027]. In terms of execution safety, the interface is specified as thread-safe and guarantees exception safety, as it is declared as noexcept and does not throw exceptions [SWS_CRYPT_50027].

All related context interfaces of the cryptography module share the identical abort behavior for streaming operations that have not yet been finalized:

• VerifierPublicCtx for verifying digital signatures [SWS_CRYPT_50023],
• SignerPrivateCtx for generating digital signatures [SWS_CRYPT_50041],
• SymmetricCipherCtx for symmetric encryptions [SWS_CRYPT_50046],
• HashFunctionCtx for hash computations [SWS_CRYPT_50058],
• DecryptorPrivateCtx for asymmetric decryptions [SWS_CRYPT_50069],
• AuthCipherCtx for authenticated encryptions [SWS_CRYPT_50077], as well as
• EncryptorPublicCtx for asymmetric encryptions [SWS_CRYPT_50089].

Interpretation: Aborting the incomplete operation likely returns the context to a clean state that allows subsequent reinitialization via Start(). Question Q-a8fa5cb85c3dab50 (open)

use

The pure virtual method Compare of class ara::crypto::cryp::MessageAuthnCodeCtx serves to compare the size and content of a calculated Message Authentication Code (MAC) with an expected digest [SWS_CRYPT_50133]. As parameter, the expected MAC digest is passed via ReadOnlyMemRegion expected. The function returns a ara::core::Result<bool>, which contains true if the calculated MAC value exactly matches the expected value, and false otherwise [SWS_CRYPT_50133].

Error handling

In case of error, an error code is returned in the result object, with rollback semantics applying [SWS_CRYPT_50133]:

• ara::crypto::CryptoErrc::kProcessingNotFinished: Reported if the calculation of the digest was not previously completed by calling the method Finish() [SWS_CRYPT_50133].
• ara::crypto::CryptoErrc::kInvalidInputSize: Occurs if the passed buffer size of the expected MAC digest is not supported by the context [SWS_CRYPT_50133].

Concurrency and Limitations

The method is declared as const as well as noexcept and is, according to the specification, thread-safe (thread-safe) as well as exception-safe (exception safe) [SWS_CRYPT_50133]. An essential precondition is the digest calculation previously completed successfully via Finish() [SWS_CRYPT_50133].

Interaction

In contrast to Compare, which validates the complete match of the entire MAC digest [SWS_CRYPT_50133], CompareSubspan in the same context only compares the most significant bits with the expected value [SWS_CRYPT_50028]. For unkeyed hash functions, an eponymous Compare function exists in ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50154].

The synchronous method CompareSubspan of class ara::crypto::cryp::MessageAuthnCodeCtx matches the most significant bits of a calculated MAC value against a specified reference [SWS_CRYPT_50028]. The expected comparison value is passed via parameter expected as ReadOnlyMemRegion [SWS_CRYPT_50028]. The result is returned as ara::core::Result<bool> and contains true in case of identity of the most significant bits and false in case of discrepancies [SWS_CRYPT_50028].

Error Handling and Operating Conditions

For a valid comparison, calculation of the verification value must be completed. If there is no previous call to method Finish(), the call fails with error code ara::crypto::CryptoErrc::kProcessingNotFinished [SWS_CRYPT_50028]. If the buffer size of the passed parameter expected is invalid for the procedure used, the method reports ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50028]. Both error types guarantee rollback semantics [SWS_CRYPT_50028].

Concurrency and Execution Context

The operation is specified as noexcept (exception-safe) and classified as thread-safe [SWS_CRYPT_50028]. Interpretation: The declared thread safety likely refers to the state after Finish() has taken place, allowing multiple threads to verify the same calculated digest in parallel. Question Q-ac8b7ead6a5b508e (open)

The Finish() method conclusively completes the ongoing calculation of a Message Authentication Code (MAC) within the MessageAuthnCodeCtx interface [SWS_CRYPT_22115]. The call is synchronous, takes no parameters, and returns ara::core::Result<void>, which represents an empty result in the regular success case [SWS_CRYPT_22115].

In case of an error, the function returns the error code ara::crypto::CryptoErrc::kProcessingNotStarted if the MAC calculation was not started successfully prior to the call; rollback semantics apply [SWS_CRYPT_22115]. The operation is declared as noexcept and, according to the specification, specified as both exception-safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_22115].

In the processing flow, Finish() forms the link between data processing and evaluation: after the call, the generated MAC digest can be transferred to a provided buffer via GetDigest() [SWS_CRYPT_22116] or directly verified against a reference value with CompareSubspan() [SWS_CRYPT_50028]. While GetMaximumChunkSize() [SWS_CRYPT_50033] generically describes buffer sizes for Update() or Finish(), Finish() does not process data directly here; its mention in the requirement is presumably likely to reflect a uniform pattern across all crypto contexts. Question Q-79b4f4ecf3998e48 (open)

According to [SWS_CRYPT_50029], the synchronous member function Generate of class ara::crypto::cryp::MessageAuthnCodeCtx is used to calculate a message authentication code (MAC) in a single step and writes the calculated digest into the provided output buffer.

The following parameters are passed for the call:

• data: Input data for the MAC calculation as ReadOnlyMemRegion.
• digest: Destination memory area of type ReadWriteMemRegion into which the digest is written.
• iv: An optional initialization vector as ara::core::Optional<ReadOnlyMemRegion>.

In case of success, the function returns a ara::core::Result<std::size_t> containing the size of the written MAC digest in bytes [SWS_CRYPT_50029].

If an error occurs, an error code with rollback semantics is returned [SWS_CRYPT_50029]:

• UninitializedContext: The context has not yet been initialized by assigning a key.
• ara::crypto::CryptoErrc::kUsageViolation: The key used does not have the required usage flag kAllowMac. Interpretation: A matching symmetric key is presumably generated and configured in advance via GenerateSymmetricKey [SWS_CRYPT_20721]. Question Q-d22f397bbc02487b (open)
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently empty.
• ara::crypto::CryptoErrc::kUnsupported: Single-call processing is not supported, or the specification of the initialization vector does not meet the algorithm requirements (missing or impermissibly specified IV).
• ara::crypto::CryptoErrc::kInvalidInputSize: The buffer size of the input data or IV is not supported.
• ara::crypto::CryptoErrc::kInsufficientCapacity: The destination buffer digest is too small for the MAC digest.
• ara::crypto::CryptoErrc::kBusyResource: A required system resource is busy.

Regarding concurrency, the method is specified as thread-safe and exception safe [SWS_CRYPT_50029]. It is declared as const noexcept and does not modify the state of the context during execution.

The GenerateSubspan method of class ara::crypto::cryp::MessageAuthnCodeCtx calculates a Message Authentication Code (MAC) for the input data data in a single step and writes the beginning (the most significant bytes, MSB) of the calculated digest into the output buffer truncatedDigest [SWS_CRYPT_50030]. Via the optional parameter iv, an initialization vector can be passed if required [SWS_CRYPT_50030]. The direct return of ara::core::Result<std::size_t> is likely to indicate synchronous execution; upon successful execution, the number of written bytes of the MAC digest is returned [SWS_CRYPT_50030]. Question Q-167c6d44b9f39fed (open)

For the error case, the specification defines rollback semantics and provides for the following error codes [SWS_CRYPT_50030]:

• UninitializedContext: The context was not previously initialized by assigning a key [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently empty [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUsageViolation: The permitted usage of the key does not include kAllowMac [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUnsupported: Single-step processing is not supported, or the IV configuration does not match the context (required IV is missing or invalid IV passed) [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed data data or of the iv is not supported [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kBusyResource: A required resource is busy [SWS_CRYPT_50030].

Regarding the execution environment, the method is specified as thread-safe and provides exception safety (noexcept) [SWS_CRYPT_50030]. A prerequisite for a flawless invocation is the prior provision of a key with appropriate permission in the context [SWS_CRYPT_50030].

The method SetKey configures an instance of ara::crypto::cryp::MessageAuthnCodeCtx for subsequent MAC calculation with a provided symmetric key [SWS_CRYPT_22118]. The call is synchronous and accepts the key object as a smart pointer SymmetricKey::Sptr. As result, the function returns a ara::core::Result<void>, which is empty on success or encapsulates a specific error code in case of an error [SWS_CRYPT_22118].

If the assignment fails, rollback semantics take effect, preserving the previous state of the context [SWS_CRYPT_22118]. The following error states from ara::crypto::CryptoErrc are specified:

• kUnsupported: The context exclusively supports binding via a KeySlot instead of via direct key objects [SWS_CRYPT_22118].
• kIncompatibleObject: The passed symmetric key object is incompatible with the target context [SWS_CRYPT_22118].
• kUsageViolation: The permission flags of the key do not contain the mandatory usage kAllowMac [SWS_CRYPT_22118].

Regarding execution safety, the interface is defined as thread-safe and exception safe (with noexcept) [SWS_CRYPT_22118]. In interaction with key management, it represents the direct counterpart to slot-based assignment: if an implementation or use case supports the use of persisted slots, the overload for KeySlot::Sptr is used instead [SWS_CRYPT_50026].

use

The virtual member function SetKey of interface ara::crypto::cryp::MessageAuthnCodeCtx from header file ara/crypto/cryp/message_authn_code_ctx.h configures the context for calculating or verifying a Message Authentication Code (MAC) [SWS_CRYPT_50026]. As a parameter, the synchronous method accepts a smart pointer keySlot of type KeySlot::Sptr that holds a symmetric key, and returns a ara::core::Result<void> [SWS_CRYPT_50026]. Binding of the key is semantically deferred: The key stored in the slot is only used at the point in time when the MAC calculation is actually started [SWS_CRYPT_50026]. Interpretation: Subsequent updates to the slot content up to the start of calculation should thus remain effective. Question Q-d1886811d8af71e3 (open)

Concurrency and Execution Safety

The interface is defined as noexcept, guarantees exception safety (exception safe), and is explicitly specified for concurrent invocation (thread-safe) [SWS_CRYPT_50026].

Error Handling and Interaction

In the event of an error, the method guarantees strict rollback semantics so that the previous state of the context is fully preserved [SWS_CRYPT_50026]. The following error codes can occur in the result object:

• ara::crypto::CryptoErrc::kIncompatibleObject: The passed KeySlot is incompatible with this symmetric key context [SWS_CRYPT_50026].
• ara::crypto::CryptoErrc::kUnsupported: The concrete implementation of the context does not support setting via KeySlot [SWS_CRYPT_50026]. In this case, the overload SetKey(SymmetricKey::Sptr) for direct passing of a key must be used alternatively [SWS_CRYPT_22118].

The method Start of ara::crypto::cryp::MessageAuthnCodeCtx initializes the context for a new MAC calculation, setting an initialization vector or nonce value via parameter iv ([SWS_CRYPT_22110]). This is used, for example, in algorithms such as GMAC ([SWS_CRYPT_22110]). For calculations without an explicit initialization vector, the parameterless overload Start() is alternatively available ([SWS_CRYPT_22111]).

Usage and Concurrency

The call takes place synchronously and is specified as thread-safe and exception safe ([SWS_CRYPT_22110]). After a successful call, message parts can be passed successively to the context using Update ([SWS_CRYPT_22113]). An ongoing streaming operation that has not yet completed can be aborted if necessary via Cancel ([SWS_CRYPT_50027]).

Error handling

The method returns a ara::core::Result<void> that has rollback semantics in case of an error ([SWS_CRYPT_22110]). Possible error states are:

• UninitializedContext: No key was assigned to the context in advance ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is empty ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUsageViolation: The permissions of the key do not include kAllowMac ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kInvalidInputSize: The passed IV size is not supported ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUnsupported: Streaming or setting an IV is not supported by the algorithm or context ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kBusyResource: A required resource is busy ([SWS_CRYPT_22110]).

use

The Start() method initializes an instance of ara::crypto::cryp::MessageAuthnCodeCtx for a new MAC calculation [SWS_CRYPT_22111]. The call takes no parameters and returns a ara::core::Result<void> [SWS_CRYPT_22111]. Execution is likely synchronous, as a result object is provided directly. Question Q-1e6e36f4ed1176d3 (open)

Error Handling and Concurrency

If an error occurs during initialization, rollback semantics apply and one of the following error codes is returned [SWS_CRYPT_22111]:

• UninitializedContext: No key was previously assigned to the context [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUnsupported: The context does not support streaming or the algorithm strictly requires an initialization vector (IV) [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kBusyResource: A required resource is busy [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is empty [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUsageViolation: The key does not permit MAC calculation without kAllowMac set [SWS_CRYPT_22111].

The function is specified as thread-safe and exception safe (exception safe) [SWS_CRYPT_22111].

Interaction in the Streaming Process

If the algorithm requires an IV (e.g. GMAC), the overload Start(ReadOnlyMemRegion iv) must be used instead [SWS_CRYPT_22110]. After a successful call, message data can be passed step by step via Update() [SWS_CRYPT_22113]. A streaming operation that has not yet been completed can be discarded via Cancel() [SWS_CRYPT_50027].

use

The synchronous method Update of context ara::crypto::cryp::MessageAuthnCodeCtx serves to append another fragment of the input message to the ongoing calculation of a Message Authentication Code (MAC) [SWS_CRYPT_22113]. The data segment to be processed is passed via parameter data in the form of a ReadOnlyMemRegion. As a return value, the function provides a ara::core::Result<void> that either confirms the successful intermediate step or indicates the cause of the error in case of an error [SWS_CRYPT_22113].

Error Handling and Concurrency

In case of an error, rollback semantics are guaranteed so that the previous calculation state remains unchanged [SWS_CRYPT_22113]. Possible error causes are:

• ara::crypto::CryptoErrc::kProcessingNotStarted: The calculation was not previously initiated by calling the Start() method [SWS_CRYPT_22113].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed data block is not supported by the context [SWS_CRYPT_22113].

The method is declared as noexcept and specified as thread-safe and exception safe [SWS_CRYPT_22113].

Interaction

To avoid buffer errors with ara::crypto::CryptoErrc::kInvalidInputSize, the maximum permitted input size for individual calls can be queried in advance via method GetMaximumChunkSize() [SWS_CRYPT_50033]. After successively processing all message parts, calculation of the MAC tag is, according to interpretation, typically completed via method Finish() [SWS_CRYPT_50033]. Question Q-7f8eaf8ebbf30d55 (open)

use

The Verify method in ara::crypto::cryp::MessageAuthnCodeCtx ([SWS_CRYPT_50031]) is used to synchronously calculate a MAC digest over the input buffer data and directly compare it with the expected value expected. Optionally, an initialization vector can be passed via iv. As a result, the function provides a ara::core::Result<bool> containing true if the calculated MAC matches the expected byte sequence, otherwise false.

Error handling

If verification fails for systemic or cryptographic reasons, the method returns a ara::core::Result with a corresponding error code ([SWS_CRYPT_50031]):

• UninitializedContext: If the context was not initialized beforehand by assigning a key.
• ara::crypto::CryptoErrc::kEmptyKeySlot: If the configured KeySlot is empty.
• ara::crypto::CryptoErrc::kUsageViolation: If the permitted key usage does not include kAllowMac.
• ara::crypto::CryptoErrc::kInvalidInputSize: If the buffer size of data, expected, or iv is invalid.
• ara::crypto::CryptoErrc::kUnsupported: If single-call execution is not supported or providing iv does not meet the requirements of the algorithm.
• ara::crypto::CryptoErrc::kBusyResource: In case of resource conflicts.

Concurrency and Interaction

The method is specified as thread-safe and exception safe ([SWS_CRYPT_50031]). In case of an error, rollback semantics apply. In contrast to asymmetric signature verifications in ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_24112], [SWS_CRYPT_50024]), Verify operates on symmetric MAC contexts. The maximum buffer size processable in a single call is presumably limited by the context implementation—analogously to the buffer query for signature verifiers ([SWS_CRYPT_50025]). Question Q-51e7427e4e082881 (open)

The VerifySubspan method of class ara::crypto::cryp::MessageAuthnCodeCtx serves to synchronously calculate a MAC digest and subsequently compare its most significant bits with an expected byte sequence [SWS_CRYPT_50032]. It processes input data via data, the expected leading bits via expected, and an optional initialization vector via iv [SWS_CRYPT_50032]. The result is returned as ara::core::Result<bool> and signals true upon successful match, otherwise false [SWS_CRYPT_50032].

The interface is specified as noexcept, is exception safe as well as thread-safe, and applies rollback semantics in case of an error [SWS_CRYPT_50032]. Failed calls return specific error codes in the return value [SWS_CRYPT_50032]:

• UninitializedContext: The context was not previously initialized by assigning a key [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUsageViolation: The permitted usage of the key does not include kAllowMac [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently empty [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed data, of the expected verification value, or of the IV is not supported [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUnsupported: The single-call operation is not supported or the provision of the IV conflicts with the requirements of the context [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kBusyResource: A required resource is busy [SWS_CRYPT_50032].