class ara::crypto::cryp::VerifierPublicCtx

Usage and Semantics

The method Cancel() aborts an ongoing streaming operation that was previously initiated by Start() and has not yet been completed [SWS_CRYPT_50023]. It is defined in header ara/crypto/cryp/verifier_public_ctx.h as a pure virtual method of context ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023]. The call is synchronous and takes no arguments. The return value is a ara::core::Result<void>, which is empty on success and confirms the successful cancellation of the operation [SWS_CRYPT_50023].

Error handling

If data processing has not yet been started by calling the method Start(), the abort operation fails. In this scenario, the function returns an error result with error code ara::crypto::CryptoErrc::kProcessingNotStarted while guaranteeing rollback semantics [SWS_CRYPT_50023].

Concurrency and Limitations

The specification identifies the method as thread-safe and exception safe with the designation noexcept [SWS_CRYPT_50023]. Interpretation: After a successful abort, the context is likely to revert to the initial state prior to the start of processing so that a new streaming process can be started. Question Q-d80d09c8a8311bbc (open)

Interaction in Module crypt

This uniform cancellation pattern with identical signature and error handling applies consistently to all streaming contexts of module crypt:

• MessageAuthnCodeCtx for Message Authentication Codes [SWS_CRYPT_50027],
• SignerPrivateCtx for digital signature generation [SWS_CRYPT_50041],
• SymmetricCipherCtx for symmetric encryption and decryption [SWS_CRYPT_50046],
• HashFunctionCtx for cryptographic hash operations [SWS_CRYPT_50058],
• DecryptorPrivateCtx for asymmetric decryption [SWS_CRYPT_50069],
• AuthCipherCtx for authenticated encryption [SWS_CRYPT_50077], and
• EncryptorPublicCtx for asymmetric encryption [SWS_CRYPT_50089].

The Finish method in ara::crypto::cryp::VerifierPublicCtx completes a signature verification and returns the verification result [SWS_CRYPT_50022]. Via the input buffer signature (type ReadOnlyMemRegion), it accepts the signature to be verified, and via signatureFormat (type FormatId), its format [SWS_CRYPT_50022]. The call is synchronous and is declared thread-safe and exception safe according to the specification [SWS_CRYPT_50022].

A ara::core::Result<bool> serves as the return value [SWS_CRYPT_50022]: Upon successful validation of the signature, the result contains true, and in case of an invalid signature content, false. If, on the other hand, a processing error occurs, a corresponding error code is returned [SWS_CRYPT_50022]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: The operation was not successfully started beforehand (rollback semantics) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidInputSize: The buffer size of signature is invalid (rollback semantics) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kUnsupportedFormat: The specified format signatureFormat is not supported (rollback semantics) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidArgument: The signature does not match the specified format (rollback semantics) [SWS_CRYPT_50022].

In the cryptographic flow, this function forms the counterpart to signature generation via ara::crypto::cryp::SignerPrivateCtx::Finish [SWS_CRYPT_50040], which writes a signature into an output buffer. All reported errors have rollback semantics [SWS_CRYPT_50022], so that the context state remains consistent in the event of a failure.

The method SetKey configures an instance of VerifierPublicCtx for using a specific public key for signature verification ([SWS_CRYPT_24115]). A pointer of type PublicKey::Sptr is passed via the parameter key. The call is synchronous and returns a ara::core::Result<void> that is empty on success or encapsulates a specific error code.

According to the specification, the operation is designed to be thread-safe and exception safe (exception safe) ([SWS_CRYPT_24115]). If an error occurs during key binding, rollback semantics take effect for all error cases so that the context remains in a consistent state:

• CryptoErrc::kIncompatibleObject: The passed key is incompatible with the signature verification context ([SWS_CRYPT_24115]).
• CryptoErrc::kUsageViolation: The key's permissions do not permit signature verification (absence of the usage flag for signature verification) ([SWS_CRYPT_24115]).
• ara::crypto::CryptoErrc::kUnsupported: The context implementation exclusively supports binding a key via a KeySlot ([SWS_CRYPT_24115]).

In the cryptographic workflow, SetKey constitutes the public counterpart to SignerPrivateCtx::SetKey ([SWS_CRYPT_23515]). If a context does not permit direct key passing via PublicKey::Sptr or keys are managed in secured slots, the overload via KeySlot::Sptr is available alternatively ([SWS_CRYPT_50018]).

use

The method SetKey of class ara::crypto::cryp::VerifierPublicCtx configures the verification context to use a key stored in a passed KeySlot [SWS_CRYPT_50018]. The key is retrieved at the time the signature verification is started [SWS_CRYPT_50018].

A smart pointer keySlot of type KeySlot::Sptr containing a public key serves as the parameter [SWS_CRYPT_50018]. The function operates synchronously and returns a ara::core::Result<void> to indicate successful completion or errors [SWS_CRYPT_50018].

Error Handling and Semantics

The operation is specified as noexcept and exception safe [SWS_CRYPT_50018]. If an error occurs, rollback semantics apply [SWS_CRYPT_50018]:

• ara::crypto::CryptoErrc::kIncompatibleObject: The provided KeySlot is incompatible with this context [SWS_CRYPT_50018].
• ara::crypto::CryptoErrc::kUnsupported: The context exclusively supports setting a PublicKey directly [SWS_CRYPT_50018].

Concurrency and Interaction

The method is specified as thread-safe [SWS_CRYPT_50018]. As an alternative to the KeySlot, VerifierPublicCtx provides an overload to set a PublicKey directly [SWS_CRYPT_24115]. A corresponding key configuration via a KeySlot also exists analogously in other contexts such as SignerPrivateCtx [SWS_CRYPT_50036] or MessageAuthnCodeCtx [SWS_CRYPT_50026].

use

The synchronous method Start() of interface ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_50019]) initializes the context for a new cryptographic signature verification in streaming operation. The function takes no input parameters, is declared as noexcept, and returns a ara::core::Result<void>, which is empty in case of success.

Error Handling and Rollback

If an error occurs during execution, rollback semantics apply ([SWS_CRYPT_50019]), leaving the context in a consistent state. Possible error causes are:

• UninitializedContext: No cryptographic key was previously assigned to the context.
• ara::crypto::CryptoErrc::kUsageViolation: The assigned key is not authorized for signature verification (kAllowSig Verification).
• ara::crypto::CryptoErrc::kEmptyKeySlot: A KeySlot configured for verification is currently empty.
• ara::crypto::CryptoErrc::kUnsupported: The context does not support streaming or the procedure strictly requires a context value.
• ara::crypto::CryptoErrc::kBusyResource: A resource required for the operation is currently busy.

Concurrency and Interaction

Although the specification designates the method as thread-safe ([SWS_CRYPT_50019]), a concurrent call on the same context instance during an ongoing verification would likely reset the existing operation or fail due to busy resources. Question Q-af5e08ff9d905a29 (open)

After successful initialization, the message parts are passed sequentially via Update() ([SWS_CRYPT_50021]). An ongoing streaming operation can be aborted prematurely if necessary using Cancel() ([SWS_CRYPT_50023]). If the algorithm strictly requires a context value, the overloaded function Start(ReadOnlyMemRegion context) ([SWS_CRYPT_50020]) must be called instead.

use

The function Start initializes a verification context of the class ara::crypto::cryp::VerifierPublicCtx for a new signature check according to [SWS_CRYPT_50020]. As an input parameter, it accepts context of type ReadOnlyMemRegion, which provides an application-specific context value. The overload [SWS_CRYPT_50019] exists as an alternative without context data. The return value is ara::core::Result<void>; Interpretation: Since neither callbacks nor future objects are defined, the call is likely handled purely synchronously. Question Q-4e10cdb1a4343a3a (open)

Error handling

In the event of an error, the function returns a ara::core::Result with a matching error code from ara::crypto::CryptoErrc, with rollback semantics being specified [SWS_CRYPT_50020]:

• kUninitializedContext: The context has not yet been initialized by assigning a key.
• kEmptyKeySlot: A configured KeySlot is currently empty.
• kUsageViolation: The permitted usage of the assigned key does not include kAllowSigVerification.
• kInvalidInputSize: The buffer size of the passed context value is invalid for the algorithm.
• kUnsupported: The context does not support streaming, or the algorithm does not support setting a context value.
• kBusyResource: A required resource is busy.

Concurrency and Limitations

According to [SWS_CRYPT_50020], the method is classified as thread-safe as well as exception-safe. It does not throw any exceptions (noexcept).

Interaction

After successful execution of Start, the input message can be transmitted step by step via repeated calls to Update [SWS_CRYPT_50021]. An ongoing streaming process that was initiated by Start can be aborted prematurely via Cancel if necessary [SWS_CRYPT_50023].

use

The method Update() serves to update the signature verification context step by step with a further part of the input message [SWS_CRYPT_50021]. A memory area data of type ReadOnlyMemRegion is passed as a parameter. The function returns a ara::core::Result<void>; Interpretation: Due to this return type, processing is likely performed synchronously. Question Q-f98391030b3b4684 (open)

Error handling

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

• ara::crypto::CryptoErrc::kProcessingNotStarted: The signature verification was not previously initiated by calling the method Start() [SWS_CRYPT_50021].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the data provided in data is not supported [SWS_CRYPT_50021].

Concurrency and Interaction

The operation is classified in the specification as thread-safe and exception safe [SWS_CRYPT_50021]. Before the call, initialization via Start() must have taken place [SWS_CRYPT_50021]. To prevent kInvalidInputSize from occurring, the maximum permitted buffer size for individual calls can be queried via the method GetMaximumChunkSize() of the same context [SWS_CRYPT_50025]. Update() in SignerPrivateCtx represents the complementary counterpart to message-wise signature generation [SWS_CRYPT_50039].

use

The Verify method of context ara::crypto::cryp::VerifierPublicCtx serves to verify the signature of a provided message in a single call [SWS_CRYPT_24112]. The message buffer message, the signature signature, and the format signatureFormat are passed as parameters [SWS_CRYPT_24112]. Upon successful verification, the return value ara::core::Result<bool> contains true, upon mismatch false, or an error code [SWS_CRYPT_24112]. Interpretation: Due to the synchronous result type, the verification process likely executes blocking in the calling thread. Question Q-671054c6e2b581c6 (open)

Error Handling and Concurrency

The function is specified as exception safe and thread-safe [SWS_CRYPT_24112]. In case of an error, rollback semantics apply to the error codes [SWS_CRYPT_24112]. Possible error causes include:

• UninitializedContext, if the context was not initialized with a key [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kEmptyKeySlot in case of an empty key slot, or kUsageViolation if the key lacks the kAllowSig Verification right [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kInvalidInputSize in case of an invalid buffer size [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kUnsupportedFormat or kInvalidArgument in case of an incorrect or incompatible signature format [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kBusyResource, if required resources are busy [SWS_CRYPT_24112].

Interaction

The maximum buffer size for individual calls can be queried via GetMaximumChunkSize() [SWS_CRYPT_50025]. If the algorithm strictly requires a context value, ara::crypto::CryptoErrc::kUnsupported is returned [SWS_CRYPT_24112]; in this case, the overload with the additional context parameter must be chosen [SWS_CRYPT_50024]. By contrast, ara::crypto::cryp::MessageAuthnCodeCtx::Verify exists for verifications of Message Authentication Codes [SWS_CRYPT_50031].

The synchronous method Verify verifies the digital signature of a passed message taking into account a user-defined context value in a single call ([SWS_CRYPT_50024]). As input parameters, the method expects the buffers message, context, and signature each as ReadOnlyMemRegion as well as the format of the signature via signatureFormat ([SWS_CRYPT_50024]). The return value is a ara::core::Result<bool>: It contains true upon successful verification, false in the case of an invalid signature, or a corresponding error code ([SWS_CRYPT_50024]).

In the event of an error, rollback semantics apply ([SWS_CRYPT_50024]). Specific error codes include, among others:

• UninitializedContext if the verification context has not yet been initialized with a key value ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kInvalidInputSize in case of an invalid buffer size ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupported if the selected signature algorithm does not support specifying a context value ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupportedFormat or ara::crypto::CryptoErrc::kInvalidArgument if the specified signature format is not supported or the signature does not conform to the format ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUsageViolation if the permitted key usage does not include kAllowSigVerification, as well as ara::crypto::CryptoErrc::kEmptyKeySlot and ara::crypto::CryptoErrc::kBusyResource ([SWS_CRYPT_50024]).

The method is declared as const noexcept, is considered exception safe, and is specified as thread-safe ([SWS_CRYPT_50024]). In interaction with the context, the maximum buffer size for individual calls can be determined via GetMaximumChunkSize ([SWS_CRYPT_50025]). For verifications without context, the alternative overload of Verify is available ([SWS_CRYPT_24112]).