class ara::crypto::cryp::AuthCipherCtx

use

The method Cancel() of interface ara::crypto::cryp::AuthCipherCtx aborts an active streaming operation that was previously initiated via Start() and has not yet been completed [SWS_CRYPT_50077]. The function is provided via the header ara/crypto/cryp/auth_cipher_ctx.h and operates synchronously without parameters [SWS_CRYPT_50077]. It returns a ara::core::Result<void> that is empty in case of success.

Error Handling and Boundary Conditions

An abort requires that data processing was actually started beforehand by Start(). If the streaming operation was not started, the call fails and returns the error code ara::crypto::CryptoErrc::kProcessingNotStarted with rollback semantics [SWS_CRYPT_50077].

Concurrency

The operation is declared as noexcept and, according to the specification, classified as both thread-safe and exception safe [SWS_CRYPT_50077].

Interaction

The abort pattern realized by Cancel() is standardized in module crypt. An identical interface semantics and the same error code ara::crypto::CryptoErrc::kProcessingNotStarted are defined for corresponding streaming contexts:

• ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023]
• ara::crypto::cryp::MessageAuthnCodeCtx [SWS_CRYPT_50027]
• ara::crypto::cryp::SignerPrivateCtx [SWS_CRYPT_50041]
• ara::crypto::cryp::SymmetricCipherCtx [SWS_CRYPT_50046]
• ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50058]
• ara::crypto::cryp::DecryptorPrivateCtx [SWS_CRYPT_50069]
• ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50089]

The synchronous method EncryptSingleCallWithOutputIv of interface ara::crypto::cryp::AuthCipherCtx performs authenticated ciphering in a single step and thereby generates an initialization vector independently [SWS_CRYPT_50080]. It processes input data from dataIn as well as optional additional data authenticatedData and writes the ciphertext into the buffer dataOut. The generated initialization vector is stored in the buffer ivOut, while the authentication tag is output via tag [SWS_CRYPT_50080]. The buffer size for ivOut can be determined in advance via the method GetOutputIvSize [SWS_CRYPT_50165]. Despite the name component Encrypt, the method can presumably also be used for decryption, since the error specification explicitly lists the behavior for transformDirection == kDecrypt [SWS_CRYPT_50080]. Question Q-66618567b20f99b9 (open)

Essential preconditions and restrictions apply to the call:

• The context must have been successfully initialized with SetKey beforehand; otherwise, kUninitializedContext is reported [SWS_CRYPT_50080].
• The key in the configured Key-Slot must be compatible and have the appropriate permission (e.g., kAllowDataEncrypt), as otherwise kUsageViolation or kIncompatibleObject is returned [SWS_CRYPT_50080].
• If the output buffers dataOut or ivOut are insufficient, the call fails with kInsufficientCapacity [SWS_CRYPT_50080].
• If the context does not support single-step processing or requires an external IV specification, kUnsupported is returned [SWS_CRYPT_50080].

The operation is specified as thread-safe as well as exception-safe and guarantees rollback semantics in case of error [SWS_CRYPT_50080]. For pure symmetric cipher operations without tag processing, a separate counterpart exists in SymmetricCipherCtx [SWS_CRYPT_50049].

Usage and Semantics

The method Finish synchronously completes encryption or decryption within a ara::crypto::cryp::AuthCipherCtx and calculates or verifies the authentication tag without returning an initialization vector (IV) [SWS_CRYPT_50075]. The caller passes the remaining data via the buffer in as well as the destination buffer out. In the case of encryption, the calculated tag is output via the buffer tag, whereas in the case of decryption, the tag to be verified is passed [SWS_CRYPT_50075]. The return value ara::core::Result<std::size_t> specifies the number of bytes actually written to out, which may be smaller than the capacity of the output buffer [SWS_CRYPT_50075].

Sequence and Interaction

Prior to the call, data processing must mandatorily have been initiated by Start() [SWS_CRYPT_50075]. If data blocks were previously processed using UpdateConfidentialData, an application may use the resulting plaintext during decryption only after successful authentication by Finish [SWS_CRYPT_50074]. The maximum required buffer size for out can be determined in advance via GetRequiredOutputBufferSize by specifying isFinal = true [SWS_CRYPT_50081].

Error Handling and Concurrency

The method is specified as thread-safe and exception-safe [SWS_CRYPT_50075]. Errors are reported via ara::core::Result with rollback semantics [SWS_CRYPT_50075]:

• ProcessingNotStarted: Data processing was not previously started with Start() [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer out is too small [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kInvalidInputSize: The buffer size of in or tag is invalid [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kAuthTagNotValid: Data authenticity cannot be confirmed during decryption [SWS_CRYPT_50075].
• ara::crypto::CryptoErrc::kUnsupported: Streaming processing is not supported by the context [SWS_CRYPT_50075].

use

The method FinishEncrypt synchronously completes an authenticated encryption operation in ara::crypto::cryp::AuthCipherCtx, calculates the authentication tag, and returns the initialization vector generated by the context via ivOut [SWS_CRYPT_50076]. The call is specified as thread-safe and exception-safe (exception safe) [SWS_CRYPT_50076]. As its result, the function returns an ara::core::Result<std::size_t> with the number of bytes actually written to the output buffer out, where the output size may be smaller than the buffer capacity [SWS_CRYPT_50076]. Interpretation: Although the name indicates encryption, the specification of parameter tag and the error code ara::crypto::CryptoErrc::kAuthTagNotValid indicate that the signature in the context should presumably also be used symmetrically for decryption operations. Question Q-6b924f12c32e0f33 (open)

Interaction and Buffer Dimensioning

Data processing must strictly have been initiated in advance with Start(); otherwise the function reports the error ProcessingNotStarted [SWS_CRYPT_50076]. For buffer dimensioning, the interaction with the following context functions must be observed:

• The maximum required capacity for out can be calculated in advance via [SWS_CRYPT_50081] using parameter isFinal = true in order to avoid error ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50076].
• The minimum and maximum buffer size for the input data in is determined by [SWS_CRYPT_50162] and [SWS_CRYPT_50082].
• The buffer size required to accommodate the generated initialization vector in ivOut can be queried via [SWS_CRYPT_50165].

Error Handling and Boundary Conditions

In case of error, all responses have defined rollback semantics [SWS_CRYPT_50076]. For invalid buffer sizes for input data or the authentication tag, ara::crypto::CryptoErrc::kInvalidInputSize is returned [SWS_CRYPT_50076]. In addition, the function returns ara::crypto::CryptoErrc::kUnsupported if stream processing is not supported, no IV is used, or the IV was already specified by the application at the start [SWS_CRYPT_50076].

The synchronous method ProcessSingleCall of ara::crypto::cryp::AuthCipherCtx, which is defined as thread-safe, performs the encryption or decryption of payload data and the simultaneous calculation or verification of the authentication tag in a single operation without an initialization vector (IV) [SWS_CRYPT_50078]. Additional authenticated data can be provided via the optional buffer authenticatedData [SWS_CRYPT_50078]. The buffer tag serves as input for verification during decryption and as output for storing the generated authentication tag during encryption [SWS_CRYPT_50078]. Upon successful processing, ara::core::Result<std::size_t> returns the actual number of bytes written to dataOut, which may be smaller than the capacity of the target buffer [SWS_CRYPT_50078].

Before the call, the cryptographic context must have been initialized via a successful call to SetKey; otherwise, the function fails with ara::crypto::CryptoErrc::kUninitializedContext [SWS_CRYPT_50078]. In addition, the used key must be enabled for the requested transformation direction (kAllowDataEncrypt or kAllowDataDecrypt), as otherwise ara::crypto::CryptoErrc::kUsageViolation is reported [SWS_CRYPT_50078]. If single-step processing is not supported or the context requires an IV, the function returns ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_50078]. If authentication fails during decryption, ara::crypto::CryptoErrc::kAuthTagNotValid is triggered [SWS_CRYPT_50078]. Errors on the associated key slot are signaled via EmptyKeySlot, ara::crypto::CryptoErrc::kBusyResource, or ara::crypto::CryptoErrc::kIncompatibleObject [SWS_CRYPT_50078].

For buffer management, the maximum required output size for dataOut can be calculated in advance via GetRequiredOutputBufferSize with the flag isFinal = true set [SWS_CRYPT_50081]; an output buffer that is too small leads to ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50078]. In addition, the size of dataIn must conform to the limits of GetMinimumChunkSize [SWS_CRYPT_50162] and GetMaximumChunkSize [SWS_CRYPT_50082] in order to avoid ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50078].

The method [SWS_CRYPT_50079] of class ara::crypto::cryp::AuthCipherCtx performs synchronous single-step processing (single-call) for encrypting or decrypting data while simultaneously calculating or verifying the authentication tag.

Upon the call, the input data is specified via dataIn and the direction via transformDirection. The initialization vector is passed via iv, and optional authentication data can be provided via authenticatedData [SWS_CRYPT_50079]. The buffer tag serves as output for the calculated tag in the case of encryption, and as input for verification in the case of decryption [SWS_CRYPT_50079]. On success, the return value ara::core::Result<std::size_t> provides the number of bytes written to dataOut, which may be smaller than the buffer capacity [SWS_CRYPT_50079].

In case of error, all error codes have rollback semantics [SWS_CRYPT_50079]:

• ara::crypto::CryptoErrc::kUninitializedContext: No key was configured beforehand via SetKey [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kUsageViolation: The key does not possess the required right kAllowDataEncrypt or kAllowDataDecrypt [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kEmptyKeySlot, ara::crypto::CryptoErrc::kBusyResource, or ara::crypto::CryptoErrc::kIncompatibleObject: A configured KeySlot is empty, occupied, or does not contain a compatible SymmetricKey [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kInvalidInputSize or ara::crypto::CryptoErrc::kInsufficientCapacity: The buffers for input, tag, or IV are dimensioned invalidly, or dataOut provides insufficient capacity [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kAuthTagNotValid: During decryption, authentication fails [SWS_CRYPT_50079].
• ara::crypto::CryptoErrc::kUnsupported: Single-shot processing is not supported by the context, or the context requires setting or outputting an IV [SWS_CRYPT_50079].

The operation is defined as thread-safe and exception safe [SWS_CRYPT_50079]. The permissible lengths for iv can be queried dynamically via GetMinimumInputIvSize [SWS_CRYPT_50163] and GetMaximumInputIvSize [SWS_CRYPT_50164]. Compared to the pure block cipher in SymmetricCipherCtx [SWS_CRYPT_50048], this interface combines cryptographic transformation and integrity verification in a single call.

The SetKey method configures the instance of ara::crypto::cryp::AuthCipherCtx to use a passed symmetric key [SWS_CRYPT_23911]. A shared pointer key (of type SymmetricKey::Sptr) used for authenticated encryption or decryption is passed as a parameter [SWS_CRYPT_23911]. The call is synchronous, declared as noexcept, and returns a ara::core::Result<void> [SWS_CRYPT_23911].

In case of an error, the result is reset with rollback semantics and delivers specific error codes [SWS_CRYPT_23911]:

• ara::crypto::CryptoErrc::kUnsupported: if the context exclusively supports configuration via a KeySlot [SWS_CRYPT_23911].
• ara::crypto::CryptoErrc::kIncompatibleObject: if the passed key type is not compatible with the current context [SWS_CRYPT_23911].
• ara::crypto::CryptoErrc::kUsageViolation: if the permitted usage flags of the key do not contain kAllowDataEncrypt for encryption or kAllowDataDecrypt for decryption [SWS_CRYPT_23911].

According to the specification, the interface is classified as thread-safe (thread-safe) and exception safe (exception safe) [SWS_CRYPT_23911]. In interaction with the module context, the key is likely set via Start [SWS_CRYPT_24715] before initializing a new transformation. Question Q-11f7daa370f5d438 (open)

The function SetKey in interface ara::crypto::cryp::AuthCipherCtx configures the context for cryptographic operations so that the symmetric key stored in a provided key slot is used as soon as the authenticated encryption or decryption is executed [SWS_CRYPT_50072].

Usage: The synchronous call is made via the interface from ara/crypto/cryp/auth_cipher_ctx.h. An instance of KeySlot::Sptr that encapsulates a symmetric key is passed as parameter keySlot [SWS_CRYPT_50072]. The function returns an ara::core::Result<void> that confirms success or contains an error code [SWS_CRYPT_50072].

Error handling: If the concrete implementation of the context only supports direct configuration via an SymmetricKey object and does not offer setting via KeySlot, the call fails. In this case, error ara::crypto::CryptoErrc::kUnsupported is returned with rollback semantics [SWS_CRYPT_50072].

Concurrency and constraints: The function is specified as thread-safe and exception safe [SWS_CRYPT_50072]. It can be called concurrently and ensures that no inconsistent state remains in exception situations.

Interaction: The overload SetKey with a direct SymmetricKey::Sptr is available as a functional alternative [SWS_CRYPT_23911]. After key binding has occurred, the context is initialized with the operation direction and the initialization vector via Start [SWS_CRYPT_24715]. Analogous signatures with KeySlot::Sptr also exist in MessageAuthnCodeCtx [SWS_CRYPT_50026] and SymmetricKeyWrapperCtx [SWS_CRYPT_50034].

The Start method initializes context ara::crypto::cryp::AuthCipherCtx for a new encryption or decryption and sets the initialization vector (IV) or nonce value to be used [SWS_CRYPT_24715]. The transformation direction is specified via parameter transformDirection, while iv passes the vector as ReadOnlyMemRegion [SWS_CRYPT_24715]. The permitted IV size can be determined via GetMinimumInputIvSize() and GetMaximumInputIvSize(); if the length differs, the function reports the error ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_24715].

Prior to the call, SetKey must have been executed successfully; otherwise, ara::crypto::CryptoErrc::kUninitializedContext is returned [SWS_CRYPT_24715]. A configured KeySlot must neither be empty (EmptyKeySlot) nor busy (ara::crypto::CryptoErrc::kBusyResource) [SWS_CRYPT_24715]. Furthermore, the stored key must be a suitable SymmetricKey (otherwise ara::crypto::CryptoErrc::kIncompatibleObject) and authorized for the desired direction (kAllowDataEncrypt or kAllowDataDecrypt, otherwise ara::crypto::CryptoErrc::kUsageViolation) [SWS_CRYPT_24715]. If support for stream processing or setting an IV in the selected direction is missing, the call fails with ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_24715]. All errors exhibit rollback semantics [SWS_CRYPT_24715].

The operation is declared as thread-safe and exception-safe (noexcept) [SWS_CRYPT_24715]. In the interaction of cryptographic flows, passing additional authenticated data via UpdateAuthenticatedData would typically follow after successful initialization [SWS_CRYPT_20313]. Question Q-e023e27f1cd24507 (open)

use

The pure virtual method Start of class ara::crypto::cryp::AuthCipherCtx synchronously initializes the context for an upcoming encryption or decryption [SWS_CRYPT_50073]. The parameter transformDirection indicates whether the context is prepared for encryption or decryption. This overload without an initialization vector (IV) may only be used if the cryptographic context does not require an IV in the selected transformation direction or determines it itself [SWS_CRYPT_50073]. The return value is an empty ara::core::Result<void> in the success case or a corresponding error code.

Error Handling and Preconditions

Before the call, the context must have been successfully configured with a key via SetKey; otherwise the function fails with ara::crypto::CryptoErrc::kUninitializedContext [SWS_CRYPT_50073]. In addition, the following return values occur in the event of an error:

• ara::crypto::CryptoErrc::kUnsupported if stream processing is not supported by the context or if the context strictly requires the explicit specification of an IV in the selected transformation direction [SWS_CRYPT_50073].
• ara::crypto::CryptoErrc::kUsageViolation if the permitted key usage in the configured KeySlot does not include the required permission kAllowDataEncrypt for encryption or kAllowDataDecrypt for decryption at the time of the call [SWS_CRYPT_50073].
• EmptyKeySlot or ara::crypto::CryptoErrc::kBusyResource if a configured KeySlot is currently empty or blocked [SWS_CRYPT_50073].
• ara::crypto::CryptoErrc::kIncompatibleObject if the configured KeySlot does not contain a SymmetricKey or if this key type is not supported by the context [SWS_CRYPT_50073].

If an error occurs, the specified rollback semantics (rollback_semantics) take effect [SWS_CRYPT_50073].

Concurrency and Interaction

The function is declared with noexcept=0, ensures exception safety, and is designed to be thread-safe [SWS_CRYPT_50073]. If the algorithm requires the external provision of an initialization vector, the overload Start(CryptoTransform, ReadOnlyMemRegion) must be used instead [SWS_CRYPT_24715]. After successful initialization, additional authenticated data can be incorporated into the calculation of the authentication tag via UpdateAuthenticatedData [SWS_CRYPT_20313].

The method UpdateAuthenticatedData of interface ara::crypto::cryp::AuthCipherCtx serves to update the calculation of the authentication tag incrementally with another portion of additional authenticated data (Additional Authenticated Data) [SWS_CRYPT_20313]. Via the parameter authenticatedData, the corresponding buffer is passed as ReadOnlyMemRegion [SWS_CRYPT_20313].

Regarding call context and concurrency, the operation is defined as thread-safe and exception safe [SWS_CRYPT_20313]. Strict sequence conditions apply to the call:

• The transformation must have been initiated beforehand via the method Start(); otherwise, ara::crypto::CryptoErrc::kProcessingNotStarted is reported [SWS_CRYPT_20313].
• The function must no longer be called once UpdateConfidentialData has already been executed; in case of non-compliance, the error ara::crypto::CryptoErrc::kInvalidUsageOrder is returned [SWS_CRYPT_20313].

As a return value, the function returns a ara::core::Result<void> that is empty in case of success or encapsulates an occurred error code [SWS_CRYPT_20313]. All errors exhibit rollback semantics [SWS_CRYPT_20313]:

• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed input buffer is invalid [SWS_CRYPT_20313].
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the current context [SWS_CRYPT_20313].

The method UpdateConfidentialData of the class ara::crypto::cryp::AuthCipherCtx serves to encrypt or decrypt confidential payload data step by step within the scope of an authenticated encryption context [SWS_CRYPT_50074]. The input buffer in (type ReadOnlyMemRegion) with part of the plaintext or ciphertext as well as the output buffer out (type ReadWriteMemRegion) are passed to it [SWS_CRYPT_50074]. As a synchronous return value, the function returns a ara::core::Result<std::size_t>, which upon success contains the number of bytes actually written; this can be smaller than the capacity of out [SWS_CRYPT_50074].

Regarding the sequence and concurrency, the following conditions apply:

• Execution order and integrity: Before processing, the operation must have been initiated via Start() [SWS_CRYPT_50074]. If the method is used for decryption, the plaintext is output without a prior authenticity check; the application must under no circumstances use this data before the final verification by means of Finish() [SWS_CRYPT_50074]. Additional authenticated data can be factored into the tag calculation in parallel via UpdateAuthenticatedData [SWS_CRYPT_20313].
• Thread and exception safety: The operation is declared as thread-safe as well as exception-safe and does not throw any exceptions (noexcept) [SWS_CRYPT_50074].

If processing fails, rollback semantics apply while returning a corresponding error code in ara::core::Result [SWS_CRYPT_50074]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Processing has not yet been initiated via Start() [SWS_CRYPT_50074].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer out is dimensioned too small [SWS_CRYPT_50074].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the buffer in is invalid [SWS_CRYPT_50074].
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the context [SWS_CRYPT_50074].