MAC algorithm definitions for the PSA Crypto API. More...

Detailed Description

MAC algorithm definitions for the PSA Crypto API.

Author: Armin Wolf wolf..nosp@m.armi.nosp@m.n@mai.nosp@m.lbox.nosp@m..tu-d.nosp@m.resd.nosp@m.en.de; Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

Definition in file algorithm.h.

#include "psa/algorithm.h"
#include "psa/hash/algorithm.h"

Include dependency graph for algorithm.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define	PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x03000000)
	Category for MAC algorithms.

#define	PSA_ALG_HMAC_BASE (0x03800000)
	HMAC Base.

#define	PSA_ALG_IS_MAC(alg) (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)
	Whether the specified algorithm is a MAC algorithm.

#define	PSA_ALG_IS_HMAC(alg) (((alg) & 0x7fc0ff00) == 0x03800000)
	Whether the specified algorithm is an HMAC algorithm.

#define	PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) (((alg) & 0x7fc00000) == 0x03c00000)
	Whether the specified algorithm is a MAC algorithm based on a block cipher.

#define	PSA_ALG_HMAC(hash_alg) ((psa_algorithm_t)(PSA_ALG_HMAC_BASE \| ((hash_alg) & PSA_ALG_HASH_MASK)))
	Macro to build an HMAC message-authentication-code algorithm from an underlying hash algorithm.

#define	PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)
	The CBC-MAC message-authentication-code algorithm, constructed over a block cipher.

#define	PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200)
	The CMAC message-authentication-code algorithm, constructed over a block cipher.

#define	PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) ((psa_algorithm_t)(((mac_alg) & ~0x003f0000) \| (((mac_length) & 0x3f) << 16)))
	Macro to build a truncated MAC algorithm.

#define	PSA_ALG_FULL_LENGTH_MAC(mac_alg) ((psa_algorithm_t)((mac_alg) & ~0x003f0000))
	Macro to construct the MAC algorithm with a full length MAC, from a truncated MAC algorithm.

#define	PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) /* specification-defined value */
	Macro to build a MAC minimum-MAC-length wildcard algorithm.

Macro Definition Documentation

◆ PSA_ALG_AT_LEAST_THIS_LENGTH_MAC

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

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

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 allowed by the base algorithm, this effectively becomes an ‘any-MAC-length-allowed’ 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.

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.

Definition at line 218 of file algorithm.h.

◆ PSA_ALG_CATEGORY_MAC

#define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x03000000)

Category for MAC algorithms.

Definition at line 35 of file algorithm.h.

◆ PSA_ALG_CBC_MAC

#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x03c00100)

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

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

Definition at line 115 of file algorithm.h.

◆ PSA_ALG_CMAC

#define PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200)

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

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

Definition at line 134 of file algorithm.h.

◆ PSA_ALG_FULL_LENGTH_MAC

#define PSA_ALG_FULL_LENGTH_MAC ( mac_alg ) ((psa_algorithm_t)((mac_alg) & ~0x003f0000))

Macro to construct the MAC algorithm with a full length MAC, from a truncated 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.

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 a full length MAC. Unspecified if mac_alg is not a supported MAC algorithm. *

Definition at line 187 of file algorithm.h.

◆ PSA_ALG_HMAC

#define PSA_ALG_HMAC ( hash_alg ) ((psa_algorithm_t)(PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK)))

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

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

Parameters

hash_alg A hash algorithm (PSA_ALG_XXX value 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.

Definition at line 91 of file algorithm.h.

◆ PSA_ALG_HMAC_BASE

#define PSA_ALG_HMAC_BASE (0x03800000)

HMAC Base.

Definition at line 40 of file algorithm.h.

◆ PSA_ALG_IS_BLOCK_CIPHER_MAC

#define PSA_ALG_IS_BLOCK_CIPHER_MAC ( alg ) (((alg) & 0x7fc00000) == 0x03c00000)

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

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

Definition at line 72 of file algorithm.h.

◆ PSA_ALG_IS_HMAC

#define PSA_ALG_IS_HMAC ( alg ) (((alg) & 0x7fc0ff00) == 0x03800000)

Whether the specified algorithm is an HMAC algorithm.

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

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is an HMAC algorithm 0 otherwise

Definition at line 62 of file algorithm.h.

◆ PSA_ALG_IS_MAC

#define PSA_ALG_IS_MAC ( alg ) (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)

Whether the specified algorithm is a MAC algorithm.

Parameters

alg	An algorithm identifier: a value of type psa_algorithm_t.

Returns: 1 if alg is a MAC algorithm 0 otherwise

Definition at line 50 of file algorithm.h.

◆ PSA_ALG_TRUNCATED_MAC

#define PSA_ALG_TRUNCATED_MAC	(	mac_alg,
		mac_length
	)	((psa_algorithm_t)(((mac_alg) & ~0x003f0000) \| (((mac_length) & 0x3f) << 16)))

Macro to build a truncated MAC algorithm.

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.; 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.

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.

Definition at line 169 of file algorithm.h.