|
Platform Security Architecture — cryptography and keystore interface
Working draft
|
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) |
| #define PSA_HASH_SIZE | ( | alg | ) |
The size of the output of psa_hash_finish(), in bytes.
This is also the hash size that psa_hash_verify() expects.
| alg | A 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). |
| 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.
| 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:
struct to all-bits-zero.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.
| [in,out] | operation | Initialized hash operation. |
| PSA_SUCCESS | |
| PSA_ERROR_BAD_STATE | operation is not an active hash operation. |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| 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.
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.| [in,out] | operation | Active hash operation. |
| [out] | hash | Buffer where the hash is to be written. |
| hash_size | Size of the hash buffer in bytes. | |
| [out] | hash_length | On 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. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not started, or already completed). |
| PSA_ERROR_BUFFER_TOO_SMALL | The 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_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:
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:
| [out] | operation | The operation object to use. |
| alg | The hash algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_HASH(alg) is true). |
| PSA_SUCCESS | Success. |
| PSA_ERROR_NOT_SUPPORTED | alg 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_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.
| [in,out] | operation | Active hash operation. |
| [in] | input | Buffer containing the message fragment to hash. |
| input_length | Size of the input buffer in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The 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_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.
| [in,out] | operation | Active hash operation. |
| [in] | hash | Buffer containing the expected hash value. |
| hash_length | Size of the hash buffer in bytes. |
| PSA_SUCCESS | The expected hash is identical to the actual hash of the message. |
| PSA_ERROR_INVALID_SIGNATURE | The hash of the message was calculated successfully, but it differs from the expected hash. |
| PSA_ERROR_BAD_STATE | The 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 |
1.8.13