Platform Security Architecture — cryptography and keystore interface  Working draft
Macros | Typedefs | Functions
Message digests

Macros

#define PSA_HASH_SIZE(alg)
 

Typedefs

typedef struct psa_hash_operation_s psa_hash_operation_t
 

Functions

psa_status_t psa_hash_setup (psa_hash_operation_t *operation, psa_algorithm_t alg)
 
psa_status_t psa_hash_update (psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
 
psa_status_t psa_hash_finish (psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
 
psa_status_t psa_hash_verify (psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)
 
psa_status_t psa_hash_abort (psa_hash_operation_t *operation)
 

Detailed Description

Macro Definition Documentation

◆ PSA_HASH_SIZE

#define PSA_HASH_SIZE (   alg)
Value:
( \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_MD2 ? 16 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_MD4 ? 16 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_MD5 ? 16 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_224 ? 28 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_256 ? 32 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_384 ? 48 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_512 ? 64 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_512_224 ? 28 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA_512_256 ? 32 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_224 ? 28 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_256 ? 32 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_384 ? 48 : \
PSA_ALG_HMAC_HASH(alg) == PSA_ALG_SHA3_512 ? 64 : \
0)
#define PSA_ALG_SHA3_256
Definition: crypto.h:686
#define PSA_ALG_SHA3_224
Definition: crypto.h:684
#define PSA_ALG_SHA3_512
Definition: crypto.h:690
#define PSA_ALG_SHA_256
Definition: crypto.h:674
#define PSA_ALG_SHA_512
Definition: crypto.h:678
#define PSA_ALG_SHA_224
Definition: crypto.h:672
#define PSA_ALG_SHA_384
Definition: crypto.h:676
#define PSA_ALG_SHA_512_224
Definition: crypto.h:680
#define PSA_ALG_SHA_512_256
Definition: crypto.h:682
#define PSA_ALG_SHA3_384
Definition: crypto.h:688

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

This is also the hash size that psa_hash_verify() expects.

Parameters
algA hash algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true), or an HMAC algorithm (PSA_ALG_HMAC(hash_alg) where hash_alg is a hash algorithm).
Returns
The hash size for the specified hash algorithm. If the hash algorithm is not recognized, return 0. An implementation may return either 0 or the correct size for a hash algorithm that it recognizes, but does not support.

Typedef Documentation

◆ psa_hash_operation_t

typedef struct psa_hash_operation_s psa_hash_operation_t

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

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.

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 any of the following methods:

  • A call to psa_hash_setup(), whether it succeeds or not.
  • Initializing the struct to all-bits-zero.
  • Initializing the struct to logical zeros, e.g. psa_hash_operation_t operation = {0}.

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
PSA_ERROR_BAD_STATEoperation is not an active hash operation.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ 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, the operation becomes inactive.

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_SIZE(alg) where alg is the hash algorithm that is calculated.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BAD_STATEThe operation state is not valid (not started, or already completed).
PSA_ERROR_BUFFER_TOO_SMALLThe size of the hash buffer is too small. You can determine a sufficient buffer size by calling PSA_HASH_SIZE(alg) where alg is the hash algorithm that is calculated.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ psa_hash_setup()

psa_status_t psa_hash_setup ( psa_hash_operation_t operation,
psa_algorithm_t  alg 
)

Start 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. 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. The hash that is calculated is the hash of the concatenation of these messages in order.
  4. To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify().

The application may call psa_hash_abort() at any time after the operation has been initialized with psa_hash_setup().

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

Parameters
[out]operationThe operation object to 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 supported or is not a hash algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ 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 becomes inactive.

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_BAD_STATEThe operation state is not valid (not started, or already completed).
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED

◆ 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, the operation becomes inactive.

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_BAD_STATEThe operation state is not valid (not started, or already completed).
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_TAMPERING_DETECTED