10.2. Message digests (Hashes)
The singlepart 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
multipart operation allows messages to be processed in fragments. A multipart hash operation is used as follows:
 Initialize the
psa_hash_operation_t
object to zero, or by assigning the value of the associated macroPSA_HASH_OPERATION_INIT
.  Call
psa_hash_setup()
to specify the required hash algorithm, callpsa_hash_clone()
to duplicate the state of activepsa_hash_operation_t
object, or callpsa_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 suspend the hash operation and extract a hash suspend state, call
To abort the operation or recover from an error, call psa_hash_abort()
.
10.2.1. Hash algorithms
PSA_ALG_MD2
(macro)
The MD2 messagedigest 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 protocols.
MD2 is defined in The MD2 MessageDigest Algorithm [RFC1319].
PSA_ALG_MD4
(macro)
The MD4 messagedigest 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 protocols.
MD4 is defined in The MD4 MessageDigest Algorithm [RFC1320].
PSA_ALG_MD5
(macro)
The MD5 messagedigest 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 protocols.
MD5 is defined in The MD5 MessageDigest Algorithm [RFC1321].
PSA_ALG_RIPEMD160
(macro)
The RIPEMD160 messagedigest algorithm.
#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x02000004)
RIPEMD160 is defined in RIPEMD160: A Strengthened Version of RIPEMD [RIPEMD], and also in ISO/IEC 101183:2018 IT Security techniques — Hashfunctions — Part 3: Dedicated hashfunctions [ISO10118].
PSA_ALG_SHA_1
(macro)
The SHA1 messagedigest algorithm.
#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x02000005)
Warning
The SHA1 hash is weak and deprecated and is only recommended for use in legacy protocols.
SHA1 is defined in FIPS Publication 1804: Secure Hash Standard (SHS) [FIPS1804].
PSA_ALG_SHA_224
(macro)
The SHA224 messagedigest algorithm.
#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x02000008)
SHA224 is defined in [FIPS1804].
PSA_ALG_SHA_256
(macro)
The SHA256 messagedigest algorithm.
#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x02000009)
SHA256 is defined in [FIPS1804].
PSA_ALG_SHA_384
(macro)
The SHA384 messagedigest algorithm.
#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0200000a)
SHA384 is defined in [FIPS1804].
PSA_ALG_SHA_512
(macro)
The SHA512 messagedigest algorithm.
#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0200000b)
SHA512 is defined in [FIPS1804].
PSA_ALG_SHA_512_224
(macro)
The SHA512/224 messagedigest algorithm.
#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0200000c)
SHA512/224 is defined in [FIPS1804].
PSA_ALG_SHA_512_256
(macro)
The SHA512/256 messagedigest algorithm.
#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0200000d)
SHA512/256 is defined in [FIPS1804].
PSA_ALG_SHA3_224
(macro)
The SHA3224 messagedigest algorithm.
#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x02000010)
SHA3224 is defined in FIPS Publication 202: SHA3 Standard: PermutationBased Hash and ExtendableOutput Functions [FIPS202].
PSA_ALG_SHA3_256
(macro)
The SHA3256 messagedigest algorithm.
#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x02000011)
SHA3256 is defined in [FIPS202].
PSA_ALG_SHA3_384
(macro)
The SHA3384 messagedigest algorithm.
#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012)
SHA3384 is defined in [FIPS202].
PSA_ALG_SHA3_512
(macro)
The SHA3512 messagedigest algorithm.
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013)
SHA3512 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, SHA3512 is recommended. SHA3512 has the same output size, and a theoretically higher security strength.
PSA_ALG_SM3
(macro)
The SM3 messagedigest algorithm.
#define PSA_ALG_SM3 ((psa_algorithm_t)0x02000014)
SM3 is defined in ISO/IEC 101183:2018 IT Security techniques — Hashfunctions — Part 3: Dedicated hashfunctions [ISO10118], and also in GM/T 00042012: SM3 cryptographic hash algorithm [CSTC0004] (English version [CSTC0004/E]).
10.2.2. Singlepart 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 thatPSA_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 leastPSA_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 ofhash
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 foralg
.

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 thatPSA_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 foralg
.

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. Multipart hashing operations
psa_hash_operation_t
(type)
The type of the state object for multipart hash operations.
typedef /* implementationdefined 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 allbitszero, 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 implementationdefined type. Applications that make assumptions about the content of this object will result in in implementationspecific behavior, and are nonportable.
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 /* implementationdefined 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 multipart 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 thatPSA_ALG_IS_HASH
(
alg
)
is true.
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
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 an 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, callpsa_hash_verify()
. To suspend the hash operation and extract the current state, callpsa_hash_suspend()
.
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 can 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:
 A successful call to
psa_hash_finish()
orpsa_hash_verify()
orpsa_hash_suspend()
.  A call to
psa_hash_abort()
.
psa_hash_update
(function)
Add a message fragment to a multipart 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 leastPSA_HASH_LENGTH
(
alg
)
wherealg
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
)
wherealg
is the hash algorithm that the operation performs.
Returns: psa_status_t

PSA_SUCCESS
 Success.
The first
(*hash_length)
bytes ofhash
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
)
wherealg
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.
 A sufficient output size is

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 ofhash_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()
orPSA_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.
 Allocate an operation object and initialize it as described in the documentation for
psa_hash_operation_t
.  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.  Call
psa_hash_suspend()
to extract the hash suspend state into a buffer.
 Allocate an operation object and initialize it as described in the documentation for
 Pass the hash state buffer to the application which will resume the operation.
 Compute the rest of the hash.
 Allocate an operation object and initialize it as described in the documentation for
psa_hash_operation_t
.  Call
psa_hash_resume()
with the extracted hash state.  Call
psa_hash_update()
zero, one or more times, passing a fragment of the message each time.  To calculate the hash, call
psa_hash_finish()
. To compare the hash with an expected value, callpsa_hash_verify()
.
 Allocate an operation object and initialize it as described in the documentation for
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 multipart 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()
orpsa_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 assource_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()
.
 The

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) /* implementationdefined 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.
See also PSA_HASH_MAX_SIZE
.
PSA_HASH_MAX_SIZE
(macro)
Maximum size of a hash.
#define PSA_HASH_MAX_SIZE /* implementationdefined 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.
See also PSA_HASH_LENGTH()
.
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) /* specificationdefined value */
Parameters

alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_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.
See also PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE
.
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 /* implementationdefined 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.
See also PSA_HASH_SUSPEND_OUTPUT_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 inputlength field that is part of the output of psa_hash_suspend()
, in bytes.
#define PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) \ /* specificationdefined value */
Parameters

alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
alg
)
is true.
Returns
The size, in bytes, of the inputlength 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 algorithmspecific 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 hashstate field that is part of the output of psa_hash_suspend()
, in bytes.
#define PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) \ /* specificationdefined value */
Parameters

alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_ALG_IS_HASH
(
alg
)
is true.
Returns
The size, in bytes, of the hashstate 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 algorithmspecific 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) /* implementationdefined value */
Parameters

alg
 A hash algorithm: a value of type
psa_algorithm_t
such thatPSA_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:
hashsuspendstate = algorithm  inputlength  hashstate  unprocessedinput
The fields in the hash suspend state are defined as follows:
 algorithm
A bigendian 32bit unsigned integer.
The PSA Crypto API algorithm identifier value.
The byte length of the algorithm field can be evaluated using
PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH
. inputlength
A bigendian unsigned integer
The content of this field is algorithmspecific:
 For MD2, this is the number of bytes in the unprocessedinput.
 For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the unprocessedinput bytes.
The size of this field is algorithmspecific:
 For MD2: inputlength is an 8bit unsigned integer.
 For MD4, MD5, RIPEMD160, SHA1, SHA224, and SHA256: inputlength is a 64bit unsigned integer.
 For SHA512/224, SHA512/256, SHA384, and SHA512: inputlength is a 128bit unsigned integer.
The length, in bytes, of the inputlength field can be calculated using
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH
(
alg
)
wherealg
is a hash algorithm. See Hash suspend state field sizes. hashstate
An array of bytes
Algorithmspecific intermediate hash state:
 For MD2: 16 bytes of internal checksum, then 48 bytes of intermediate digest.
 For MD4 and MD5: 4x 32bit integers, in littleendian encoding.
 For RIPEMD160: 5x 32bit integers, in littleendian encoding.
 For SHA1: 5x 32bit integers, in bigendian encoding.
 For SHA224 and SHA256: 8x 32bit integers, in bigendian encoding.
 For SHA512/224, SHA512/256, SHA384, and SHA512: 8x 64bit integers, in bigendian encoding.
The length of this field is specific to the algorithm. The length, in bytes, of the hashstate field can be calculated using
PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH
(
alg
)
wherealg
is a hash algorithm. See Hash suspend state field sizes. unprocessedinput
0 to (hashblocksize1) bytes
A partial block of unprocessed input data. This is between zero and hashblocksize1 bytes of data, the length can be calculated by:
length(
unprocessedinput)
=
inputlength%
hashblocksize.The hashblocksize is specific to the algorithm. The size of a hash block can be calculated using
PSA_HASH_BLOCK_LENGTH
(
alg
)
wherealg
is a hash algorithm. See Hash suspend state field sizes.
Hash suspend state field sizes
The following table defines the algorithmspecific 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 inputlength field.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH
(
alg
)
returns the length of the hashstate field.PSA_HASH_BLOCK_LENGTH
(
alg
)1
is the maximum length of the unprocessedbytes field.PSA_HASH_SUSPEND_OUTPUT_SIZE
(
alg
)
returns the maximum size of the hash suspend state.
Hash algorithm  inputlength size (bytes)  hashstate length (bytes)  unprocessedbytes 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 