10.1. Algorithms

This specification encodes algorithms into a structured 32-bit integer value.

Algorithm identifiers are used for two purposes in the Crypto API:

  1. To specify a specific algorithm to use in a cryptographic operation. These are all defined in Cryptographic operation reference.

  2. To specify the policy for a key, identifying the permitted algorithm for use with the key. This use is described in Key policies.

The specific algorithm identifiers are described alongside the cryptographic operation functions to which they apply:

10.1.1. Algorithm encoding

psa_algorithm_t (typedef)

Encoding of a cryptographic algorithm.

typedef uint32_t psa_algorithm_t;

This is a structured bitfield that identifies the category and type of algorithm. The range of algorithm identifier values is divided as follows:

0x00000000

Reserved as an invalid algorithm identifier.

0x00000001 0x7fffffff

Specification-defined algorithm identifiers. Algorithm identifiers defined by this standard always have bit 31 clear. Unallocated algorithm identifier values in this range are reserved for future use.

0x80000000 0xffffffff

Implementation-defined algorithm identifiers. Implementations that define additional algorithms must use an encoding with bit 31 set. The related support macros will be easier to write if these algorithm identifier encodings also respect the bitwise structure used by standard encodings.

For algorithms that can be applied to multiple key types, this identifier does not encode the key type. For example, for symmetric ciphers based on a block cipher, psa_algorithm_t encodes the block cipher mode and the padding mode while the block cipher itself is encoded via psa_key_type_t.

The Algorithm and key type encoding appendix provides a full definition of the algorithm identifier encoding.

PSA_ALG_NONE (macro)

An invalid algorithm identifier value.

#define PSA_ALG_NONE ((psa_algorithm_t)0)

Zero is not the encoding of any algorithm.

10.1.2. Algorithm categories

PSA_ALG_IS_HASH (macro)

Whether the specified algorithm is a hash algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See Hash algorithms for a list of defined hash algorithms.

PSA_ALG_IS_MAC (macro)

Whether the specified algorithm is a MAC algorithm.

#define PSA_ALG_IS_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, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported algorithm identifier.

Description

See MAC algorithms for a list of defined MAC algorithms.

PSA_ALG_IS_CIPHER (macro)

Whether the specified algorithm is a symmetric cipher algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See Cipher algorithms for a list of defined cipher algorithms.

PSA_ALG_IS_AEAD (macro)

Whether the specified algorithm is an authenticated encryption with associated data (AEAD) algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See AEAD algorithms for a list of defined AEAD algorithms.

PSA_ALG_IS_SIGN (macro)

Whether the specified algorithm is an asymmetric signature algorithm, also known as public-key signature algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See Asymmetric signature algorithms for a list of defined signature algorithms.

PSA_ALG_IS_ASYMMETRIC_ENCRYPTION (macro)

Whether the specified algorithm is an asymmetric encryption algorithm, also known as public-key encryption algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See Asymmetric encryption algorithms for a list of defined asymmetric encryption algorithms.

PSA_ALG_IS_KEY_AGREEMENT (macro)

Whether the specified algorithm is a key agreement algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See Key agreement algorithms for a list of defined key agreement algorithms.

PSA_ALG_IS_KEY_DERIVATION (macro)

Whether the specified algorithm is a key derivation algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

Description

See Key derivation algorithms for a list of defined key derivation algorithms.

PSA_ALG_IS_WILDCARD (macro)

Whether the specified algorithm encoding is a wildcard.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a wildcard algorithm encoding.

0 if alg is a non-wildcard algorithm encoding that is suitable for an operation.

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

Description

Wildcard algorithm values can only be used to set the permitted-algorithm field in a key policy, wildcard values cannot be used to perform an operation.

See PSA_ALG_ANY_HASH for example of how a wildcard algorithm can be used in a key policy.

PSA_ALG_GET_HASH (macro)

Get the hash used by a composite algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

The underlying hash algorithm if alg is a composite algorithm that uses a hash algorithm.

PSA_ALG_NONE if alg is not a composite algorithm that uses a hash.

Description

The following composite algorithms require a hash algorithm: