Message authentication codes

Macros

#define PSA_MAC_OPERATION_INIT   {0, 0, 0, 0, 0, 0, 0, 0, {0}}
 

Typedefs

typedef struct psa_mac_operation_s psa_mac_operation_t
 

Functions

psa_status_t psa_mac_compute (psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length)
 
psa_status_t psa_mac_verify (psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *mac, size_t mac_length)
 
static psa_mac_operation_t psa_mac_operation_init (void)
 
psa_status_t psa_mac_sign_setup (psa_mac_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
 
psa_status_t psa_mac_verify_setup (psa_mac_operation_t *operation, psa_key_handle_t handle, 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)
 

Macro Definition Documentation

#define PSA_MAC_OPERATION_INIT   {0, 0, 0, 0, 0, 0, 0, 0, {0}}

This macro returns a suitable initializer for a MAC operation object of type psa_mac_operation_t.

Definition at line 187 of file crypto_struct.h.

Referenced by psa_mac_operation_init().

Typedef Documentation

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

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

  • Set the structure to all-bits-zero, for example:
    1 psa_mac_operation_t operation;
    2 memset(&operation, 0, sizeof(operation));
  • Initialize the structure to logical zero values, for example:
    1 psa_mac_operation_t operation = {0};
  • Initialize the structure to the initializer PSA_MAC_OPERATION_INIT, for example:
    1 psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
  • Assign the result of the function psa_mac_operation_init() to the structure, for example:
    1 psa_mac_operation_t operation;
    2 operation = psa_mac_operation_init();

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.

Definition at line 1334 of file crypto.h.

Function Documentation

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 one of the methods described in psa_mac_operation_t.

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.

Parameters
[in,out]operationInitialized MAC operation.
Return values
PSA_SUCCESS
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_mac_compute ( psa_key_handle_t  handle,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
uint8_t *  mac,
size_t  mac_size,
size_t *  mac_length 
)

Calculate the MAC (message authentication code) of a message.

Note
To verify the MAC of a message against an expected value, use psa_mac_verify() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as 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.
Parameters
handleHandle to the key to use for the operation.
algThe MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
[in]inputBuffer containing the input message.
input_lengthSize of the input buffer in bytes.
[out]macBuffer where the MAC value is to be written.
mac_sizeSize of the mac buffer in bytes.
[out]mac_lengthOn success, the number of bytes that make up the MAC value.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a MAC algorithm.
PSA_ERROR_BUFFER_TOO_SMALLmac_size is too small
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILUREThe key could not be retrieved from storage.
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
static psa_mac_operation_t psa_mac_operation_init ( void  )
static

Return an initial value for a MAC operation object.

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 successfuly, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Warning
Applications should not call this function if they expect a specific value for the MAC. Call psa_mac_verify_finish() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as 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.
Parameters
[in,out]operationActive MAC operation.
[out]macBuffer where the MAC value is to be written.
mac_sizeSize of the mac buffer in bytes.
[out]mac_lengthOn 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.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be an active mac sign operation).
PSA_ERROR_BUFFER_TOO_SMALLThe 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_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_mac_sign_setup ( psa_mac_operation_t operation,
psa_key_handle_t  handle,
psa_algorithm_t  alg 
)

Set up 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:

  1. Allocate an operation object which will be passed to all the functions listed here.
  2. Initialize the operation object with one of the methods described in the documentation for psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
  3. Call psa_mac_sign_setup() to specify the algorithm and key.
  4. Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
  5. At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it.

If an error occurs at any step after a call to psa_mac_sign_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.

After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
handleHandle to the key to use for the operation. It must remain valid until the operation terminates.
algThe MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a MAC algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILUREThe key could not be retrieved from storage.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be inactive).
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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 enters an error state and must be aborted by calling psa_mac_abort().

Parameters
[in,out]operationActive MAC operation.
[in]inputBuffer containing the message fragment to add to the MAC calculation.
input_lengthSize of the input buffer in bytes.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be active).
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_mac_verify ( psa_key_handle_t  handle,
psa_algorithm_t  alg,
const uint8_t *  input,
size_t  input_length,
const uint8_t *  mac,
size_t  mac_length 
)

Calculate the MAC of a message and compare it with a reference value.

Parameters
handleHandle to the key to use for the operation.
algThe MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
[in]inputBuffer containing the input message.
input_lengthSize of the input buffer in bytes.
[out]macBuffer containing the expected MAC value.
mac_lengthSize of the mac buffer in bytes.
Return values
PSA_SUCCESSThe expected MAC is identical to the actual MAC of the input.
PSA_ERROR_INVALID_SIGNATUREThe MAC of the message was calculated successfully, but it differs from the expected value.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENThandle is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a MAC algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILUREThe key could not be retrieved from storage.
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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 successfuly, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Note
Implementations shall make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.
Parameters
[in,out]operationActive MAC operation.
[in]macBuffer containing the expected MAC value.
mac_lengthSize of the mac buffer in bytes.
Return values
PSA_SUCCESSThe expected MAC is identical to the actual MAC of the message.
PSA_ERROR_INVALID_SIGNATUREThe MAC of the message was calculated successfully, but it differs from the expected MAC.
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be an active mac verify operation).
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_mac_verify_setup ( psa_mac_operation_t operation,
psa_key_handle_t  handle,
psa_algorithm_t  alg 
)

Set up 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:

  1. Allocate an operation object which will be passed to all the functions listed here.
  2. Initialize the operation object with one of the methods described in the documentation for psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
  3. Call psa_mac_verify_setup() to specify the algorithm and key.
  4. Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
  5. At the end of the message, call psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.

If an error occurs at any step after a call to psa_mac_verify_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application may call psa_mac_abort() at any time after the operation has been initialized.

After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:

Parameters
[in,out]operationThe operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
handleHandle to the key to use for the operation. It must remain valid until the operation terminates.
algThe MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(alg) is true).
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_INVALID_HANDLE
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTkey is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg is not supported or is not a MAC algorithm.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_HARDWARE_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILUREThe key could not be retrieved from storage
PSA_ERROR_BAD_STATEThe operation state is not valid (it must be inactive).
PSA_ERROR_BAD_STATEThe library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.