class ara::crypto::cryp::DecryptorPrivateCtx

Method Cancel of class ara::crypto::cryp::DecryptorPrivateCtx, defined in ara/crypto/cryp/decryptor_private_ctx.h, aborts an ongoing streaming operation that was previously initiated by means of Start() and has not yet been completed [SWS_CRYPT_50069]. The call takes no input parameters and returns a ara::core::Result<void> as return value [SWS_CRYPT_50069]. If the abort of the streaming processing was successful, the object contains an empty result; otherwise, it conveys an occurred error [SWS_CRYPT_50069]. The purely virtual interface is declared as noexcept, exhibits complete exception safety, and is designated as thread-safe for concurrent access [SWS_CRYPT_50069].

In error handling and pre-conditions, the exact sequence must be observed: If data processing was not previously initiated by calling the Start() method, the operation fails and returns the specific error code ara::crypto::CryptoErrc::kProcessingNotStarted with rollback semantics [SWS_CRYPT_50069]. The caller must therefore ensure that an active operation already exists prior to the abort in order to avoid this error state [SWS_CRYPT_50069].

In interaction with the overall module architecture of crypt, Cancel follows a standardized design pattern for stateful streaming operations. The related cryptographic 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::AuthCipherCtx [SWS_CRYPT_50077], and ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50089] share the same signature, return semantics, and error handling.

The synchronous method Decrypt decrypts ciphertext data in a single step ([SWS_CRYPT_50070]). The input buffer in passes the ciphertext as ReadOnlyMemRegion, while the output buffer out of type ReadWriteMemRegion receives the plaintext ([SWS_CRYPT_50070]). Upon successful decryption, the function returns the actual number of bytes written via ara::core::Result<std::size_t>, which may be smaller than the total capacity of out ([SWS_CRYPT_50070]).

The interface is specified as thread-safe as well as exception-safe ([SWS_CRYPT_50070]). Before the call, the context must have been initialized by assigning a key; otherwise the function fails with UninitializedContext or, if the KeySlot is empty, with ara::crypto::CryptoErrc::kEmptyKeySlot ([SWS_CRYPT_50070]). The key must be compatible with the transformation algorithm (otherwise kIncompatibleObject) and include permission kAllowDataDecryption (otherwise kUsageViolation) ([SWS_CRYPT_50070]).

To prevent buffer overflows, the maximum required capacity of the output buffer can be queried in advance using GetRequiredOutputBufferSize by specifying isFinal = true ([SWS_CRYPT_50159]). If the capacity of out is insufficient, the method aborts with ara::crypto::CryptoErrc::kInsufficientCapacity ([SWS_CRYPT_50070]). Furthermore, the size of the input buffer in must be in the range between GetMinimumChunkSize ([SWS_CRYPT_50160]) and GetMaximumChunkSize ([SWS_CRYPT_50071]); otherwise ara::crypto::CryptoErrc::kInvalidInputSize is returned ([SWS_CRYPT_50070]). Other specified errors with rollback semantics are kUnsupported, kInvalidArgument, and kBusyResource ([SWS_CRYPT_50070]).

The Finish method synchronously completes a decryption process in the context of ara::crypto::cryp::DecryptorPrivateCtx [SWS_CRYPT_50068]. Via the input buffer in (ReadOnlyMemRegion), it processes the last ciphertext segment and writes the resulting plaintext data into the output buffer out (ReadWriteMemRegion) [SWS_CRYPT_50068]. The actual number of written bytes is returned as ara::core::Result<std::size_t> and may be smaller than the total capacity of the destination buffer out [SWS_CRYPT_50068].

Prior to the call, data processing must strictly have been initiated with Start(); otherwise, the error CryptoErrc::kProcessingNotStarted is reported [SWS_CRYPT_50068]. The maximum permitted block size for in can be determined via GetMaximumChunkSize() [SWS_CRYPT_50071]; if the input length is inappropriate, the call fails with CryptoErrc::kInvalidInputSize [SWS_CRYPT_50068]. If out is too small, CryptoErrc::kInsufficientCapacity results, where the required buffer size can be queried using GetRequiredOutputBufferSize() [SWS_CRYPT_50068]. Further possible errors are CryptoErrc::kInvalidArgument in case of invalid ciphertext data as well as CryptoErrc::kUnsupported if stream processing is not supported in the context [SWS_CRYPT_50068].

The operation is specified as thread-safe as well as exception safe [SWS_CRYPT_50068]. Thanks to the designated rollback semantics, the processing state is expected to remain unchanged in the event of buffer errors, so that a retry should be possible after increasing the buffer size. Question Q-e2562509449aa32c (open)

use

The SetKey method configures an instance of ara::crypto::cryp::DecryptorPrivateCtx for the use of a key stored in a passed KeySlot [SWS_CRYPT_50066]. A KeySlot::Sptr is passed as a parameter, which must contain a PrivateKey [SWS_CRYPT_50066]. The actual key is only referenced at the point in time when the decryption operation is started [SWS_CRYPT_50066]. The function operates synchronously and reports the result back via ara::core::Result<void> [SWS_CRYPT_50066].

Error handling

In case of an error, a corresponding error code is returned in the ara::core::Result, whereby rollback semantics apply [SWS_CRYPT_50066]:

• ara::crypto::CryptoErrc::kIncompatibleObject: The provided KeySlot is not compatible with the context [SWS_CRYPT_50066].
• ara::crypto::CryptoErrc::kUnsupported: The context supports only setting a PrivateKey directly and does not support KeySlots [SWS_CRYPT_50066].

Concurrency and Interaction

The interface is declared thread-safe (thread-safe) and exception-safe (exception safe) [SWS_CRYPT_50066]. Since the key is evaluated only when decryption starts, updating the slot content prior to this start time should take effect. Question Q-ec258ea8b5a1d1c2 (open) While other cryptographic contexts accept keys partly directly as an instance (for example, SignerPrivateCtx [SWS_CRYPT_23515]), this method follows the pattern of deferred binding via key slots, as is also used in VerifierPublicCtx [SWS_CRYPT_50018] and KeyDerivationFunctionCtx [SWS_CRYPT_50010], among others.

use

The SetKey method configures an instance of ara::crypto::cryp::DecryptorPrivateCtx to use a specific private key for data decryption [SWS_CRYPT_50157]. An instance is passed as a parameter via PrivateKey::Sptr key. The return value is ara::core::Result<void>, confirming successful assignment or returning an error. The call is expected to be executed synchronously (interpretation: the interface blocks until the key is accepted and does not return an asynchronous future object). Question Q-b8e9b5cb4174e2b2 (open)

Error handling

In the event of an error, the implementation ensures rollback semantics so that the context state remains unchanged upon failure [SWS_CRYPT_50157]. The following error codes can occur:

• ara::crypto::CryptoErrc::kIncompatibleObject: The passed key object is not compatible with this context [SWS_CRYPT_50157].
• ara::crypto::CryptoErrc::kUsageViolation: The allowed key usage does not include data decryption (kAllowData Decryption) [SWS_CRYPT_50157].
• ara::crypto::CryptoErrc::kUnsupported: The context does not support directly setting a key object if it is exclusively designed for assignment via a KeySlot [SWS_CRYPT_50157].

Concurrency and Limitations

The interface is explicitly specified as thread-safe and exception safe [SWS_CRYPT_50157]. It guarantees safe execution in concurrent environments and throws no C++ exceptions (noexcept=0).

Interaction

The procedure for key assignment via SetKey is applied uniformly across various cryptographic contexts in the Adaptive Platform: While related asymmetric contexts such as KeyAgreementPrivateCtx [SWS_CRYPT_21313], KeyDecapsulatorPrivateCtx [SWS_CRYPT_21413], and SignerPrivateCtx [SWS_CRYPT_23515] also use PrivateKey::Sptr, alternative variants with KeySlot::Sptr exist in other contexts such as KeyDerivationFunctionCtx [SWS_CRYPT_50010] or VerifierPublicCtx [SWS_CRYPT_50018].

The member function Start of class ara::crypto::cryp::DecryptorPrivateCtx ([SWS_CRYPT_50067]) synchronously initializes the context for a new decryption. The call takes no parameters, throws no exceptions (noexcept), and returns an ara::core::Result<void> that is empty in the success case ([SWS_CRYPT_50067]). For concurrent accesses, the method is specified as thread-safe ([SWS_CRYPT_50067]).

Before execution, a compatible key must be stored, as Start checks its state and permissions ([SWS_CRYPT_50067]). If the operation fails, rollback semantics apply ([SWS_CRYPT_50067]). Relevant error codes are:

• ara::crypto::CryptoErrc::kUninitializedContext: No key has been assigned to the context yet ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently empty ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kUsageViolation: The permissions of the key do not permit data decryption ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kIncompatibleObject: The key type is incompatible with the transformation ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kBusyResource: A required resource is busy ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the context ([SWS_CRYPT_50067]).

In the overall system, the method corresponds to the standardized lifecycle of adaptive crypto contexts, as is used comparably for signature verification ([SWS_CRYPT_50019]), signature generation ([SWS_CRYPT_50037]), or MAC calculation ([SWS_CRYPT_22111]). Interpretation: A call to Start should presumably be strictly required before further processing steps in order to put the decryptor into a defined initial state. Question Q-7d5a95305eb4626a (open)

use

The Update method serves to decrypt a data buffer in the context of ara::crypto::cryp::DecryptorPrivateCtx [SWS_CRYPT_50158]. The synchronous call receives a ciphertext subsection in parameter in (ReadOnlyMemRegion) and writes the decrypted data into buffer out (ReadWriteMemRegion) [SWS_CRYPT_50158]. The result returned is a ara::core::Result<std::size_t> containing the actual number of bytes written; this value can be smaller than the total capacity of out [SWS_CRYPT_50158].

Interaction and Buffer Dimensioning

Prior to executing Update, data processing must mandatory have been initiated by calling Start() [SWS_CRYPT_50158]. The minimum size required for out can be queried via GetRequiredOutputBufferSize() [SWS_CRYPT_50158]. In addition, the maximum input size that can be processed for individual Update calls can be determined via GetMaximumChunkSize() [SWS_CRYPT_50071].

Error Handling and Concurrency

The interface is specified as thread-safe and exception-safe [SWS_CRYPT_50158]. All error cases have rollback semantics and return specific error codes in ara::core::Result [SWS_CRYPT_50158]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Processing was not previously started using Start() [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kInsufficientCapacity: Output buffer out is sized too small [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed input buffer is invalid [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the context [SWS_CRYPT_50158].