NCBI C++ ToolKit
Macros | Typedefs | Functions
Message digests

Macros

#define PSA_HASH_OPERATION_INIT   { 0, { 0 } }
 This macro returns a suitable initializer for a hash operation object of type psa_hash_operation_t. More...
 

Typedefs

typedef struct psa_hash_operation_s psa_hash_operation_t
 The type of the state data structure for multipart hash operations. More...
 

Functions

psa_status_t psa_hash_compute (psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)
 Calculate the hash (digest) of a message. More...
 
psa_status_t psa_hash_compare (psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *hash, size_t hash_length)
 Calculate the hash (digest) of a message and compare it with a reference value. More...
 
static psa_hash_operation_t psa_hash_operation_init (void)
 Return an initial value for a hash operation object. More...
 
psa_status_t psa_hash_setup (psa_hash_operation_t *operation, psa_algorithm_t alg)
 Set up a multipart hash operation. More...
 
psa_status_t psa_hash_update (psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
 Add a message fragment to a multipart hash operation. More...
 
psa_status_t psa_hash_finish (psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
 Finish the calculation of the hash of a message. More...
 
psa_status_t psa_hash_verify (psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)
 Finish the calculation of the hash of a message and compare it with an expected value. More...
 
psa_status_t psa_hash_abort (psa_hash_operation_t *operation)
 Abort a hash operation. More...
 
psa_status_t psa_hash_clone (const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
 Clone a hash operation. More...
 

Detailed Description

Macro Definition Documentation

◆ PSA_HASH_OPERATION_INIT

#define PSA_HASH_OPERATION_INIT   { 0, { 0 } }

This macro returns a suitable initializer for a hash operation object of type psa_hash_operation_t.

Definition at line 94 of file crypto_struct.h.

Typedef Documentation

◆ psa_hash_operation_t

The type of the state data structure for multipart hash operations.

Before calling any function on a hash operation object, the application must initialize it by any of the following means:

This is an implementation-defined struct. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.

Definition at line 902 of file crypto.h.

Function Documentation

◆ psa_hash_abort()

psa_status_t psa_hash_abort ( psa_hash_operation_t operation)

Abort a hash operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_hash_setup() again.

You may call this function any time after the operation object has been initialized by one of the methods described in psa_hash_operation_t.

In particular, calling psa_hash_abort() after the operation has been terminated by a call to psa_hash_abort(), psa_hash_finish() or psa_hash_verify() is safe and has no effect.

Parameters
[in,out]operationInitialized hash operation.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Referenced by mbedtls_ssl_handshake_free_ncbicxx_2_28_3(), mbedtls_ssl_reset_checksum_ncbicxx_2_28_3(), psa_hash_clone_ncbicxx_2_28_3(), psa_hash_finish_ncbicxx_2_28_3(), psa_hash_setup_ncbicxx_2_28_3(), psa_hash_update_ncbicxx_2_28_3(), and psa_hash_verify_ncbicxx_2_28_3().

◆ psa_hash_clone()

psa_status_t psa_hash_clone ( const psa_hash_operation_t source_operation,
psa_hash_operation_t target_operation 
)

Clone a hash operation.

This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling psa_hash_setup() on target_operation with the same algorithm that source_operation was set up for, then psa_hash_update() on target_operation with the same input that that was passed to source_operation. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.

Parameters
[in]source_operationThe active hash operation to clone.
[in,out]target_operationThe operation object to set up. It must be initialized but not active.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_BAD_STATEThe source_operation state is not valid (it must be active), or the target_operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Referenced by ssl_calc_finished_tls_sha256(), ssl_calc_finished_tls_sha384(), ssl_calc_verify_tls_sha256(), and ssl_calc_verify_tls_sha384().

◆ psa_hash_compare()

psa_status_t psa_hash_compare ( psa_algorithm_t  alg,
const uint8_t input,
size_t  input_length,
const uint8_t hash,
size_t  hash_length 
)

Calculate the hash (digest) of a message and compare it with a reference value.

Parameters
algThe hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).
[in]inputBuffer containing the message to hash.
input_lengthSize of the input buffer in bytes.
[out]hashBuffer containing the expected hash value.
hash_lengthSize of the hash buffer in bytes.
Return values
PSA_SUCCESSThe expected hash is identical to the actual hash of the input.
PSA_ERROR_INVALID_SIGNATUREThe hash of the message was calculated successfully, but it differs from the expected hash.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a hash algorithm.
PSA_ERROR_INVALID_ARGUMENTinput_length or hash_length do not match the hash size for alg
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_hash_compute()

psa_status_t psa_hash_compute ( psa_algorithm_t  alg,
const uint8_t input,
size_t  input_length,
uint8_t hash,
size_t  hash_size,
size_t *  hash_length 
)

Calculate the hash (digest) of a message.

Note
To verify the hash of a message against an expected value, use psa_hash_compare() instead.
Parameters
algThe hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).
[in]inputBuffer containing the message to hash.
input_lengthSize of the input buffer in bytes.
[out]hashBuffer where the hash is to be written.
hash_sizeSize of the hash buffer in bytes.
[out]hash_lengthOn success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(alg).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a hash algorithm.
PSA_ERROR_INVALID_ARGUMENT\emptydescription
PSA_ERROR_BUFFER_TOO_SMALLhash_size is too small
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_hash_finish()

psa_status_t psa_hash_finish ( psa_hash_operation_t operation,
uint8_t hash,
size_t  hash_size,
size_t *  hash_length 
)

Finish the calculation of the hash of a message.

The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Warning
Applications should not call this function if they expect a specific value for the hash. Call psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as memcmp is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.
Parameters
[in,out]operationActive hash operation.
[out]hashBuffer where the hash is to be written.
hash_sizeSize of the hash buffer in bytes.
[out]hash_lengthOn success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(alg) where alg is the hash algorithm that is calculated.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BUFFER_TOO_SMALLThe size of the hash buffer is too small. You can determine a sufficient buffer size by calling PSA_HASH_LENGTH(alg) where alg is the hash algorithm that is calculated.
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Referenced by psa_hash_verify_ncbicxx_2_28_3(), ssl_calc_finished_tls_sha256(), ssl_calc_finished_tls_sha384(), ssl_calc_verify_tls_sha256(), ssl_calc_verify_tls_sha384(), x509_crt_check_signature(), and x509write_csr_der_internal().

◆ psa_hash_operation_init()

static psa_hash_operation_t psa_hash_operation_init ( void  )
static

◆ psa_hash_setup()

psa_status_t psa_hash_setup ( psa_hash_operation_t operation,
psa_algorithm_t  alg 
)

Set up a multipart hash operation.

The sequence of operations to calculate a hash (message digest) is as follows:

  1. Allocate an operation object which will be passed to all the functions listed here.
  2. Initialize the operation object with one of the methods described in the documentation for psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
  3. Call psa_hash_setup() to specify the algorithm.
  4. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order.
  5. To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify().

If an error occurs at any step after a call to psa_hash_setup(), the operation will need to be reset by a call to psa_hash_abort(). The application may call psa_hash_abort() at any time after the operation has been initialized.

After a successful call to psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for psa_hash_operation_t and not yet in use.
algThe hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_NOT_SUPPORTEDalg is not a supported hash algorithm.
PSA_ERROR_INVALID_ARGUMENTalg is not a hash algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be inactive), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Referenced by mbedtls_ssl_reset_checksum_ncbicxx_2_28_3(), ssl_handshake_params_init(), x509_crt_check_signature(), and x509write_csr_der_internal().

◆ psa_hash_update()

psa_status_t psa_hash_update ( psa_hash_operation_t operation,
const uint8_t input,
size_t  input_length 
)

Add a message fragment to a multipart hash operation.

The application must call psa_hash_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Parameters
[in,out]operationActive hash operation.
[in]inputBuffer containing the message fragment to hash.
input_lengthSize of the input buffer in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

Referenced by ssl_update_checksum_sha256(), ssl_update_checksum_sha384(), ssl_update_checksum_start(), x509_crt_check_signature(), and x509write_csr_der_internal().

◆ psa_hash_verify()

psa_status_t psa_hash_verify ( psa_hash_operation_t operation,
const uint8_t hash,
size_t  hash_length 
)

Finish the calculation of the hash of a message and compare it with an expected value.

The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Note
Implementations shall make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.
Parameters
[in,out]operationActive hash operation.
[in]hashBuffer containing the expected hash value.
hash_lengthSize of the hash buffer in bytes.
Return values
PSA_SUCCESSThe expected hash is identical to the actual hash of the message.
PSA_ERROR_INVALID_SIGNATUREThe hash of the message was calculated successfully, but it differs from the expected hash.
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_COMMUNICATION_FAILURE\emptydescription
PSA_ERROR_HARDWARE_FAILURE\emptydescription
PSA_ERROR_CORRUPTION_DETECTED\emptydescription
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active), or the library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
Modified on Fri Mar 01 10:08:32 2024 by modify_doxy.py rev. 669887