class ara::crypto::cryp::EncryptorPublicCtx

The method Cancel() aborts an active streaming operation in context ara::crypto::cryp::EncryptorPublicCtx that was previously initiated via Start() and has not yet finished [SWS_CRYPT_50089]. It takes no input parameters and returns a ara::core::Result<void>, which is empty on success [SWS_CRYPT_50089]. Since the signature returns a Result directly and not a Future, the abort is likely executed synchronously. Question Q-cd18e56d693fe1a4 (open)

Error Handling and Concurrency

If data processing was not started in advance by Start(), the operation fails with the error code ara::crypto::CryptoErrc::kProcessingNotStarted complying with rollback semantics [SWS_CRYPT_50089]. According to the specification, the interface is declared with noexcept, exception safe, and classified as thread-safe for concurrent access [SWS_CRYPT_50089].

Interaction in the Crypto Stack

The abort behavior implemented by Cancel() follows a unified design pattern for stateful streaming operations in the crypto module. Analogous interfaces with identical error semantics exist for:

• signature and verification operations in SignerPrivateCtx [SWS_CRYPT_50041] and VerifierPublicCtx [SWS_CRYPT_50023],
• symmetric and authenticated ciphers in SymmetricCipherCtx [SWS_CRYPT_50046] as well as AuthCipherCtx [SWS_CRYPT_50077],
• asymmetric decryption in DecryptorPrivateCtx [SWS_CRYPT_50069],
• message authentication codes in MessageAuthnCodeCtx [SWS_CRYPT_50027] as well as hash computations in HashFunctionCtx [SWS_CRYPT_50058].

The synchronous method Encrypt serves to encrypt plaintext data in a single call ([SWS_CRYPT_50090]). It accepts the input data from buffer in (ReadOnlyMemRegion) and writes the ciphertext into the output buffer out (ReadWriteMemRegion) ([SWS_CRYPT_50090]). In the success case, the return value ara::core::Result<std::size_t> returns the size of the output data actually written, which may be smaller than the total capacity of out ([SWS_CRYPT_50090]).

With respect to concurrency, the function is specified as thread-safe (thread-safe) as well as exception-safe (exception safe) ([SWS_CRYPT_50090]).

In interaction with context EncryptorPublicCtx, the following buffer limits must be observed prior to the call:

• The input size must be within the limits specified by [SWS_CRYPT_50178] (GetMinimumChunkSize) and [SWS_CRYPT_50091] (GetMaximumChunkSize).
• The maximum required capacity of the output buffer out can be calculated in advance via GetRequiredOutputBufferSize with the parameter isFinal = true ([SWS_CRYPT_50177]).

All error cases have rollback semantics ([SWS_CRYPT_50090]). The defined errors from ara::crypto::CryptoErrc include:

• kUninitializedContext: The context was not initialized by providing a key ([SWS_CRYPT_50090]).
• kEmptyKeySlot: A configured KeySlot is empty ([SWS_CRYPT_50090]).
• kIncompatibleObject: The key type does not match the transformation ([SWS_CRYPT_50090]).
• kUsageViolation: The key usage does not permit data encryption (kAllowDataEncryption) ([SWS_CRYPT_50090]).
• kInsufficientCapacity: The buffer out is too small ([SWS_CRYPT_50090]).
• kInvalidInputSize or kInvalidArgument: The input size cannot be processed or the input data is invalid ([SWS_CRYPT_50090]).
• kUnsupported: Single-call encryption is not supported ([SWS_CRYPT_50090]).
• kBusyResource: A required resource is busy ([SWS_CRYPT_50090]).

use

The method Finish completes the asymmetric encryption operation in the context of ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50088]. The call is synchronous and is specified as noexcept, exception-safe, and thread-safe. As parameters, the function accepts the final plaintext fragment via in (ReadOnlyMemRegion) and writes the resulting ciphertext data to the output buffer out (ReadWriteMemRegion). The required buffer size for out can be determined in advance via GetRequiredOutputBufferSize(). The return value ara::core::Result<std::size_t> returns the number of bytes actually written in the success case, which may be smaller than the total capacity of the output buffer [SWS_CRYPT_50088].

Error Handling and Concurrency

All error cases have rollback semantics, so that the context state remains consistent upon failure [SWS_CRYPT_50088]. The method reports the following specific error codes from ara::crypto::CryptoErrc:

• kProcessingNotStarted: Data processing was not previously initiated by calling Start().
• kInsufficientCapacity: The provided output buffer out is dimensioned too small.
• kInvalidInputSize: The buffer size of in cannot be processed by the context.
• kInvalidArgument: The passed input data contains invalid values.
• kUnsupported: Stream processing is not supported by the concrete context.

Interaction

Finalization concludes the cryptographic processing sequence [SWS_CRYPT_50088]. DecryptorPrivateCtx::Finish [SWS_CRYPT_50068] acts as the complementary counterpart for decryption, while in the area of symmetric ciphers SymmetricCipherCtx::Finish [SWS_CRYPT_50045] provides a comparable sequence pattern.

Usage and Call Context

The pure virtual method SetKey of interface ara::crypto::cryp::EncryptorPublicCtx (header file ara/crypto/cryp/encryptor_public_ctx.h) serves to assign a key for asymmetric cipher operations [SWS_CRYPT_50086]. A smart pointer keySlot of type KeySlot::Sptr, which must contain a PublicKey, is passed as a parameter [SWS_CRYPT_50086]. The call is synchronous and signals success via an empty ara::core::Result<void>. Essential for the semantics is that the key stored in the slot is used only at the point in time when the encryption is started [SWS_CRYPT_50086]. (Interpretation: Since key resolution takes place only with the actual encryption start, updates to the slot content before this start time should still take effect.) Question Q-25c5d462aafde8a1 (open)

Error handling

If configuration fails, an error code with rollback semantics is returned in the result object [SWS_CRYPT_50086]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Reported if the provided keySlot is incompatible with this context [SWS_CRYPT_50086].
• ara::crypto::CryptoErrc::kUnsupported: Occurs if the concrete context implementation exclusively supports direct setting of a PublicKey and does not permit key binding via a KeySlot [SWS_CRYPT_50086].

Concurrency and Interaction

The operation is declared as noexcept, exception-safe (exception safe), and specified as thread-safe (thread-safe) for concurrent use [SWS_CRYPT_50086].

The concept of indirect key referencing via KeySlot is also found in a comparable manner in other asymmetric contexts, such as VerifierPublicCtx::SetKey [SWS_CRYPT_50018] and KeyEncapsulatorPublicCtx::SetKey [SWS_CRYPT_50012]. It differs from methods that accept key objects directly, such as in [SWS_CRYPT_24115] or [SWS_CRYPT_21815].

use

The virtual method SetKey of class ara::crypto::cryp::EncryptorPublicCtx configures the context to use a provided public key [SWS_CRYPT_50175]. The key object to be used for encryption is passed via parameter key (of type PublicKey::Sptr) [SWS_CRYPT_50175]. Execution is synchronous and returns a ara::core::Result<void>, which contains no value on success [SWS_CRYPT_50175].

Error handling

If an error occurs during configuration, a corresponding error code with defined rollback semantics is reported [SWS_CRYPT_50175]:

• ara::crypto::CryptoErrc::kUsageViolation: The allowed key usage does not permit data encryption (kAllowDataEncryption) [SWS_CRYPT_50175].
• ara::crypto::CryptoErrc::kIncompatibleObject: The passed key object is incompatible with this encryption context [SWS_CRYPT_50175].
• ara::crypto::CryptoErrc::kUnsupported: The concrete context implementation exclusively supports binding via a KeySlot [SWS_CRYPT_50175].

Concurrency and Limitations

The interface is defined as noexcept and specifies a behavior that is both thread-safe and exception safe [SWS_CRYPT_50175]. Thanks to the rollback semantics, the context remains in its previous state in the event of an error. Interpretation: A successful call is likely a mandatory prerequisite for subsequent encryption operations, as the context cannot perform any operations without an assigned key. Question Q-ab4779cac18793fa (open)

Interaction

This approach follows the module-wide pattern of asymmetric contexts, as also used in VerifierPublicCtx::SetKey [SWS_CRYPT_24115] and KeyEncapsulatorPublicCtx::SetKey [SWS_CRYPT_21815] for key binding. Alternatively, related interfaces also provide KeySlot variants for configuration, such as in VerifierPublicCtx [SWS_CRYPT_50018] or KeyEncapsulatorPublicCtx [SWS_CRYPT_50012].

Usage and Semantics

The pure virtual method Start of class ara::crypto::cryp::EncryptorPublicCtx serves to initialize the context for a new encryption [SWS_CRYPT_50087]. It takes no input parameters and is executed synchronously. As a return value, the function returns an ara::core::Result<void> that either confirms successful initialization or conveys an occurred error code [SWS_CRYPT_50087].

Error handling and rollback behavior

If the required preconditions for the encryption operation are not met, the call fails. The specification guarantees rollback semantics for error cases and defines the following error causes [SWS_CRYPT_50087]:

• UninitializedContext: No key was assigned to the context in advance.
• ara::crypto::CryptoErrc::kEmptyKeySlot: A configured KeySlot is currently unoccupied.
• ara::crypto::CryptoErrc::kUsageViolation: The permissions of the key do not contain the usage flag kAllowDataEncryption.
• ara::crypto::CryptoErrc::kIncompatibleObject: The assigned key type is incompatible with the required transformation.
• ara::crypto::CryptoErrc::kBusyResource: A resource required for initialization is occupied.
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the concrete context.

Concurrency and Interaction

The method is specified as thread-safe and exception safe [SWS_CRYPT_50087]. Providing a suitable key in the context is a mandatory precondition for success. Conceptually, the function fits into standardized lifecycles of cryptographic contexts in which operations are prepared via parameterless calls – comparable to signature verifications [SWS_CRYPT_50019], signature generations [SWS_CRYPT_50037], or MAC calculations [SWS_CRYPT_22111]. The call should represent the mandatory starting point before the actual execution of a stream encryption. Question Q-db262c3914e6b4cf (open)

use

The synchronous method Update of class ara::crypto::cryp::EncryptorPublicCtx serves to encrypt plaintext data blocks step by step [SWS_CRYPT_50176]. A portion of the plaintext is passed via parameter in (ReadOnlyMemRegion), while the encrypted data is written to the output buffer out (ReadWriteMemRegion) [SWS_CRYPT_50176]. As a return value, the function provides via ara::core::Result<std::size_t> the actual number of bytes written, which can be smaller than the provided capacity of out [SWS_CRYPT_50176].

Sequence and Interaction

Prior to the first call to Update, data processing must mandatory have been initiated by Start() [SWS_CRYPT_50176]. The maximum permitted input size for individual calls can be queried via method GetMaximumChunkSize() [SWS_CRYPT_50091]. In addition, the minimum size required for out can be calculated via GetRequiredOutputBufferSize() [SWS_CRYPT_50176].

Error Handling and Concurrency

If an error occurs during execution, it is reported with rollback semantics [SWS_CRYPT_50176]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Data processing was not previously started with Start() [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The capacity of buffer out is insufficient for the result [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kInvalidInputSize: The buffer size of in is invalid [SWS_CRYPT_50176].
• ara::crypto::CryptoErrc::kUnsupported: Stream processing is not supported by the current context [SWS_CRYPT_50176].

The method is declared as exception-safe and thread-safe [SWS_CRYPT_50176]. Nevertheless, parallel calls of multiple operations on the same context object are presumably likely to require external synchronization in order to guarantee a deterministic order of the encrypted data fragments. Question Q-b22ffe505b583b25 (open)