10.3. Message authentication codes (MAC)¶

The single-part MAC functions are:

psa_mac_compute() to calculate the MAC of a message.
psa_mac_verify() to compare the MAC of a message with a reference value.

The psa_mac_operation_t multi-part operation allows messages to be processed in fragments. A multi-part MAC operation is used as follows:

Initialize the psa_mac_operation_t object to zero, or by assigning the value of the associated macro PSA_MAC_OPERATION_INIT.
Call psa_mac_sign_setup() or psa_mac_verify_setup() to specify the algorithm and key.
Call the psa_mac_update() function on successive chunks of the message.
At the end of the message, call the required finishing function:
- To calculate the MAC of the message, call psa_mac_sign_finish().
- To verify the MAC of the message against a reference value, call psa_mac_verify_finish().

To abort the operation or recover from an error, call psa_mac_abort().

10.3.1. MAC algorithms¶

`PSA_ALG_HMAC` (macro)¶

Macro to build an HMAC message-authentication-code algorithm from an underlying hash algorithm.

#define PSA_ALG_HMAC(hash_alg) /* specification-defined value */

Parameters

hash_alg: A hash algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(hash_alg) is true.

Returns

The corresponding HMAC algorithm.

Unspecified if hash_alg is not a supported hash algorithm.

Description

For example, PSA_ALG_HMAC(PSA_ALG_SHA_256) is HMAC-SHA-256.

The HMAC construction is defined in HMAC: Keyed-Hashing for Message Authentication [RFC2104].

Compatible key types

PSA_KEY_TYPE_HMAC

`PSA_ALG_CBC_MAC` (macro)¶

The CBC-MAC message-authentication-code algorithm, constructed over a block cipher.

#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)

Warning

CBC-MAC is insecure in many cases. A more secure mode, such as PSA_ALG_CMAC, is recommended.

The CBC-MAC algorithm must be used with a key for a block cipher. For example, one of PSA_KEY_TYPE_AES.

CBC-MAC is defined as MAC Algorithm 1 in ISO/IEC 9797-1:2011 Information technology — Security techniques — Message Authentication Codes (MACs) — Part 1: Mechanisms using a block cipher [ISO9797].

Compatible key types

PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4

`PSA_ALG_CMAC` (macro)¶

The CMAC message-authentication-code algorithm, constructed over a block cipher.

#define PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200)

The CMAC algorithm must be used with a key for a block cipher. For example, when used with a key with type PSA_KEY_TYPE_AES, the resulting operation is AES-CMAC.

CMAC is defined in NIST Special Publication 800-38B: Recommendation for Block Cipher Modes of Operation: the CMAC Mode for Authentication [SP800-38B].

Compatible key types

PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_DES
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4

`PSA_ALG_TRUNCATED_MAC` (macro)¶

Macro to build a truncated MAC algorithm.

#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
    /* specification-defined value */

Parameters

mac_alg: A MAC algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(mac_alg) is true. This can be a truncated or untruncated MAC algorithm.
mac_length: Desired length of the truncated MAC in bytes. This must be at most the untruncated length of the MAC and must be at least an implementation-specified minimum. The implementation-specified minimum must not be zero.

Returns

The corresponding MAC algorithm with the specified length.

Unspecified if mac_alg is not a supported MAC algorithm or if mac_length is too small or too large for the specified MAC algorithm.

Description

A truncated MAC algorithm is identical to the corresponding MAC algorithm except that the MAC value for the truncated algorithm consists of only the first mac_length bytes of the MAC value for the untruncated algorithm.

Note

This macro might allow constructing algorithm identifiers that are not valid, either because the specified length is larger than the untruncated MAC or because the specified length is smaller than permitted by the implementation.

Note

It is implementation-defined whether a truncated MAC that is truncated to the same length as the MAC of the untruncated algorithm is considered identical to the untruncated algorithm for policy comparison purposes.

The untruncated MAC algorithm can be recovered using PSA_ALG_FULL_LENGTH_MAC().

Compatible key types

The resulting truncated MAC algorithm is compatible with the same key types as the MAC algorithm used to construct it.

`PSA_ALG_FULL_LENGTH_MAC` (macro)¶

Macro to construct the MAC algorithm with an untruncated MAC, from a truncated MAC algorithm.

#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) /* specification-defined value */

Parameters

mac_alg: A MAC algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(mac_alg) is true. This can be a truncated or untruncated MAC algorithm.

Returns

The corresponding MAC algorithm with an untruncated MAC.

Unspecified if mac_alg is not a supported MAC algorithm.

Compatible key types

The resulting untruncated MAC algorithm is compatible with the same key types as the MAC algorithm used to construct it.

`PSA_ALG_AT_LEAST_THIS_LENGTH_MAC` (macro)¶

Macro to build a MAC minimum-MAC-length wildcard algorithm.

#define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
    /* specification-defined value */

Parameters

mac_alg: A MAC algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(alg) is true. This can be a truncated or untruncated MAC algorithm.
min_mac_length: Desired minimum length of the message authentication code in bytes. This must be at most the untruncated length of the MAC and must be at least 1.

Returns

The corresponding MAC wildcard algorithm with the specified minimum MAC length.

Unspecified if mac_alg is not a supported MAC algorithm or if min_mac_length is less than 1 or too large for the specified MAC algorithm.

Description

A key with a minimum-MAC-length MAC wildcard algorithm as permitted-algorithm policy can be used with all MAC algorithms sharing the same base algorithm, and where the (potentially truncated) MAC length of the specific algorithm is equal to or larger then the wildcard algorithm’s minimum MAC length.

Note

When setting the minimum required MAC length to less than the smallest MAC length permitted by the base algorithm, this effectively becomes an ‘any-MAC-length-permitted’ policy for that base algorithm.

The untruncated MAC algorithm can be recovered using PSA_ALG_FULL_LENGTH_MAC().

Compatible key types

The resulting wildcard MAC algorithm is compatible with the same key types as the MAC algorithm used to construct it.

10.3.2. Single-part MAC functions¶

`psa_mac_compute` (function)¶

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

psa_status_t psa_mac_compute(psa_key_id_t key,
                             psa_algorithm_t alg,
                             const uint8_t * input,
                             size_t input_length,
                             uint8_t * mac,
                             size_t mac_size,
                             size_t * mac_length);

Parameters

key

Identifier of the key to use for the operation. It must permit the usage PSA_KEY_USAGE_SIGN_MESSAGE.

alg

The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(alg) is true.

input

Buffer containing the input message.

input_length

Size of the input buffer in bytes.

mac

Buffer where the MAC value is to be written.

mac_size

Size of the mac buffer in bytes. This must be appropriate for the selected algorithm and key:

The exact MAC size is PSA_MAC_LENGTH(key_type, key_bits, alg) where key_type and key_bits are attributes of the key used to compute the MAC.
PSA_MAC_MAX_SIZE evaluates to the maximum MAC size of any supported MAC algorithm.

mac_length

On success, the number of bytes that make up the MAC value.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*mac_length) bytes of mac contain the MAC value.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL

The size of the mac buffer is too small. PSA_MAC_LENGTH() or PSA_MAC_MAX_SIZE 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 MAC algorithm.
key is not compatible with alg.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

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 might leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.

`psa_mac_verify` (function)¶

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

psa_status_t psa_mac_verify(psa_key_id_t key,
                            psa_algorithm_t alg,
                            const uint8_t * input,
                            size_t input_length,
                            const uint8_t * mac,
                            size_t mac_length);

Parameters

key: Identifier of the key to use for the operation. It must permit the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg: The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(alg) is true.
input: Buffer containing the input message.
input_length: Size of the input buffer in bytes.
mac: Buffer containing the expected MAC value.
mac_length: Size of the mac buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. The expected MAC is identical to the actual MAC of the input.

PSA_ERROR_BAD_STATE

The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE

The calculated MAC of the message does not match the value in mac.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

10.3.3. Multi-part MAC operations¶

`psa_mac_operation_t` (typedef)¶

The type of the state object for multi-part MAC operations.

typedef /* implementation-defined type */ psa_mac_operation_t;

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

Set the object to all-bits-zero, for example:

psa_mac_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_mac_operation_t operation;
```
Initialize the object to the initializer PSA_MAC_OPERATION_INIT, for example:
```
psa_mac_operation_t operation = PSA_MAC_OPERATION_INIT;
```
Assign the result of the function psa_mac_operation_init() to the object, for example:
```
psa_mac_operation_t operation;
operation = psa_mac_operation_init();
```

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in implementation-specific behavior, and are non-portable.

`PSA_MAC_OPERATION_INIT` (macro)¶

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

#define PSA_MAC_OPERATION_INIT /* implementation-defined value */

`psa_mac_operation_init` (function)¶

Return an initial value for a MAC operation object.

psa_mac_operation_t psa_mac_operation_init(void);

Returns: psa_mac_operation_t

`psa_mac_sign_setup` (function)¶

Set up a multi-part MAC calculation operation.

psa_status_t psa_mac_sign_setup(psa_mac_operation_t * operation,
                                psa_key_id_t key,
                                psa_algorithm_t alg);

Parameters

operation: The operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
key: Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must permit the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg: The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(alg) is true.

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

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_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function sets up the calculation of the message authentication code (MAC) 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:

Allocate a MAC 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_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Call psa_mac_sign_setup() to specify the algorithm and key.
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.
At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it.

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

A successful call to psa_mac_sign_finish().
A call to psa_mac_abort().

If psa_mac_sign_setup() returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state.

To abandon an active operation, or reset an operation in an error state, call psa_mac_abort().

See Multi-part operations.

`psa_mac_verify_setup` (function)¶

Set up a multi-part MAC verification operation.

psa_status_t psa_mac_verify_setup(psa_mac_operation_t * operation,
                                  psa_key_id_t key,
                                  psa_algorithm_t alg);

Parameters

operation: The operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
key: Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must permit the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg: The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(alg) is true.

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

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_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function sets up the verification of the message authentication code (MAC) of a byte string against an expected value.

The sequence of operations to verify a MAC is as follows:

Allocate a MAC 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_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Call psa_mac_verify_setup() to specify the algorithm and key.
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.
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.

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

A successful call to psa_mac_verify_finish().
A call to psa_mac_abort().

If psa_mac_verify_setup() returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state.

To abandon an active operation, or reset an operation in an error state, call psa_mac_abort().

See Multi-part operations.

`psa_mac_update` (function)¶

Add a message fragment to a multi-part MAC operation.

psa_status_t psa_mac_update(psa_mac_operation_t * operation,
                            const uint8_t * input,
                            size_t input_length);

Parameters

operation: Active MAC operation.
input: Buffer containing the message fragment to add to the MAC calculation.
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 MAC 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

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

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().

`psa_mac_sign_finish` (function)¶

Finish the calculation of the MAC of a message.

psa_status_t psa_mac_sign_finish(psa_mac_operation_t * operation,
                                 uint8_t * mac,
                                 size_t mac_size,
                                 size_t * mac_length);

Parameters

operation

Active MAC operation.

mac

Buffer where the MAC value is to be written.

mac_size

Size of the mac buffer in bytes. This must be appropriate for the selected algorithm and key:

The exact MAC size is PSA_MAC_LENGTH(key_type, key_bits, alg) where key_type and key_bits are attributes of the key, and alg is the algorithm used to compute the MAC.
PSA_MAC_MAX_SIZE evaluates to the maximum MAC size of any supported MAC algorithm.

mac_length

On success, the number of bytes that make up the MAC value. This is always PSA_MAC_LENGTH(key_type, key_bits, alg) where key_type and key_bits are attributes of the key, and alg is the algorithm used to compute the MAC.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*mac_length) bytes of mac contain the MAC value.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be an active mac sign operation.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the mac buffer is too small. PSA_MAC_LENGTH() or PSA_MAC_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

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 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_mac_abort().

Warning

It is not recommended to use this function when a specific value is expected for the MAC. Call psa_mac_verify_finish() instead with the expected MAC value.

Comparing integrity or authenticity data such as MAC 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 MAC and thereby bypass security controls.

`psa_mac_verify_finish` (function)¶

Finish the calculation of the MAC of a message and compare it with an expected value.

psa_status_t psa_mac_verify_finish(psa_mac_operation_t * operation,
                                   const uint8_t * mac,
                                   size_t mac_length);

Parameters

operation: Active MAC operation.
mac: Buffer containing the expected MAC value.
mac_length: Size of the mac buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. The expected MAC is identical to the actual MAC of the message.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be an active mac verify operation.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE

The calculated MAC of the message does not match the value in mac.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

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 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_mac_abort().

Note

Implementations must make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.

`psa_mac_abort` (function)¶

Abort a MAC operation.

psa_status_t psa_mac_abort(psa_mac_operation_t * operation);

Parameters

operation: Initialized MAC 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_mac_sign_setup() or psa_mac_verify_setup() again.

This function can be called 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.

10.3.4. Support macros¶

`PSA_ALG_IS_HMAC` (macro)¶

Whether the specified algorithm is an HMAC algorithm.

#define PSA_ALG_IS_HMAC(alg) /* specification-defined value */

Parameters

alg: An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an HMAC algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

Description

HMAC is a family of MAC algorithms that are based on a hash function.

`PSA_ALG_IS_BLOCK_CIPHER_MAC` (macro)¶

Whether the specified algorithm is a MAC algorithm based on a block cipher.

#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) /* specification-defined value */

Parameters

alg: An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a MAC algorithm based on a block cipher, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

`PSA_MAC_LENGTH` (macro)¶

The size of the output of psa_mac_compute() and psa_mac_sign_finish(), in bytes.

#define PSA_MAC_LENGTH(key_type, key_bits, alg) \
    /* implementation-defined value */

Parameters

key_type: The type of the MAC key.
key_bits: The size of the MAC key in bits.
alg: A MAC algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(alg) is true.

Returns

The MAC length for the specified algorithm with the specified key parameters.

0 if the MAC algorithm is not recognized.

Either 0 or the correct length for a MAC algorithm that the implementation recognizes, but does not support.

Unspecified if the key parameters are not consistent with the algorithm.

Description

If the size of the MAC buffer is at least this large, it is guaranteed that psa_mac_compute() and psa_mac_sign_finish() will not fail due to an insufficient buffer size.

This is also the MAC length that psa_mac_verify() and psa_mac_verify_finish() expect.

`PSA_MAC_MAX_SIZE` (macro)¶

A sufficient buffer size for storing the MAC output by psa_mac_verify() and psa_mac_verify_finish(), for any of the supported key types and MAC algorithms.

#define PSA_MAC_MAX_SIZE /* implementation-defined value */

If the size of the MAC buffer is at least this large, it is guaranteed that psa_mac_verify() and psa_mac_verify_finish() will not fail due to an insufficient buffer size.

10.3. Message authentication codes (MAC)¶

10.3.1. MAC algorithms¶

PSA_ALG_HMAC (macro)¶

PSA_ALG_CBC_MAC (macro)¶

PSA_ALG_CMAC (macro)¶

PSA_ALG_TRUNCATED_MAC (macro)¶

PSA_ALG_FULL_LENGTH_MAC (macro)¶

PSA_ALG_AT_LEAST_THIS_LENGTH_MAC (macro)¶

10.3.2. Single-part MAC functions¶

psa_mac_compute (function)¶

psa_mac_verify (function)¶

10.3.3. Multi-part MAC operations¶

psa_mac_operation_t (typedef)¶

PSA_MAC_OPERATION_INIT (macro)¶

psa_mac_operation_init (function)¶

psa_mac_sign_setup (function)¶

psa_mac_verify_setup (function)¶

psa_mac_update (function)¶

psa_mac_sign_finish (function)¶

psa_mac_verify_finish (function)¶

psa_mac_abort (function)¶

10.3.4. Support macros¶

PSA_ALG_IS_HMAC (macro)¶

PSA_ALG_IS_BLOCK_CIPHER_MAC (macro)¶

PSA_MAC_LENGTH (macro)¶

PSA_MAC_MAX_SIZE (macro)¶

`PSA_ALG_HMAC` (macro)¶

`PSA_ALG_CBC_MAC` (macro)¶

`PSA_ALG_CMAC` (macro)¶

`PSA_ALG_TRUNCATED_MAC` (macro)¶

`PSA_ALG_FULL_LENGTH_MAC` (macro)¶

`PSA_ALG_AT_LEAST_THIS_LENGTH_MAC` (macro)¶

`psa_mac_compute` (function)¶

`psa_mac_verify` (function)¶

`psa_mac_operation_t` (typedef)¶

`PSA_MAC_OPERATION_INIT` (macro)¶

`psa_mac_operation_init` (function)¶

`psa_mac_sign_setup` (function)¶

`psa_mac_verify_setup` (function)¶

`psa_mac_update` (function)¶

`psa_mac_sign_finish` (function)¶

`psa_mac_verify_finish` (function)¶

`psa_mac_abort` (function)¶

`PSA_ALG_IS_HMAC` (macro)¶

`PSA_ALG_IS_BLOCK_CIPHER_MAC` (macro)¶

`PSA_MAC_LENGTH` (macro)¶

`PSA_MAC_MAX_SIZE` (macro)¶