10.2. Message digests (Hashes)¶

The single-part hash functions are:

psa_hash_compute() to calculate the hash of a message.
psa_hash_compare() to compare the hash of a message with a reference value.

The psa_hash_operation_t multi-part operation allows messages to be processed in fragments. A multi-part hash operation is used as follows:

Initialize the psa_hash_operation_t object to zero, or by assigning the value of the associated macro PSA_HASH_OPERATION_INIT.
Call psa_hash_setup() to specify the required hash algorithm, call psa_hash_clone() to duplicate the state of active psa_hash_operation_t object, or call psa_hash_resume() to restart a hash operation with the output from a previously suspended hash operation.
Call the psa_hash_update() function on successive chunks of the message.
At the end of the message, call the required finishing function:
- To suspend the hash operation and extract a hash suspend state, call psa_hash_suspend(). The output state can subsequently be used to resume the hash operation.
- To calculate the digest of a message, call psa_hash_finish().
- To verify the digest of a message against a reference value, call psa_hash_verify().

To abort the operation or recover from an error, call psa_hash_abort().

10.2.1. Hash algorithms¶

`PSA_ALG_MD2` (macro)¶

The MD2 message-digest algorithm.

#define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001)

Warning

The MD2 hash is weak and deprecated and is only recommended for use in legacy applications.

MD2 is defined in The MD2 Message-Digest Algorithm [RFC1319].

`PSA_ALG_MD4` (macro)¶

The MD4 message-digest algorithm.

#define PSA_ALG_MD4 ((psa_algorithm_t)0x02000002)

Warning

The MD4 hash is weak and deprecated and is only recommended for use in legacy applications.

MD4 is defined in The MD4 Message-Digest Algorithm [RFC1320].

`PSA_ALG_MD5` (macro)¶

The MD5 message-digest algorithm.

#define PSA_ALG_MD5 ((psa_algorithm_t)0x02000003)

Warning

The MD5 hash is weak and deprecated and is only recommended for use in legacy applications.

MD5 is defined in The MD5 Message-Digest Algorithm [RFC1321].

`PSA_ALG_RIPEMD160` (macro)¶

The RIPEMD-160 message-digest algorithm.

#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x02000004)

RIPEMD-160 is defined in RIPEMD-160: A Strengthened Version of RIPEMD [RIPEMD], and also in ISO/IEC 10118-3:2018 IT Security techniques — Hash-functions — Part 3: Dedicated hash-functions [ISO10118].

`PSA_ALG_SHA_1` (macro)¶

The SHA-1 message-digest algorithm.

#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x02000005)

Warning

The SHA-1 hash is weak and deprecated and is only recommended for use in legacy applications.

SHA-1 is defined in FIPS Publication 180-4: Secure Hash Standard (SHS) [FIPS180-4].

`PSA_ALG_SHA_224` (macro)¶

The SHA-224 message-digest algorithm.

#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x02000008)

SHA-224 is defined in [FIPS180-4].

`PSA_ALG_SHA_256` (macro)¶

The SHA-256 message-digest algorithm.

#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x02000009)

SHA-256 is defined in [FIPS180-4].

`PSA_ALG_SHA_384` (macro)¶

The SHA-384 message-digest algorithm.

#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0200000a)

SHA-384 is defined in [FIPS180-4].

`PSA_ALG_SHA_512` (macro)¶

The SHA-512 message-digest algorithm.

#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0200000b)

SHA-512 is defined in [FIPS180-4].

`PSA_ALG_SHA_512_224` (macro)¶

The SHA-512/224 message-digest algorithm.

#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0200000c)

SHA-512/224 is defined in [FIPS180-4].

`PSA_ALG_SHA_512_256` (macro)¶

The SHA-512/256 message-digest algorithm.

#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0200000d)

SHA-512/256 is defined in [FIPS180-4].

`PSA_ALG_SHA3_224` (macro)¶

The SHA3-224 message-digest algorithm.

#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x02000010)

SHA3-224 is defined in FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [FIPS202].

`PSA_ALG_SHA3_256` (macro)¶

The SHA3-256 message-digest algorithm.

#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x02000011)

SHA3-256 is defined in [FIPS202].

`PSA_ALG_SHA3_384` (macro)¶

The SHA3-384 message-digest algorithm.

#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012)

SHA3-384 is defined in [FIPS202].

`PSA_ALG_SHA3_512` (macro)¶

The SHA3-512 message-digest algorithm.

#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013)

SHA3-512 is defined in [FIPS202].

`PSA_ALG_SHAKE256_512` (macro)¶

The first 512 bits (64 bytes) of the SHAKE256 output.

#define PSA_ALG_SHAKE256_512 ((psa_algorithm_t)0x02000015)

This is the prehashing for Ed448ph (see PSA_ALG_ED448PH).

SHAKE256 is defined in [FIPS202].

Note

For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-512 is recommended. SHA3-512 has the same output size, and a theoretically higher security strength.

`PSA_ALG_SM3` (macro)¶

The SM3 message-digest algorithm.

#define PSA_ALG_SM3 ((psa_algorithm_t)0x02000014)

SM3 is defined in ISO/IEC 10118-3:2018 IT Security techniques — Hash-functions — Part 3: Dedicated hash-functions [ISO10118], and also in GM/T 0004-2012: SM3 cryptographic hash algorithm [CSTC0004].

10.2.2. Single-part hashing functions¶

`psa_hash_compute` (function)¶

Calculate the hash (digest) of a message.

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);

Parameters

alg: The hash algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.
input: Buffer containing the message to hash.
input_length: Size of the input buffer in bytes.
hash: Buffer where the hash is to be written.
hash_size: Size of the hash buffer in bytes. This must be at least PSA_HASH_LENGTH(alg).
hash_length: On success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(alg).

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*hash_length) bytes of hash contain the hash value.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the hash buffer is too small. PSA_HASH_LENGTH() can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not a hash algorithm.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not a hash algorithm.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

Note

To verify the hash of a message against an expected value, use psa_hash_compare() instead.

`psa_hash_compare` (function)¶

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

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);

Parameters

alg: The hash algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.
input: Buffer containing the message to hash.
input_length: Size of the input buffer in bytes.
hash: Buffer containing the expected hash value.
hash_length: Size of the hash buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. The expected hash is identical to the actual hash of the input.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE

The calculated hash of the message does not match the value in hash.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not a hash algorithm.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not a hash algorithm.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

10.2.3. Multi-part hashing operations¶

`psa_hash_operation_t` (typedef)¶

The type of the state object for multi-part hash operations.

typedef /* implementation-defined type */ psa_hash_operation_t;

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

Set the object to all-bits-zero, for example:

psa_hash_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:
```
static psa_hash_operation_t operation;
```
Initialize the object to the initializer PSA_HASH_OPERATION_INIT, for example:
```
psa_hash_operation_t operation = PSA_HASH_OPERATION_INIT;
```
Assign the result of the function psa_hash_operation_init() to the object, for example:
```
psa_hash_operation_t operation;
operation = psa_hash_operation_init();
```

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.

`PSA_HASH_OPERATION_INIT` (macro)¶

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

#define PSA_HASH_OPERATION_INIT /* implementation-defined value */

`psa_hash_operation_init` (function)¶

Return an initial value for a hash operation object.

psa_hash_operation_t psa_hash_operation_init(void);

Returns: psa_hash_operation_t

`psa_hash_setup` (function)¶

Set up a multi-part hash operation.

psa_status_t psa_hash_setup(psa_hash_operation_t * operation,
                            psa_algorithm_t alg);

Parameters

operation: The operation object to set up. It must have been initialized as per the documentation for psa_hash_operation_t and not yet in use.
alg: The hash algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

alg is not a hash algorithm.

PSA_ERROR_NOT_SUPPORTED

alg is not supported or is not a hash algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

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

Allocate a hash operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Call psa_hash_setup() to specify the algorithm.
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.
To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify(). To suspend the hash operation and extract the current state, call psa_hash_suspend().

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

A successful call to psa_hash_finish() or psa_hash_verify() or psa_hash_suspend().
A call to psa_hash_abort().

If psa_hash_setup() returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state.

To abandon an active operation, or reset an operation in an error state, call psa_hash_abort().

See Multi-part operations.

`psa_hash_update` (function)¶

Add a message fragment to a multi-part hash operation.

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

Parameters

operation: Active hash operation.
input: Buffer containing the message fragment to hash.
input_length: Size of the input buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

The total input for the operation is too large for the hash algorithm.

PSA_ERROR_NOT_SUPPORTED

The total input for the operation is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The application must call psa_hash_setup() or psa_hash_resume() 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().

`psa_hash_finish` (function)¶

Finish the calculation of the hash of a message.

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

Parameters

operation: Active hash operation.
hash: Buffer where the hash is to be written.
hash_size: Size of the hash buffer in bytes. This must be at least PSA_HASH_LENGTH(alg) where alg is the algorithm that the operation performs.
hash_length: On 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 the operation performs.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*hash_length) bytes of hash contain the hash value.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the hash buffer is too small. PSA_HASH_LENGTH() can be used to determine a sufficient buffer size.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The application must call psa_hash_setup() or psa_hash_resume() 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

It is not recommended to use this function when a specific value is expected for the hash. Call psa_hash_verify() instead with the expected hash value.

Comparing integrity or authenticity data such as hash values with a function such as memcmp() is risky because the time taken by the comparison might leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.

`psa_hash_verify` (function)¶

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

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

Parameters

operation: Active hash operation.
hash: Buffer containing the expected hash value.
hash_length: Size of the hash buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. The expected hash is identical to the actual hash of the message.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE

The calculated hash of the message does not match the value in hash.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

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 must make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.

`psa_hash_abort` (function)¶

Abort a hash operation.

psa_status_t psa_hash_abort(psa_hash_operation_t * operation);

Parameters

operation: Initialized hash operation.

Returns: psa_status_t

PSA_SUCCESS: Success. The operation object can now be discarded or reused.
PSA_ERROR_BAD_STATE: The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED

Description

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

This function can be called 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.

`psa_hash_suspend` (function)¶

Halt the hash operation and extract the intermediate state of the hash computation.

psa_status_t psa_hash_suspend(psa_hash_operation_t * operation,
                              uint8_t * hash_state,
                              size_t hash_state_size,
                              size_t * hash_state_length);

Parameters

operation

Active hash operation.

hash_state

Buffer where the hash suspend state is to be written.

hash_state_size

Size of the hash_state buffer in bytes. This must be appropriate for the selected algorithm:

A sufficient output size is PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) where alg is the algorithm that was used to set up the operation.
PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported hash algorithm.

hash_state_length

On success, the number of bytes that make up the hash suspend state.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*hash_state_length) bytes of hash_state contain the intermediate hash state.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the hash_state buffer is too small. PSA_HASH_SUSPEND_OUTPUT_SIZE() or PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_NOT_SUPPORTED

The hash algorithm being computed does not support suspend and resume.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The application must call psa_hash_setup() or psa_hash_resume() before calling this function. This function extracts an intermediate state of the hash computation of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().

This function can be used to halt a hash operation, and then resume the hash operation at a later time, or in another application, by transferring the extracted hash suspend state to a call to psa_hash_resume().

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().

Hash suspend and resume is not defined for the SHA3 family of hash algorithms. Hash suspend state defines the format of the output from psa_hash_suspend().

Warning

Applications must not use any of the hash suspend state as if it was a hash output. Instead, the suspend state must only be used to resume a hash operation, and psa_hash_finish() or psa_hash_verify() can then calculate or verify the final hash value.

Usage

The sequence of operations to suspend and resume a hash operation is as follows:

Compute the first part of the hash.
1. Allocate an operation object and initialize it as described in the documentation for psa_hash_operation_t.
2. Call psa_hash_setup() to specify the algorithm.
3. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time.
4. Call psa_hash_suspend() to extract the hash suspend state into a buffer.
Pass the hash state buffer to the application which will resume the operation.
Compute the rest of the hash.
1. Allocate an operation object and initialize it as described in the documentation for psa_hash_operation_t.
2. Call psa_hash_resume() with the extracted hash state.
3. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time.
4. 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() or psa_hash_resume(), the operation will need to be reset by a call to psa_hash_abort(). The application can call psa_hash_abort() at any time after the operation has been initialized.

`psa_hash_resume` (function)¶

Set up a multi-part hash operation using the hash suspend state from a previously suspended hash operation.

psa_status_t psa_hash_resume(psa_hash_operation_t * operation,
                             const uint8_t * hash_state,
                             size_t hash_state_length);

Parameters

operation: The operation object to set up. It must have been initialized as per the documentation for psa_hash_operation_t and not yet in use.
hash_state: A buffer containing the suspended hash state which is to be resumed. This must be in the format output by psa_hash_suspend(), which is described in Hash suspend state format.
hash_state_length: Length of hash_state in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

hash_state does not correspond to a valid hash suspend state. See Hash suspend state format for the definition.

PSA_ERROR_NOT_SUPPORTED

The provided hash suspend state is for an algorithm that is not supported.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

See psa_hash_suspend() for an example of how to use this function to suspend and resume a hash operation.

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

A successful call to psa_hash_finish(), psa_hash_verify() or psa_hash_suspend().
A call to psa_hash_abort().

`psa_hash_clone` (function)¶

Clone a hash operation.

psa_status_t psa_hash_clone(const psa_hash_operation_t * source_operation,
                            psa_hash_operation_t * target_operation);

Parameters

source_operation: The active hash operation to clone.
target_operation: The operation object to set up. It must be initialized but not active.

Returns: psa_status_t

PSA_SUCCESS

Success. target_operation is ready to continue the same hash operation as source_operation.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The source_operation state is not valid: it must be active.
The target_operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

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.

10.2.4. Support macros¶

`PSA_HASH_LENGTH` (macro)¶

The size of the output of psa_hash_compute() and psa_hash_finish(), in bytes.

#define PSA_HASH_LENGTH(alg) /* implementation-defined value */

Parameters

alg: A hash algorithm or an HMAC algorithm: a value of type psa_algorithm_t such that (PSA_ALG_IS_HASH(alg) || PSA_ALG_IS_HMAC(alg)) is true.

Returns

The hash length for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.

Description

This is also the hash length that psa_hash_compare() and psa_hash_verify() expect.

`PSA_HASH_MAX_SIZE` (macro)¶

Maximum size of a hash.

#define PSA_HASH_MAX_SIZE /* implementation-defined value */

It is recommended that this value is the maximum size of a hash supported by the implementation, in bytes. The value must not be smaller than this maximum.

`PSA_HASH_SUSPEND_OUTPUT_SIZE` (macro)¶

A sufficient hash suspend state buffer size for psa_hash_suspend(), in bytes.

#define PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) /* specification-defined value */

Parameters

alg: A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.

Returns

A sufficient output size for the algorithm. If the hash algorithm is not recognized, or is not supported by psa_hash_suspend(), return 0. An implementation can return either 0 or a correct size for a hash algorithm that it recognizes, but does not support.

For a supported hash algorithm alg, the following expression is true:

PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) == PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH +
                                     PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) +
                                     PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) +
                                     PSA_HASH_BLOCK_LENGTH(alg) - 1

Description

If the size of the hash state buffer is at least this large, it is guaranteed that psa_hash_suspend() will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.

`PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE` (macro)¶

A sufficient hash suspend state buffer size for psa_hash_suspend(), for any supported hash algorithms.

#define PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE /* implementation-defined value */

If the size of the hash state buffer is at least this large, it is guaranteed that psa_hash_suspend() will not fail due to an insufficient buffer size.

`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` (macro)¶

The size of the algorithm field that is part of the output of psa_hash_suspend(), in bytes.

#define PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH ((size_t)4)

Applications can use this value to unpack the hash suspend state that is output by psa_hash_suspend().

`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH` (macro)¶

The size of the input-length field that is part of the output of psa_hash_suspend(), in bytes.

#define PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) \
    /* specification-defined value */

Parameters

alg: A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.

Returns

The size, in bytes, of the input-length field of the hash suspend state for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.

The algorithm-specific values are defined in Hash suspend state field sizes.

Description

Applications can use this value to unpack the hash suspend state that is output by psa_hash_suspend().

`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH` (macro)¶

The size of the hash-state field that is part of the output of psa_hash_suspend(), in bytes.

#define PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) \
    /* specification-defined value */

Parameters

alg: A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.

Returns

The size, in bytes, of the hash-state field of the hash suspend state for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.

The algorithm-specific values are defined in Hash suspend state field sizes.

Description

Applications can use this value to unpack the hash suspend state that is output by psa_hash_suspend().

`PSA_HASH_BLOCK_LENGTH` (macro)¶

The input block size of a hash algorithm, in bytes.

#define PSA_HASH_BLOCK_LENGTH(alg) /* implementation-defined value */

Parameters

alg: A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(alg) is true.

Returns

The block size in bytes for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation can return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.

Description

Hash algorithms process their input data in blocks. Hash operations will retain any partial blocks until they have enough input to fill the block or until the operation is finished.

This affects the output from psa_hash_suspend().

10.2.5. Hash suspend state¶

The hash suspend state is output by psa_hash_suspend() and input to psa_hash_resume().

Note

Hash suspend and resume is not defined for the SM3 algorithm and the SHA3 family of hash algorithms.

Hash suspend state format¶

The hash suspend state has the following format:

hash-suspend-state = algorithm || input-length || hash-state || unprocessed-input

The fields in the hash suspend state are defined as follows:

algorithm

A big-endian 32-bit unsigned integer.

The Crypto API algorithm identifier value.

The byte length of the algorithm field can be evaluated using PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH.

input-length

A big-endian unsigned integer

The content of this field is algorithm-specific:

For MD2, this is the number of bytes in the unprocessed-input.
For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the unprocessed-input bytes.

The size of this field is algorithm-specific:

For MD2: input-length is an 8-bit unsigned integer.
For MD4, MD5, RIPEMD-160, SHA-1, SHA-224, and SHA-256: input-length is a 64-bit unsigned integer.
For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: input-length is a 128-bit unsigned integer.

The length, in bytes, of the input-length field can be calculated using PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) where alg is a hash algorithm. See Hash suspend state field sizes.

hash-state

An array of bytes

Algorithm-specific intermediate hash state:

For MD2: 16 bytes of internal checksum, then 48 bytes of intermediate digest.
For MD4 and MD5: 4x 32-bit integers, in little-endian encoding.
For RIPEMD-160: 5x 32-bit integers, in little-endian encoding.
For SHA-1: 5x 32-bit integers, in big-endian encoding.
For SHA-224 and SHA-256: 8x 32-bit integers, in big-endian encoding.
For SHA-512/224, SHA-512/256, SHA-384, and SHA-512: 8x 64-bit integers, in big-endian encoding.

The length of this field is specific to the algorithm. The length, in bytes, of the hash-state field can be calculated using PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) where alg is a hash algorithm. See Hash suspend state field sizes.

unprocessed-input

0 to (hash-block-size-1) bytes

A partial block of unprocessed input data. This is between zero and hash-block-size-1 bytes of data, the length can be calculated by:

length(unprocessed-input) = input-length % hash-block-size.

The hash-block-size is specific to the algorithm. The size of a hash block can be calculated using PSA_HASH_BLOCK_LENGTH(alg) where alg is a hash algorithm. See Hash suspend state field sizes.

Hash suspend state field sizes¶

The following table defines the algorithm-specific field lengths for the hash suspend state returned by psa_hash_suspend(). All of the field lengths are in bytes. To compute the field lengths for algorithm alg, use the following expressions:

PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH returns the length of the algorithm field.
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) returns the length of the input-length field.
PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) returns the length of the hash-state field.
PSA_HASH_BLOCK_LENGTH(alg)-1 is the maximum length of the unprocessed-bytes field.
PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) returns the maximum size of the hash suspend state.

Hash algorithm	input-length size (bytes)	hash-state length (bytes)	unprocessed-bytes length (bytes)
`PSA_ALG_MD2`	1	64	0 – 15
`PSA_ALG_MD4`	8	16	0 – 63
`PSA_ALG_MD5`	8	16	0 – 63
`PSA_ALG_RIPEMD160`	8	20	0 – 63
`PSA_ALG_SHA_1`	8	20	0 – 63
`PSA_ALG_SHA_224`	8	32	0 – 63
`PSA_ALG_SHA_256`	8	32	0 – 63
`PSA_ALG_SHA_512_224`	16	64	0 – 127
`PSA_ALG_SHA_512_256`	16	64	0 – 127
`PSA_ALG_SHA_384`	16	64	0 – 127
`PSA_ALG_SHA_512`	16	64	0 – 127

10.2. Message digests (Hashes)¶

10.2.1. Hash algorithms¶

PSA_ALG_MD2 (macro)¶

PSA_ALG_MD4 (macro)¶

PSA_ALG_MD5 (macro)¶

PSA_ALG_RIPEMD160 (macro)¶

PSA_ALG_SHA_1 (macro)¶

PSA_ALG_SHA_224 (macro)¶

PSA_ALG_SHA_256 (macro)¶

PSA_ALG_SHA_384 (macro)¶

PSA_ALG_SHA_512 (macro)¶

PSA_ALG_SHA_512_224 (macro)¶

PSA_ALG_SHA_512_256 (macro)¶

PSA_ALG_SHA3_224 (macro)¶

PSA_ALG_SHA3_256 (macro)¶

PSA_ALG_SHA3_384 (macro)¶

PSA_ALG_SHA3_512 (macro)¶

PSA_ALG_SHAKE256_512 (macro)¶

PSA_ALG_SM3 (macro)¶

10.2.2. Single-part hashing functions¶

psa_hash_compute (function)¶

psa_hash_compare (function)¶

10.2.3. Multi-part hashing operations¶

psa_hash_operation_t (typedef)¶

PSA_HASH_OPERATION_INIT (macro)¶

psa_hash_operation_init (function)¶

psa_hash_setup (function)¶

psa_hash_update (function)¶

psa_hash_finish (function)¶

psa_hash_verify (function)¶

psa_hash_abort (function)¶

psa_hash_suspend (function)¶

psa_hash_resume (function)¶

psa_hash_clone (function)¶

10.2.4. Support macros¶

PSA_HASH_LENGTH (macro)¶

PSA_HASH_MAX_SIZE (macro)¶

PSA_HASH_SUSPEND_OUTPUT_SIZE (macro)¶

PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE (macro)¶

PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH (macro)¶

PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH (macro)¶

PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH (macro)¶

PSA_HASH_BLOCK_LENGTH (macro)¶

10.2.5. Hash suspend state¶

Hash suspend state format¶

Hash suspend state field sizes¶

`PSA_ALG_MD2` (macro)¶

`PSA_ALG_MD4` (macro)¶

`PSA_ALG_MD5` (macro)¶

`PSA_ALG_RIPEMD160` (macro)¶

`PSA_ALG_SHA_1` (macro)¶

`PSA_ALG_SHA_224` (macro)¶

`PSA_ALG_SHA_256` (macro)¶

`PSA_ALG_SHA_384` (macro)¶

`PSA_ALG_SHA_512` (macro)¶

`PSA_ALG_SHA_512_224` (macro)¶

`PSA_ALG_SHA_512_256` (macro)¶

`PSA_ALG_SHA3_224` (macro)¶

`PSA_ALG_SHA3_256` (macro)¶

`PSA_ALG_SHA3_384` (macro)¶

`PSA_ALG_SHA3_512` (macro)¶

`PSA_ALG_SHAKE256_512` (macro)¶

`PSA_ALG_SM3` (macro)¶

`psa_hash_compute` (function)¶

`psa_hash_compare` (function)¶

`psa_hash_operation_t` (typedef)¶

`PSA_HASH_OPERATION_INIT` (macro)¶

`psa_hash_operation_init` (function)¶

`psa_hash_setup` (function)¶

`psa_hash_update` (function)¶

`psa_hash_finish` (function)¶

`psa_hash_verify` (function)¶

`psa_hash_abort` (function)¶

`psa_hash_suspend` (function)¶

`psa_hash_resume` (function)¶

`psa_hash_clone` (function)¶

`PSA_HASH_LENGTH` (macro)¶

`PSA_HASH_MAX_SIZE` (macro)¶

`PSA_HASH_SUSPEND_OUTPUT_SIZE` (macro)¶

`PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE` (macro)¶

`PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH` (macro)¶

`PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH` (macro)¶

`PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH` (macro)¶

`PSA_HASH_BLOCK_LENGTH` (macro)¶