class ara::crypto::cryp::SignerPrivateCtx

The method Cancel() serves to synchronously abort an ongoing, not yet completed streaming operation within class ara::crypto::cryp::SignerPrivateCtx that was previously initiated by a call to Start() [SWS_CRYPT_50041]. The purely virtual interface virtual ara::core::Result<void> Cancel() noexcept = 0; is declared in header ara/crypto/cryp/signer_private_ctx.h, takes no input parameters, and signals successful abort via an empty ara::core::Result<void> [SWS_CRYPT_50041]. For the caller, the method is specified as exception-safe (exception safe) and concurrently thread-safe (thread-safe) [SWS_CRYPT_50041].

Regarding call sequence and error handling, Cancel() strictly requires active processing: If data processing was not previously initiated by a call to method Start(), the abort fails and returns the error code ara::crypto::CryptoErrc::kProcessingNotStarted with defined rollback semantics [SWS_CRYPT_50041]. Interpretation: After a successful call to Cancel(), the context should return to an unstarted basic state so that a new signature or streaming process can be started. Question Q-348fb3ae43e424c9 (open)

The design follows a uniform principle for all streaming operations in the crypto module. Completely identical signatures and error semantics exist for related contexts such as VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SymmetricCipherCtx [SWS_CRYPT_50046], HashFunctionCtx [SWS_CRYPT_50058], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077], and EncryptorPublicCtx [SWS_CRYPT_50089].

use

The ara::crypto::cryp::SignerPrivateCtx::Finish method synchronously completes signature generation and writes the calculated signature directly into the provided output buffer signature [SWS_CRYPT_50040]. The function expects the writable memory area signature (type ReadWriteMemRegion) and the desired format signatureFormat (type FormatId) as input parameters [SWS_CRYPT_50040]. As the return value, ara::core::Result<size_t> provides the actual byte size of the written signature data; this amount of data may be smaller than the capacity of the destination buffer [SWS_CRYPT_50040].

Error handling

Rollback semantics are specified for all occurring error cases [SWS_CRYPT_50040]. The following error codes can be returned via the result:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Signature generation was not successfully started beforehand [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The capacity of the passed output buffer signature is too small [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kUnsupportedFormat: The value of signatureFormat is unknown or not supported [SWS_CRYPT_50040].

Concurrency and Limitations

The method is specified as thread-safe and exception safe and must not throw exceptions (noexcept) [SWS_CRYPT_50040]. A valid call strictly requires that the generation process in the context was successfully initiated beforehand [SWS_CRYPT_50040].

Interaction

The direct functional counterpart for verifying the generated signature is the ara::crypto::cryp::VerifierPublicCtx::Finish method [SWS_CRYPT_50022]. In contrast to contexts for hash or MAC calculations, where Finish() only finalizes the calculation and the intermediate or final result is fetched separately [SWS_CRYPT_21115] [SWS_CRYPT_21116], SignerPrivateCtx::Finish writes the signature directly into the buffer [SWS_CRYPT_50040].

use

The virtual method SetKey of class ara::crypto::cryp::SignerPrivateCtx (#include "ara/crypto/cryp/signer_private_ctx.h") configures the signing context for the use of a provided private key [SWS_CRYPT_23515]. Parameter key of type PrivateKey::Sptr is passed as the source key object [SWS_CRYPT_23515]. The method executes synchronously and returns a ara::core::Result<void>, which is empty on success or carries the occurred error code in case of error [SWS_CRYPT_23515].

Error handling

If an error occurs during configuration, rollback semantics take effect [SWS_CRYPT_23515]. The following error codes are specified:

• ara::crypto::CryptoErrc::kIncompatibleObject: The passed key object is incompatible with the current context [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUsageViolation: The permitted usage of the key does not include signature generation (kAllowSig Generation) [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUnsupported: The specific context exclusively supports setting via a KeySlot [SWS_CRYPT_23515].

Concurrency and Limitations

The interface is declared as noexcept and, according to the specification, is classified as both exception safe ("exception safe") and thread-safe ("thread-safe") [SWS_CRYPT_23515].

Interaction

In SignerPrivateCtx, the overload SetKey(KeySlot::Sptr) alternatively exists, which configures the context such that the key stored in a KeySlot is only used at the start time of the signature calculation [SWS_CRYPT_50036]. For checking signatures on the verification side, the functional counterpart SetKey with PublicKey::Sptr within ara::crypto::cryp::VerifierPublicCtx serves [SWS_CRYPT_24115].

use

The SetKey method configures the signing context [SWS_CRYPT_50036] to use a key located in the passed KeySlot::Sptr. The key is only referenced at the point in time when the actual signature calculation is started [SWS_CRYPT_50036]. The call is synchronous, declared as noexcept, and returns a ara::core::Result<void> [SWS_CRYPT_50036].

Error handling

If the configuration fails, an error is transmitted in the return object, with rollback semantics applying [SWS_CRYPT_50036]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Occurs if the provided keySlot is not compatible with this signing context [SWS_CRYPT_50036].
• ara::crypto::CryptoErrc::kUnsupported: Is reported if the context exclusively supports setting a PrivateKey directly [SWS_CRYPT_50036].

Concurrency and Interaction

The interface belongs to class ara::crypto::cryp::SignerPrivateCtx and is specified as thread-safe as well as exception-safe [SWS_CRYPT_50036]. In addition to this slot-based variant, SignerPrivateCtx also provides an overload that directly accepts a PrivateKey::Sptr object [SWS_CRYPT_23515]. Analogous slot bindings exist for further cryptographic contexts, such as for signature verification with KeySlot in VerifierPublicCtx [SWS_CRYPT_50018] or for key derivation in KeyDerivationFunctionCtx [SWS_CRYPT_50010].

The method Sign signs a message synchronously in a single step according to [SWS_CRYPT_23512]. It accepts the input message to be signed (message), the destination buffer (signature), the desired signature format (signatureFormat), and optionally a context value (context). In case of success, the function returns the actual byte size of the generated signature via ara::core::Result<std::size_t>, which may be smaller than the capacity of the destination buffer [SWS_CRYPT_23512].

Regarding concurrency and exception safety, the method is declared as noexcept, is considered exception safe, and is explicitly specified as thread-safe [SWS_CRYPT_23512].

Prior to the call, the context must be properly initialized with a key value; otherwise, UninitializedContext is reported [SWS_CRYPT_23512]. Regarding the input length, Sign interacts with [SWS_CRYPT_50042]: via GetMaximumChunkSize, the maximum supported buffer size for single-step processing can be determined in order to prevent errors such as ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_23512] [SWS_CRYPT_50042].

Error handling provides rollback semantics for specific error codes [SWS_CRYPT_23512]:

• ara::crypto::CryptoErrc::kInsufficientCapacity: The output buffer signature is too small.
• ara::crypto::CryptoErrc::kUnsupported: Single-step processing is not supported, or the context specification context does not comply with the specifications.
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified FormatId is unknown or not supported.
• ara::crypto::CryptoErrc::kUsageViolation: The permitted key usage does not include kAllowSig Generation.
• ara::crypto::CryptoErrc::kEmptyKeySlot or ara::crypto::CryptoErrc::kBusyResource: The configured KeySlot is empty or a required resource is busy.

The parameterless method Start initializes a context of class ara::crypto::cryp::SignerPrivateCtx for a new signature generation [SWS_CRYPT_50037]. The call is synchronous, declared as noexcept, and returns an empty ara::core::Result<void> upon successful initialization or an error code in case of an error [SWS_CRYPT_50037].

In case of an error, the operation supports rollback semantics [SWS_CRYPT_50037]. Defined error causes from ara::crypto::CryptoErrc include:

• kUninitializedContext: The context was not previously initialized by providing a key [SWS_CRYPT_50037].
• kEmptyKeySlot: A configured key slot is currently empty [SWS_CRYPT_50037].
• kUsageViolation: The permissions of the assigned key do not include kAllowSigGeneration [SWS_CRYPT_50037].
• kBusyResource: A resource required for the operation is busy [SWS_CRYPT_50037].
• kUnsupported: The context does not support streaming or the signature algorithm strictly requires specifying a context value [SWS_CRYPT_50037].

According to the specification, the function is thread-safe as well as exception safe [SWS_CRYPT_50037]. If the algorithm requires a specific context value, the overloaded variant Start(ReadOnlyMemRegion context) must be used alternatively [SWS_CRYPT_50038]. After a successful call to Start, message parts to be signed can be processed continuously via Update [SWS_CRYPT_50039].

The Start method is used for the synchronous initialization of the context ara::crypto::cryp::SignerPrivateCtx for a new signature generation while providing a context value ([SWS_CRYPT_50038]). It accepts parameter context of type ReadOnlyMemRegion and returns a ara::core::Result<void>. The function is specified as noexcept=0, declared exception-safe, and thread-safe ([SWS_CRYPT_50038]).

In case of an error, the context state is left unchanged via rollback semantics ([SWS_CRYPT_50038]). Specified error causes are:

• UninitializedContext: if the context was not initialized beforehand by providing a key.
• ara::crypto::CryptoErrc::kUnsupported: if the context does not support streaming or the algorithm does not permit a context value.
• ara::crypto::CryptoErrc::kInvalidInputSize: if the buffer size of the passed context value is invalid.
• ara::crypto::CryptoErrc::kEmptyKeySlot: if a configured key slot is currently empty.
• ara::crypto::CryptoErrc::kUsageViolation: if the permitted key usage does not include signature generation (kAllowSig Generation).
• ara::crypto::CryptoErrc::kBusyResource: if a required resource is busy.

In the typical processing flow, the data to be signed are presumably passed successively via Update ([SWS_CRYPT_50039]) after a successful start. Question Q-7b821391730c9d38 (open) If the cryptographic algorithm does not require a context value, the parameterless overload Start() is available as an alternative ([SWS_CRYPT_50037]).

The Update method serves in [SWS_CRYPT_50039] to continuously extend the internal state of a signature calculation by another segment of the message. The call is synchronous and processes the passed memory area data of type ReadOnlyMemRegion. As a result, the function returns a ara::core::Result<void>, which contains no value upon successful processing or otherwise encapsulates an error code [SWS_CRYPT_50039].

In case of an error, the return values possess rollback semantics [SWS_CRYPT_50039]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Occurs if the signature calculation was not previously initiated by calling the Start() method [SWS_CRYPT_50039].
• ara::crypto::CryptoErrc::kInvalidInputSize: Is reported if the size of the provided input data is not supported by the context [SWS_CRYPT_50039].

Regarding concurrency and safety, the method is declared as thread-safe as well as exception safe [SWS_CRYPT_50039]. In interaction with the signing context, calculation strictly requires that the process was started with Start(). The maximum permitted buffer size for individual calls can be queried via GetMaximumChunkSize() [SWS_CRYPT_50042]; this limit likely represents the upper bound, exceeding which leads to kInvalidInputSize. Question Q-cf204a853a730365 (open)