|
Platform Security Architecture — cryptography and keystore interface
Working draft
|
Typedefs | |
| typedef struct psa_mac_operation_s | psa_mac_operation_t |
Functions | |
| psa_status_t | psa_mac_sign_setup (psa_mac_operation_t *operation, psa_key_slot_t key, psa_algorithm_t alg) |
| psa_status_t | psa_mac_verify_setup (psa_mac_operation_t *operation, psa_key_slot_t key, psa_algorithm_t alg) |
| psa_status_t | psa_mac_update (psa_mac_operation_t *operation, const uint8_t *input, size_t input_length) |
| psa_status_t | psa_mac_sign_finish (psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length) |
| psa_status_t | psa_mac_verify_finish (psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length) |
| psa_status_t | psa_mac_abort (psa_mac_operation_t *operation) |
| typedef struct psa_mac_operation_s psa_mac_operation_t |
The type of the state data structure for multipart MAC 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_mac_abort | ( | psa_mac_operation_t * | operation | ) |
Abort a MAC 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_mac_sign_setup() or psa_mac_verify_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_mac_operation_t operation = {0}.In particular, calling psa_mac_abort() after the operation has been terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or psa_mac_verify_finish() is safe and has no effect.
| [in,out] | operation | Initialized MAC operation. |
| PSA_SUCCESS | |
| PSA_ERROR_BAD_STATE | operation is not an active MAC operation. |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| psa_status_t psa_mac_sign_finish | ( | psa_mac_operation_t * | operation, |
| uint8_t * | mac, | ||
| size_t | mac_size, | ||
| size_t * | mac_length | ||
| ) |
Finish the calculation of the MAC of a message.
The application must call psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update().
When this function returns, the operation becomes inactive.
memcmp is risky because the time taken by the comparison may leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.| [in,out] | operation | Active MAC operation. |
| [out] | mac | Buffer where the MAC value is to be written. |
| mac_size | Size of the mac buffer in bytes. | |
| [out] | mac_length | On success, the number of bytes that make up the MAC value. This is always PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size respectively of the key and alg is the MAC 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 mac buffer is too small. You can determine a sufficient buffer size by calling PSA_MAC_FINAL_SIZE(). |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| psa_status_t psa_mac_sign_setup | ( | psa_mac_operation_t * | operation, |
| psa_key_slot_t | key, | ||
| psa_algorithm_t | alg | ||
| ) |
Start a multipart MAC calculation operation.
This function sets up the calculation of the MAC (message authentication code) of a byte string. To verify the MAC of a message against an expected value, use psa_mac_verify_setup() instead.
The sequence of operations to calculate a MAC is as follows:
The application may call psa_mac_abort() at any time after the operation has been initialized with psa_mac_sign_setup().
After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:
| [out] | operation | The operation object to use. |
| key | Slot containing the key to use for the operation. | |
| alg | The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true). |
| PSA_SUCCESS | Success. |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | key is not compatible with alg. |
| PSA_ERROR_NOT_SUPPORTED | alg is not supported or is not a MAC algorithm. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| psa_status_t psa_mac_update | ( | psa_mac_operation_t * | operation, |
| const uint8_t * | input, | ||
| size_t | input_length | ||
| ) |
Add a message fragment to a multipart MAC operation.
The application must call psa_mac_sign_setup() or psa_mac_verify_setup() before calling this function.
If this function returns an error status, the operation becomes inactive.
| [in,out] | operation | Active MAC operation. |
| [in] | input | Buffer containing the message fragment to add to the MAC calculation. |
| 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_mac_verify_finish | ( | psa_mac_operation_t * | operation, |
| const uint8_t * | mac, | ||
| size_t | mac_length | ||
| ) |
Finish the calculation of the MAC of a message and compare it with an expected value.
The application must call psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function.
When this function returns, the operation becomes inactive.
| [in,out] | operation | Active MAC operation. |
| [in] | mac | Buffer containing the expected MAC value. |
| mac_length | Size of the mac buffer in bytes. |
| PSA_SUCCESS | The expected MAC is identical to the actual MAC of the message. |
| PSA_ERROR_INVALID_SIGNATURE | The MAC of the message was calculated successfully, but it differs from the expected MAC. |
| 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_mac_verify_setup | ( | psa_mac_operation_t * | operation, |
| psa_key_slot_t | key, | ||
| psa_algorithm_t | alg | ||
| ) |
Start a multipart MAC verification operation.
This function sets up the verification of the MAC (message authentication code) of a byte string against an expected value.
The sequence of operations to verify a MAC is as follows:
The application may call psa_mac_abort() at any time after the operation has been initialized with psa_mac_verify_setup().
After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:
| [out] | operation | The operation object to use. |
| key | Slot containing the key to use for the operation. | |
| alg | The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true). |
| PSA_SUCCESS | Success. |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | key is not compatible with alg. |
| PSA_ERROR_NOT_SUPPORTED | alg is not supported or is not a MAC algorithm. |
| PSA_ERROR_INSUFFICIENT_MEMORY | |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
1.8.13