class ara::crypto::cryp::HashFunctionCtx

The CalculateHashDigest method performs a synchronous one-shot calculation of a cryptographic hash value and writes the result into the provided output buffer [SWS_CRYPT_50060]. The input message data to be processed, the destination buffer digest, and optionally an initialization vector iv are passed as parameters. Upon successful execution, the function returns the actual number of written digest bytes via the result object ara::core::Result<std::size_t> [SWS_CRYPT_50060].

Error handling

If the calculation fails, the interface guarantees rollback semantics [SWS_CRYPT_50060]. The following error codes can be contained in the result:

• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed data or of the initialization vector is not supported [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported: Single-call calculation is not supported by the context, or the passing of the initialization vector does not match the configuration of the context (IV required but missing, or IV passed although not supported) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity: The capacity of the output buffer digest is not sufficient for the calculated digest [SWS_CRYPT_50060].

Concurrency and Interaction

The function is declared as exception-safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_50060]. To avoid errors regarding impermissible input lengths in advance, the maximum buffer size permitted for a single call of the context can be determined via GetMaximumChunkSize [SWS_CRYPT_50062].

use

The method Cancel() serves to purposefully abort an ongoing streaming operation that was previously started via method Start() and has not yet been regularly completed [SWS_CRYPT_50058]. The call is synchronous and parameterless on an instance of ara::crypto::cryp::HashFunctionCtx from header file ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. Upon successful execution, the operation returns an empty ara::core::Result<void> [SWS_CRYPT_50058].

Error handling

If a problem occurs during execution, the returned ara::core::Result contains a corresponding error value [SWS_CRYPT_50058]. If processing was not initiated by Start() prior to calling Cancel(), the abort fails and returns the specific error code ara::crypto::CryptoErrc::kProcessingNotStarted with rollback semantics [SWS_CRYPT_50058].

Concurrency and Limitations

The interface is defined as thread-safe and exception safe and declared with noexcept [SWS_CRYPT_50058]. As an essential functional precondition, data processing must be in an active state created by a preceding Start() call [SWS_CRYPT_50058].

Interaction

The pattern implemented by Cancel() is standardized across various streaming contexts of the crypto stack. Exactly matching semantics and error signaling are also exhibited by the contexts VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077], and EncryptorPublicCtx [SWS_CRYPT_50089].

The method Compare of class ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) synchronously compares the size and content of a previously calculated hash digest with an expected reference value. The nominal value is passed via the parameter expected of type ReadOnlyMemRegion. In case of success, the function returns a ara::core::Result<bool> that contains true if and only if the expected byte sequence is identical to the calculated digest.

A precondition for the call is that the digest calculation was previously completed with the method Finish(). If this is not the case, the call fails and returns the error ara::crypto::CryptoErrc::kProcessingNotFinished with rollback semantics ([SWS_CRYPT_50154]). Interpretation: A deviating length or unequal content of expected presumably does not lead to an error code, but to a regular false in the result object. Question Q-fdd0ecaec22f6985 (open)

Regarding concurrency, the method is specified as thread-safe and exception safe ([SWS_CRYPT_50154]). Due to the declaration as noexcept, it does not throw any C++ exceptions.

The same verification pattern is used in related crypto contexts: For Message Authentication Codes, ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) compares the size and content of the calculated MAC value, while CompareSubspan ([SWS_CRYPT_50028]) verifies the most significant bits. Both methods likewise require a previously finished calculation.

The [SWS_CRYPT_50064] method of class ara::crypto::cryp::HashFunctionCtx synchronously writes the current state of a hash context into the passed output buffer contextState of type ReadWriteMem Region. This enables applications to suspend an ongoing cryptographic hash operation and resume it at a later point in time. Upon successful execution, the call returns an empty ara::core::Result<void>.

Interaction and Buffer Dimensioning

To prevent memory errors, the strictly required buffer size in bytes should be queried beforehand via the [SWS_CRYPT_50063] function. The exported state can later be re-imported into a hash context using [SWS_CRYPT_50065]. A prerequisite for this is that the target context has the same AlgorithmId and is provided by the same Crypto Provider as the source context. During import, any existing computational state is completely overwritten.

Error handling

If the operation fails, an error is returned in ara::core::Result. The following error codes from ara::crypto::CryptoErrc are specified:

• ara::crypto::CryptoErrc::kUnsupported: The concrete context does not support exporting or importing states.
• ara::crypto::CryptoErrc::kInsufficientCapacity: The capacity of the passed buffer contextState is not sufficient to hold the state.

Rollback semantics are defined for both error cases, so that the state of the object remains unchanged.

Concurrency and Execution Safety

The interface is declared as const and noexcept. According to the specification, the call is both thread-safe and exception-safe.

use

The synchronous method Finish() finalizes the calculation of a hash value in ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_21115]. The parameterless call returns a ara::core::Result<void> that signals successful completion or encapsulates an error [SWS_CRYPT_21115]. The interface is declared as noexcept and specified as exception safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_21115].

Error Handling and Concurrency

If the hash calculation was not successfully started prior to the call, the method fails with the error ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_21115]. A rollback semantics is defined for this error case, so callers must strictly ensure a properly started context prior to finalization [SWS_CRYPT_21115].

Interaction

After a successful call to Finish(), the calculated hash digest is typically transferred into a provided buffer using GetDigest() [SWS_CRYPT_21116], [SWS_CRYPT_50059]. GetIntermediateDigest() serves for distinction: this function provides the same hash value as the sequence of Finish() and GetDigest(), but allows further data to be passed afterward [SWS_CRYPT_50059]. Interpretation: After the call of Finish(), the calculation is likely to be completed finally and the context will no longer accept additional data. Question Q-f4daf29364f45fd5 (open) Permissible buffer sizes for processing steps in the context can be queried via GetMaximumChunkSize() [SWS_CRYPT_50062].

The ImportContextState method of class ara::crypto::cryp::HashFunctionCtx (defined in ara/crypto/cryp/hash_function_ctx.h) serves to restore the internal state of a hash context from a passed buffer, thereby continuing a previously interrupted hash operation [SWS_CRYPT_50065]. Any ongoing calculation state of the current context is completely replaced by the imported state [SWS_CRYPT_50065].

Call and Preconditions

The synchronous call takes place via the signature ImportContextState(ReadOnlyMem Region contextState) noexcept and returns a ara::core::Result<void> [SWS_CRYPT_50065]. The following mandatory prerequisites apply to the parameter contextState:

• The data buffer must have been previously exported from an instance of HashFunctionCtx using the ExportContextState() method [SWS_CRYPT_50065].
• The source context must have had the same AlgorithmId and must have been provided by the same Crypto Provider as the target context [SWS_CRYPT_50065].

Error Handling and Concurrency

In case of an error, an error code with rollback semantics is returned, so that the existing state of the context remains unchanged in case of failure [SWS_CRYPT_50065]:

• ara::crypto::CryptoErrc::kInvalidArgument: The argument contextState contains invalid data [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported: The specific context does not support exporting and importing context states [SWS_CRYPT_50065].

The operation is specified as thread-safe and exception safe [SWS_CRYPT_50065].

The method Start() of interface ara::crypto::cryp::HashFunctionCtx initializes the context for the incremental calculation of a hash value without an initialization vector (IV) [SWS_CRYPT_50152]. A repeated call aborts any hash calculation that may already be in progress and sets up the context for a new calculation [SWS_CRYPT_50152].

The function is synchronous, takes no parameters, and returns an ara::core::Result<void> [SWS_CRYPT_50152]. If an error occurs during initialization, rollback semantics apply with the following specific error codes [SWS_CRYPT_50152]:

• ara::crypto::CryptoErrc::kUnsupported: The hash function used strictly expects an initialization vector [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource: An internal resource strictly required for the operation is occupied [SWS_CRYPT_50152].

With respect to concurrency, the method is specified as thread-safe as well as exception safe and declared as noexcept [SWS_CRYPT_50152]. After successful initialization, message parts can be fed sequentially via the method Update() of the context [SWS_CRYPT_21113]. Because the call aborts ongoing calculations, the function should in practice also serve as a reset mechanism before a restart. Question Q-9c369489a6c6e8cb (open)

use

The function Start of interface ara::crypto::cryp::HashFunctionCtx initializes the context for calculating a hash digest using an initialization vector (IV) [SWS_CRYPT_50153]. The initialization vector iv is passed as a parameter via a ReadOnlyMemRegion [SWS_CRYPT_50153]. The synchronous call returns an ara::core::Result<void>, which contains no return value in the success case [SWS_CRYPT_50153]. A call also aborts any hash calculation that may already be in progress on this context [SWS_CRYPT_50153].

Error handling

If an error occurs during initialization, a corresponding error code is returned, with rollback semantics being guaranteed for all error cases [SWS_CRYPT_50153]:

• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the provided initialization vector is not supported [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported: The underlying hash function does not use an initialization vector [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource: A resource required for initialization is occupied [SWS_CRYPT_50153].

Concurrency and Interaction

The interface is declared as noexcept and specified as thread-safe (thread-safe) and exception-safe (exception safe) [SWS_CRYPT_50153]. In the typical sequence, the call forms the precondition for the subsequent incremental processing of the input message via method Update [SWS_CRYPT_21113].

The synchronous method Update serves in [SWS_CRYPT_21113] for the incremental update of an ongoing hash calculation context (ara::crypto::cryp::HashFunctionCtx). Via the parameter data (ReadOnlyMemRegion), part of the input message to be processed is passed. The function returns a ara::core::Result<void> that is empty in case of success or encapsulates a corresponding error code.

Regarding error behavior, the method provides rollback semantics for two specific error states:

• ara::crypto::CryptoErrc::kProcessingNotStarted: The calculation was not previously initiated by a call to the method Start() [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize: The size of the passed data is not supported by the context [SWS_CRYPT_21113].

Clear sequencing and size conditions apply to the call context: Before data is passed, the hashing process must have been initialized [SWS_CRYPT_21113]. To avoid kInvalidInputSize, the maximum permissible block size for a single Update call can be determined beforehand via GetMaximumChunkSize [SWS_CRYPT_50062]. According to the specification, the function is declared as exception safe (exception safe) and thread-safe (thread-safe) [SWS_CRYPT_21113].

In interaction with other interfaces, an overload exists within HashFunctionCtx for passing key objects via Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. After feeding all data blocks, finalization of the checksum is presumably likely to take place via Finish() [SWS_CRYPT_50062]. Question Q-dcac20f353ca55f4 (open)

The synchronous method Update in [SWS_CRYPT_50057] serves to incrementally extend the context of a hash value calculation in ara::crypto::cryp::HashFunctionCtx with a new message section in the form of a key object. A smart pointer to the key object (CryptoObject::Sptr key) is passed as a parameter. The call returns a ara::core::Result<void>, which is empty upon successful processing or encapsulates a corresponding error code in case of an error [SWS_CRYPT_50057].

The sequencing requirement is that the calculation must strictly have been initiated previously by calling Start(); otherwise, the error ProcessingNotStarted is reported [SWS_CRYPT_50057]. Other specific error cases include (each with rollback semantics) [SWS_CRYPT_50057]:

• ara::crypto::CryptoErrc::kUnsupported, if the hash context generally does not support hashing keys,
• ara::crypto::CryptoErrc::kIncompatibleObject, if the passed key object is not compatible with the context,
• ara::crypto::CryptoErrc::kUsageViolation, provided that the permitted usage of the key does not include kAllowHash Calculation,
• ara::crypto::CryptoErrc::kInvalidInputSize, if the data size of the passed key is not supported.

The method is declared thread-safe and exception safe (noexcept) [SWS_CRYPT_50057]. In interaction with other interfaces of the module, the maximum permitted buffer size for individual Update calls can be determined via GetMaximumChunkSize() [SWS_CRYPT_50062]. For regular message parts without a key object, the overload Update(ReadOnlyMemRegion data) exists in parallel in HashFunctionCtx [SWS_CRYPT_21113].