class ara::crypto::cryp::SymmetricCipherCtx

The synchronous method Cancel() of class ara::crypto::cryp::SymmetricCipherCtx serves to prematurely abort an ongoing streaming operation that was previously initiated with Start() and has not yet finished [SWS_CRYPT_50046]. The interface is declared without parameters in ara/crypto/cryp/symmetric_cipher_ctx.h and returns an empty ara::core::Result<void> upon successful execution [SWS_CRYPT_50046].

If data processing was not started beforehand by calling Start(), the operation fails with the specific error code ara::crypto::CryptoErrc::kProcessingNotStarted and rollback semantics [SWS_CRYPT_50046]. For the call context, the specification guarantees thread safety (thread-safe) as well as exception safety (exception safe) with a noexcept declaration [SWS_CRYPT_50046]. Interpretation: Due to the rollback semantics, the object will likely return to a ready initial state after an abort. Question Q-b6deb8db5367acc5 (open)

This functional pattern is consistently defined across all cryptographic streaming contexts in AUTOSAR Adaptive. Identical signatures and error semantics apply to the context classes VerifierPublicCtx ([SWS_CRYPT_50023]), MessageAuthnCodeCtx ([SWS_CRYPT_50027]), SignerPrivateCtx ([SWS_CRYPT_50041]), HashFunctionCtx ([SWS_CRYPT_50058]), DecryptorPrivateCtx ([SWS_CRYPT_50069]), AuthCipherCtx ([SWS_CRYPT_50077]), and EncryptorPublicCtx ([SWS_CRYPT_50089]).

Usage and Buffer Handling

The synchronous method EncryptSingleCallWithOutputIv performs symmetric encryption in a single call and returns the initialization vector generated by the context via the buffer ivOut [SWS_CRYPT_50049]. The input data are passed via in, while out accommodates the encrypted data [SWS_CRYPT_50049]. Upon successful execution, the result ara::core::Result<std::size_t> provides the actual size of the generated output data, which may be smaller than the total capacity of out [SWS_CRYPT_50049]. If the selected algorithm does not require an initialization vector, no data are written to ivOut [SWS_CRYPT_50049].

Interaction and Preconditions

Prior to the call, the context must be initialized via a suitable key [SWS_CRYPT_50049]. To ensure sufficient capacity of the buffer ivOut, the required IV length can be determined in advance via GetOutputIvSize() [SWS_CRYPT_50143]. If authentication with tag calculation is additionally required, ara::crypto::cryp::AuthCipherCtx provides the corresponding counterpart [SWS_CRYPT_50080].

Error Handling and Concurrency

The interface is specified as thread-safe and exception safe (“exception safe”) and applies rollback semantics in case of errors [SWS_CRYPT_50049]. Interpretation: These rollback semantics are presumably intended to ensure that, in the event of errors, the context state remains intact and no incomplete data remain valid in the buffer. Question Q-841087731518d866 (open) Relevant errors include:

• UninitializedContext: No key has yet been assigned to the context [SWS_CRYPT_50049].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The capacity of out or ivOut is insufficient [SWS_CRYPT_50049].
• ara::crypto::CryptoErrc::kUnsupported: Single-call encryption is not supported or the algorithm enforces the specification of an input IV [SWS_CRYPT_50049].
• ara::crypto::CryptoErrc::kUsageViolation or ara::crypto::CryptoErrc::kIncompatibleObject: The key type does not match the transformation or the key usage does not permit data encryption [SWS_CRYPT_50049].

use

The synchronous method Finish finalizes a symmetric encryption or decryption within ara::crypto::cryp::SymmetricCipherCtx without returning an initialization vector ([SWS_CRYPT_50045]). It processes the last data section from the input buffer in (ReadOnlyMemRegion) and writes the resulting data into the output buffer out (ReadWriteMemRegion) ([SWS_CRYPT_50045]). The buffer size required for this can be queried in advance via GetRequiredOutputBufferSize() ([SWS_CRYPT_50045]). In case of success, the return value of type ara::core::Result<std::size_t> provides the exact number of written bytes, which may be smaller than the total capacity of out ([SWS_CRYPT_50045]).

Error handling

In case of an error, the method returns a ara::core::Result with specific error codes ([SWS_CRYPT_50045]):

• ProcessingNotStarted: Data processing was not previously initiated by Start() ([SWS_CRYPT_50045]).
• ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer out is too small ([SWS_CRYPT_50045]).
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the input data cannot be processed ([SWS_CRYPT_50045]).
• ara::crypto::CryptoErrc::kInvalidArgument: The passed input data are invalid ([SWS_CRYPT_50045]).
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the current context ([SWS_CRYPT_50045]).

If one of the CryptoErrc errors occurs, rollback semantics take effect ([SWS_CRYPT_50045]).

Concurrency and Interaction

The operation is defined as thread-safe and exception safe ([SWS_CRYPT_50045]). Before the call, the transformation must strictly have been started by Start() ([SWS_CRYPT_50045]). The maximum permitted input size for individual calls of Finish() can be determined via GetMaximumChunkSize() ([SWS_CRYPT_50050]). After completion, the transformation run is presumably terminated, and a new call to Start() will likely be required for further operations. Question Q-c4ffc8028e8f522b (open)

The FinishEncrypt method completes an encryption operation and returns the initialization vector (IV) generated by the context [SWS_CRYPT_23618]. It processes the final input data buffer in and writes the resulting data to the output buffer out as well as the IV to ivOut. As a return value, it provides a ara::core::Result<std::size_t> with the actual size of the written output data, which can be smaller than the capacity of out [SWS_CRYPT_23618].

For error-free execution, buffer dimensions and context state must be coordinated in advance:

• The required buffer size for out can be determined via [SWS_CRYPT_50140] with parameter isFinal = true set. If out is dimensioned too small, the call fails with CryptoErrc::kInsufficientCapacity [SWS_CRYPT_23618].
• The expected size for ivOut can be queried via [SWS_CRYPT_50143].
• The input size of in must lie between the minimum and maximum limits defined by [SWS_CRYPT_50144] and [SWS_CRYPT_50050]; otherwise, CryptoErrc::kInvalidInputSize is returned [SWS_CRYPT_23618].

If data processing was not previously initiated by Start(), the method reports CryptoErrc::kProcessingNotStarted [SWS_CRYPT_23618]. If the input buffer contains invalid data, CryptoErrc::kInvalidArgument follows [SWS_CRYPT_23618]. Error CryptoErrc::kUnsupported occurs if stream processing is not supported, the context does not use an IV, or an IV was already passed in Start() [SWS_CRYPT_23618]. All errors have rollback semantics [SWS_CRYPT_23618]. According to the specification, the call is thread-safe and exception safe (noexcept) [SWS_CRYPT_23618].

The ProcessSingleCall method performs encryption or decryption in a single synchronous call without an initialization vector (IV) ([SWS_CRYPT_50047]). The data buffer in (ReadOnlyMemRegion) and the transformation direction transformDirection (CryptoTransform) serve as input parameters, while the result is written into the buffer out (ReadWriteMemRegion). Upon successful execution, the function returns a ara::core::Result<std::size_t> containing the number of written bytes; this value may be smaller than the total capacity of the output buffer.

Regarding concurrency and safety, the method is specified as thread-safe and exception safe ([SWS_CRYPT_50047]). The processable input size of in is subject to the limits defined by the context, which can be queried via [SWS_CRYPT_50144] (GetMinimumChunkSize) and [SWS_CRYPT_50050] (GetMaximumChunkSize).

All error cases follow rollback semantics ([SWS_CRYPT_50047]):

• ara::crypto::CryptoErrc::kUninitializedContext: The context was not initialized beforehand by assigning a key.
• ara::crypto::CryptoErrc::kUnsupported: Single-call processing is not supported, or the transformation requires setting or reading an IV.
• ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer out does not offer sufficient capacity.
• ara::crypto::CryptoErrc::kInvalidInputSize: The input size cannot be processed by the context.
• ara::crypto::CryptoErrc::kUsageViolation: The key usage does not cover the requested operation (kAllowDataEncryption or kAllowDataDecryption).
• ara::crypto::CryptoErrc::kIncompatibleObject, kEmptyKeySlot, kInvalidArgument, or kBusyResource: Key is incompatible, key slot is empty, input data are invalid, or required resources are busy.

In interaction with other interfaces, the call requires a fully configured context; for authenticating ciphers with additional tag processing, the alternative interface [SWS_CRYPT_50078] is available in AuthCipherCtx.

The ProcessSingleCallWithInputIv method on ara::crypto::cryp::SymmetricCipherCtx performs symmetric encryption or decryption of data in a single synchronous call (single-call) [SWS_CRYPT_50048]. In doing so, the initialization vector used for the transformation is explicitly passed via the input buffer iv.

Usage and Interaction

transformDirection controls whether the data from in are encrypted or decrypted. The result is written into the buffer out. The returned ara::core::Result<std::size_t> contains the actual number of written bytes, which may be less than the total capacity of out [SWS_CRYPT_50048].

Helper functions are available for dimensioning the buffers:

• The required buffer size for out can be calculated in advance via GetRequiredOutputBufferSize with the parameter isFinal = true [SWS_CRYPT_50140].
• The permitted length for iv can be determined for the selected transformation direction via GetMinimumInputIvSize [SWS_CRYPT_50141] as well as GetMaximumInputIvSize [SWS_CRYPT_50142].
• If the generation or verification of an authentication tag is additionally required, ara::crypto::cryp::AuthCipherCtx::ProcessSingleCallWithInputIv must be used instead [SWS_CRYPT_50079].

Error Handling and Concurrency

The operation is defined as thread-safe and exception safe [SWS_CRYPT_50048]. All errors have rollback semantics:

• CryptoErrc::kUninitializedContext or CryptoErrc::kEmptyKeySlot: No key was assigned to the context or the KeySlot is empty [SWS_CRYPT_50048].
• CryptoErrc::kUsageViolation: The key does not permit the selected direction (kAllowDataEncryption or kAllowDataDecryption is missing) [SWS_CRYPT_50048].
• CryptoErrc::kIncompatibleObject: The key type is incompatible with the transformation [SWS_CRYPT_50048].
• CryptoErrc::kInsufficientCapacity: The output buffer out is too small [SWS_CRYPT_50048].
• CryptoErrc::kInvalidInputSize or CryptoErrc::kInvalidArgument: Buffer size or content of in is invalid [SWS_CRYPT_50048].
• CryptoErrc::kUnsupported: Single-call processing or input IVs are not supported [SWS_CRYPT_50048].
• CryptoErrc::kBusyResource: A required resource is busy [SWS_CRYPT_50048].

The method Seek of the interface ara::crypto::cryp::SymmetricCipherCtx sets the position of the next byte to be processed within a data stream [SWS_CRYPT_23613]. The call is likely to be synchronous due to the absence of asynchronous return types such as futures. Question Q-fccf732722263f60 (open)

use

Positioning is controlled via two parameters [SWS_CRYPT_23613]:

• offset: Byte offset in the data stream, relative either to the beginning of the stream or the current position [SWS_CRYPT_23613].
• fromBegin: Reference point of the positioning; true addresses the offset from the beginning of the stream, false relative to the current position [SWS_CRYPT_23613].

The function is declared as noexcept and returns a ara::core::Result<void>, which signals successful completion or contains an occurred error object [SWS_CRYPT_23613].

Concurrency and Limitations

According to the specification, Seek is classified as exception safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_23613]. A prerequisite for execution is that data processing was previously initiated by calling Start() [SWS_CRYPT_23613].

Error handling

All error cases are subject to a defined rollback semantics (rollback_semantics), so that the internal state remains consistent upon errors [SWS_CRYPT_23613]:

• ara::crypto::CryptoErrc::kUnsupported: The seek operation is not supported by the current cryptographic context [SWS_CRYPT_23613].
• ara::crypto::CryptoErrc::kProcessingNotStarted: Data processing was not started in advance via Start() [SWS_CRYPT_23613].
• ara::crypto::CryptoErrc::kOutOfBounds: The resulting offset is too small or too large for the data stream [SWS_CRYPT_23613].
• ara::crypto::CryptoErrc::kInvalidArgument: The resulting offset is not aligned to a block boundary, although the context requires block alignment [SWS_CRYPT_23613].

The pure virtual method SetKey configures the instance of ara::crypto::cryp::SymmetricCipherCtx so that it uses the key from the passed KeySlot for future cryptographic operations [SWS_CRYPT_50043].

Usage and Call Context

The call is synchronous and accepts a KeySlot::Sptr containing a SymmetricKey as parameter keySlot [SWS_CRYPT_50043]. The return value is a ara::core::Result<void> that indicates success or, in case of an error, conveys an error code [SWS_CRYPT_50043]. The configuration causes the key stored in the slot not to be consulted until the actual encryption or decryption is started [SWS_CRYPT_50043].

Error handling

In case of an error, no exception is thrown (the method is specified as noexcept and exception safe); instead, an error code with rollback semantics is returned [SWS_CRYPT_50043]:

• ara::crypto::CryptoErrc::kIncompatibleObject: The passed KeySlot is incompatible with the cipher context [SWS_CRYPT_50043].
• ara::crypto::CryptoErrc::kUnsupported: The context implementation exclusively supports setting a direct key (such as SymmetricKey) and not assignment via a KeySlot [SWS_CRYPT_50043].

Concurrency and Interaction

The method is designated as thread-safe [SWS_CRYPT_50043]. Interpretation: The actual reading of the key material is presumably performed only when starting encryption or decryption, meaning that the slot must remain consistent until the transformation starts. Question Q-799125800ab0f93c (open) The concept of configuring contexts via KeySlot::Sptr instead of direct key objects aligns with the unified pattern of related crypto contexts, including KeyDerivationFunctionCtx [SWS_CRYPT_50010], MessageAuthnCodeCtx [SWS_CRYPT_50026], SymmetricKeyWrapperCtx [SWS_CRYPT_50034], and VerifierPublicCtx [SWS_CRYPT_50018].

use

The method SetKey serves to configure an instance of ara::crypto::cryp::SymmetricCipherCtx to use a passed symmetric key [SWS_CRYPT_50138]. As an input parameter, the function accepts the key to be used as a smart pointer key of type SymmetricKey::Sptr. The call is synchronous and returns an ara::core::Result<void>, which is empty upon successful assignment or provides an error code in case of error [SWS_CRYPT_50138]. The declaration is included via header ara/crypto/cryp/symmetric_cipher_ctx.h.

Error handling

Error handling guarantees rollback semantics, so that the context remains in its previous state upon failure of the assignment [SWS_CRYPT_50138]. Two specific errors are defined:

• ara::crypto::CryptoErrc::kUnsupported: Occurs when the context exclusively supports assigning a key via a KeySlot [SWS_CRYPT_50138].
• ara::crypto::CryptoErrc::kIncompatibleObject: Returned when the passed key object is not compatible with the context [SWS_CRYPT_50138].

Concurrency and Interaction

The virtual function is defined as noexcept, is considered exception-safe, and is implemented thread-safe according to the specification [SWS_CRYPT_50138]. Similar interfaces for assigning SymmetricKey::Sptr can be found in related crypto contexts such as AuthCipherCtx [SWS_CRYPT_23911] as well as SymmetricKeyWrapperCtx [SWS_CRYPT_24018]. Furthermore, context classes that alternatively accept KeySlot::Sptr illustrate the interaction with key containers [SWS_CRYPT_50034].

use

The method Start initializes the context ara::crypto::cryp::SymmetricCipherCtx for a new synchronous encryption or decryption operation and sets the associated initialization vector (IV) or nonce value [SWS_CRYPT_23625]. The transformation direction is specified via the parameter transformDirection, while iv provides the initialization vector as ReadOnlyMemRegion [SWS_CRYPT_23625]. The permitted size of the buffer can be queried in advance via the methods GetMinimumInputIvSize() and GetMaximumInputIvSize() [SWS_CRYPT_23625]. The call returns a ara::core::Result<void>, is declared as noexcept, and is considered exception safe [SWS_CRYPT_23625].

Error handling

In the event of an error, an error code with rollback semantics is returned [SWS_CRYPT_23625]:

• ara::crypto::CryptoErrc::kUninitializedContext: The context was not previously initialized by assigning a key [SWS_CRYPT_23625].
• ara::crypto::CryptoErrc::kInvalidInputSize: The passed IV size is not supported [SWS_CRYPT_23625].
• ara::crypto::CryptoErrc::kUnsupported: Setting an IV in the specified transformation direction or stream processing is not supported by the context [SWS_CRYPT_23625].
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently empty [SWS_CRYPT_23625].
• ara::crypto::CryptoErrc::kUsageViolation: The permitted key usage does not include kAllowDataEncryption for encryption or kAllowDataDecryption for decryption [SWS_CRYPT_23625].
• ara::crypto::CryptoErrc::kIncompatibleObject: The key type is incompatible with the transformation or transformation direction [SWS_CRYPT_23625].
• ara::crypto::CryptoErrc::kBusyResource: A required resource is busy [SWS_CRYPT_23625].

Concurrency and Interaction

The function is specified as thread-safe [SWS_CRYPT_23625]. In the course of stream processing, Start acts as an initiating step, which is followed, for example, by positioning operations via Seek [SWS_CRYPT_23613] or finalization via FinishEncrypt [SWS_CRYPT_23618].

use

The Start method initializes an instance of ara::crypto::cryp::SymmetricCipherCtx synchronously for upcoming encryption or decryption ([SWS_CRYPT_50044]). It is used when no initialization vector (IV) is required for the transformation direction specified via the parameter transformDirection or when the context generates it itself ([SWS_CRYPT_50044]). If, however, the context requires an explicit IV in the selected direction, the overload with IV parameter must be called ([SWS_CRYPT_23625]).

Error Handling and Concurrency

The operation is specified as thread-safe and exception-safe ([SWS_CRYPT_50044]). In case of an error, the function returns a ara::core::Result<void> with rollback semantics ([SWS_CRYPT_50044]). Relevant causes of error are:

• ara::crypto::CryptoErrc::kUninitializedContext: No key was assigned to the context in advance ([SWS_CRYPT_50044]).
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported or the operation mandatory requires setting an IV in this direction ([SWS_CRYPT_50044]).
• ara::crypto::CryptoErrc::kUsageViolation: The key does not possess the required permission kAllowDataEncryption or kAllowDataDecryption ([SWS_CRYPT_50044]).
• ara::crypto::CryptoErrc::kIncompatibleObject or ara::crypto::CryptoErrc::kEmptyKeySlot: The key type does not match the transformation or the configured key slot is empty ([SWS_CRYPT_50044]).
• ara::crypto::CryptoErrc::kBusyResource: A required resource is currently occupied ([SWS_CRYPT_50044]).

Interaction

After successful initialization, the data stream can be positioned via Seek if required ([SWS_CRYPT_23613]). If the IV was determined by the context itself, it is passed to the caller via FinishEncrypt at the end of encryption ([SWS_CRYPT_23618]).

The synchronous method Update() serves in ara::crypto::cryp::SymmetricCipherCtx for step-by-step encryption or decryption of partial data streams [SWS_CRYPT_50139]. It processes an input buffer in (type ReadOnlyMemRegion) containing plaintext or ciphertext and writes the transformed data into the output buffer out (type ReadWriteMemRegion) [SWS_CRYPT_50139]. In case of success, the return value ara::core::Result<std::size_t> provides the exact number of bytes actually written to out, which may be less than the total capacity of the destination buffer [SWS_CRYPT_50139].

Defined preconditions and buffer rules apply to the call:

• Execution order: Data processing must mandatorily have been initiated beforehand using the method Start(); otherwise, the call fails with ara::crypto::CryptoErrc::kProcessingNotStarted [SWS_CRYPT_50139].
• Buffer sizing: The maximum input size permitted per single call can be determined via GetMaximumChunkSize() [SWS_CRYPT_50050]; the method acknowledges invalid buffer sizes with ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50139]. The required output buffer can be queried via GetRequiredOutputBufferSize() [SWS_CRYPT_50139]; a buffer that is too small leads to ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50139].
• Streaming support: If the concrete context does not support continuous stream processing, the call fails with ara::crypto::CryptoErrc::kUnsupported [SWS_CRYPT_50139].

The interface is specified as thread-safe as well as exception safe and guarantees rollback semantics for every error [SWS_CRYPT_50139]. In the processing cycle, it interacts with GetMaximumChunkSize() as well as concluding operations such as Finish() or FinishEncrypt() [SWS_CRYPT_50050].