PSA Certified Crypto API 1.1 (2023)

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_aead_encrypt_setup() or

psa_aead_decrypt_setup() again.

This function can be called any time after the operation object has been initialized as described in

psa_aead_operation_t.

In particular, calling psa_aead_abort() after the operation has been terminated by a call to psa_aead_abort(),

psa_aead_finish() or psa_aead_verify() is safe and has no effect.

10.5.4 Support macros

PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER (macro)

Whether the specified algorithm is an AEAD mode on a block cipher.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an AEAD algorithm which is an AEAD mode based on a block cipher, 0 otherwise.

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

PSA_AEAD_ENCRYPT_OUTPUT_SIZE (macro)

A sufficient ciphertext buffer size for psa_aead_encrypt(), in bytes.

#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) \

/* implementation-defined value */

Parameters

key_type

A symmetric key type that is compatible with algorithm alg.

alg

An AEAD algorithm: a value of type psa_algorithm_t such that

PSA_ALG_IS_AEAD(alg) is true.

plaintext_length

Size of the plaintext in bytes.

IHI 0086

Page 199

1.1.2

Non-confidential

Returns

The AEAD ciphertext size for the specified key type and algorithm. If the key type or AEAD algorithm is

not recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a

correct size for a key type and AEAD algorithm that it recognizes, but does not support.

Description

If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_encrypt() will not fail

due to an insufficient buffer size. Depending on the algorithm, the actual size of the ciphertext might be

smaller.

See also PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE.

PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE (macro)

A sufficient ciphertext buffer size for psa_aead_encrypt(), for any of the supported key types and AEAD

algorithms.

#define PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) \

/* implementation-defined value */

Parameters

plaintext_length

Size of the plaintext in bytes.

Description

If the size of the ciphertext buffer is at least this large, it is guaranteed that psa_aead_encrypt() will not fail

due to an insufficient buffer size.

See also PSA_AEAD_ENCRYPT_OUTPUT_SIZE().

PSA_AEAD_DECRYPT_OUTPUT_SIZE (macro)

A sufficient plaintext buffer size for psa_aead_decrypt(), in bytes.

#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \

/* implementation-defined value */

Parameters

key_type

A symmetric key type that is compatible with algorithm alg.

alg

An AEAD algorithm: a value of type psa_algorithm_t such that

PSA_ALG_IS_AEAD(alg) is true.

ciphertext_length

Size of the ciphertext in bytes.

IHI 0086

Page 200

1.1.2

Non-confidential

Returns

The AEAD plaintext size for the specified key type and algorithm. If the key type or AEAD algorithm is not

recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a

correct size for a key type and AEAD algorithm that it recognizes, but does not support.

Description

If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_decrypt() will not fail

due to an insufficient buffer size. Depending on the algorithm, the actual size of the plaintext might be

smaller.

See also PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE.

PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE (macro)

A sufficient plaintext buffer size for psa_aead_decrypt(), for any of the supported key types and AEAD

algorithms.

#define PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) \

/* implementation-defined value */

Parameters

ciphertext_length

Size of the ciphertext in bytes.

Description

If the size of the plaintext buffer is at least this large, it is guaranteed that psa_aead_decrypt() will not fail

due to an insufficient buffer size.

See also PSA_AEAD_DECRYPT_OUTPUT_SIZE().

PSA_AEAD_NONCE_LENGTH (macro)

The default nonce size for an AEAD algorithm, in bytes.

#define PSA_AEAD_NONCE_LENGTH(key_type, alg) /* implementation-defined value */

Parameters

key_type

A symmetric key type that is compatible with algorithm alg.

alg

An AEAD algorithm: a value of type psa_algorithm_t such that

PSA_ALG_IS_AEAD(alg) is true.

Returns

The default nonce size for the specified key type and algorithm. If the key type or AEAD algorithm is not

recognized, or the parameters are incompatible, return 0. An implementation can return either 0 or a

correct size for a key type and AEAD algorithm that it recognizes, but does not support.

IHI 0086

Page 201

1.1.2

Non-confidential

Description

If the size of the nonce buffer is at least this large, it is guaranteed that psa_aead_generate_nonce() will not

fail due to an insufficient buffer size.

For most AEAD algorithms, PSA_AEAD_NONCE_LENGTH() evaluates to the exact size of the nonce generated by

psa_aead_generate_nonce().

See also PSA_AEAD_VERIFY_OUTPUT_SIZE().

10.6 Key derivation

A key derivation encodes a deterministic method to generate a finite stream of bytes. This data stream is

computed by the cryptoprocessor and extracted in chunks. If two key derivation operations are

constructed with the same parameters, then they produce the same output.

A key derivation consists of two phases:

1. Input collection. This is sometimes known as extraction: the operation “extracts” information from

the inputs to generate a pseudorandom intermediate secret value.

2. Output generation. This is sometimes known as expansion: the operation “expands” the intermediate

secret value to the desired output length.

The specification defines a multi-part operation API for key derivation that allows:

∙ Multiple key and non-key outputs to be produced from a single derivation operation object.

∙ Key and non-key outputs can be extracted from the key derivation object, or compared with existing

key and non-key values.

∙ Algorithms that require high-entropy secret inputs. For example PSA_ALG_HKDF.

∙ Algorithms that work with low-entropy secret inputs, or passwords. For example

PSA_ALG_PBKDF2_HMAC().

IHI 0086

Page 205

1.1.2

Non-confidential

An implementation with isolation has the following properties:

∙ The intermediate state of the key derivation is not visible to the caller.

∙ If an output of the derivation is a non-exportable key, then this key cannot be recovered outside the

isolation boundary.

∙ If an output of the derivation is compared using psa_key_derivation_verify_bytes() or

psa_key_derivation_verify_key(), then the output is not visible to the caller.

Applications use the psa_key_derivation_operation_t type to create key derivation operations. The

operation object is used as follows:

1. Initialize a psa_key_derivation_operation_t object to zero or to PSA_KEY_DERIVATION_OPERATION_INIT.

2. Call psa_key_derivation_setup() to select a key derivation algorithm.

3. Call the functions psa_key_derivation_input_key() or psa_key_derivation_key_agreement() to provide

the secret inputs, and psa_key_derivation_input_bytes() or psa_key_derivation_input_integer() to

provide the non-secret inputs, to the key derivation algorithm. Many key derivation algorithms take

multiple inputs; the step parameter to these functions indicates which input is being provided. The

documentation for each key derivation algorithm describes the expected inputs for that algorithm

and in what order to pass them.

4. Optionally, call psa_key_derivation_set_capacity() to set a limit on the amount of data that can be

output from the key derivation operation.

5. Call an output or verification function:

∙ psa_key_derivation_output_key() to create a derived key.

∙ psa_key_derivation_output_bytes() to export the derived data.

∙ psa_key_derivation_verify_key() to compare a derived key with an existing key value.

∙ psa_key_derivation_verify_bytes() to compare derived data with a buffer.

These functions can be called multiple times to read successive output from the key derivation, until

the stream is exhausted when its capacity has been reached.

6. Key derivation does not finish in the same way as other multi-part operations. Call

psa_key_derivation_abort() to release the key derivation operation memory when the object is no

longer required.

To recover from an error, call psa_key_derivation_abort() to release the key derivation operation memory.

A key derivation operation cannot be rewound. Once a part of the stream has been output, it cannot be

output again. This ensures that the same part of the output will not be used for different purposes.

10.6.1 Key derivation algorithms

PSA_ALG_HKDF (macro)

Macro to build an HKDF algorithm.

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

IHI 0086

Page 206

1.1.2

Non-confidential

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 HKDF algorithm. For example, PSA_ALG_HKDF(PSA_ALG_SHA_256) is HKDF using

HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This is the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) specified by HMAC-based

Extract-and-Expand Key Derivation Function (HKDF) [RFC5869].

This key derivation algorithm uses the following inputs:

∙ PSA_KEY_DERIVATION_INPUT_SALT is the salt used in the “extract” step. It is optional; if omitted, the

derivation uses an empty salt.

∙ PSA_KEY_DERIVATION_INPUT_SECRET is the secret key (input keying material) used in the “extract” step.

∙ PSA_KEY_DERIVATION_INPUT_INFO is the info string used in the “expand” step.

If PSA_KEY_DERIVATION_INPUT_SALT is provided, it must be before PSA_KEY_DERIVATION_INPUT_SECRET.

PSA_KEY_DERIVATION_INPUT_INFO can be provided at any time after setup and before starting to generate

output.

Warning: HKDF processes the salt as follows: first hash it with hash_alg if the salt is longer than the

block size of the hash algorithm; then pad with null bytes up to the block size. As a result, it is possible

for distinct salt inputs to result in the same outputs. To ensure unique outputs, it is recommended to

use a fixed length for salt values.

Each input may only be passed once.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the secret key)

PSA_KEY_TYPE_RAW_DATA (for the other inputs)

PSA_ALG_HKDF_EXTRACT (macro)

Macro to build an HKDF-Extract algorithm.

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

IHI 0086

Page 207

1.1.2

Non-confidential

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 HKDF-Extract algorithm. For example, PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA_256) is

HKDF-Extract using HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This is the Extract step of HKDF as specified by HMAC-based Extract-and-Expand Key Derivation Function

(HKDF) [RFC5869] §2.2.

This key derivation algorithm uses the following inputs:

∙ PSA_KEY_DERIVATION_INPUT_SALT is the salt.

∙ PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used in the “extract” step.

The inputs are mandatory and must be passed in the order above. Each input may only be passed once.

Warning: HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF should be used instead if

possible. PSA_ALG_HKDF_EXTRACT is provided as a separate algorithm for the sake of protocols that use it

as a building block. It may also be a slight performance optimization in applications that use HKDF with

the same salt and key but many different info strings.

Warning: HKDF processes the salt as follows: first hash it with hash_alg if the salt is longer than the

block size of the hash algorithm; then pad with null bytes up to the block size. As a result, it is possible

for distinct salt inputs to result in the same outputs. To ensure unique outputs, it is recommended to

use a fixed length for salt values.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the input keying material)

PSA_KEY_TYPE_RAW_DATA (for the salt)

PSA_ALG_HKDF_EXPAND (macro)

Macro to build an HKDF-Expand algorithm.

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

IHI 0086

Page 208

1.1.2

Non-confidential

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 HKDF-Expand algorithm. For example, PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA_256) is

HKDF-Expand using HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This is the Expand step of HKDF as specified by HMAC-based Extract-and-Expand Key Derivation Function

(HKDF) [RFC5869] §2.3.

This key derivation algorithm uses the following inputs:

∙ PSA_KEY_DERIVATION_INPUT_SECRET is the pseudoramdom key (PRK).

∙ PSA_KEY_DERIVATION_INPUT_INFO is the info string.

The inputs are mandatory and must be passed in the order above. Each input may only be passed once.

Warning: HKDF-Expand is not meant to be used on its own. PSA_ALG_HKDF should be used instead if

possible. PSA_ALG_HKDF_EXPAND is provided as a separate algorithm for the sake of protocols that use it as

a building block. It may also be a slight performance optimization in applications that use HKDF with

the same salt and key but many different info strings.

Compatible key types

PSA_KEY_TYPE_DERIVE (for the pseudorandom key)

PSA_KEY_TYPE_RAW_DATA (for the info string)

PSA_ALG_TLS12_PRF (macro)

Macro to build a TLS-1.2 PRF algorithm.

#define PSA_ALG_TLS12_PRF(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.

IHI 0086

Page 209

1.1.2

Non-confidential

Returns

The corresponding TLS-1.2 PRF algorithm. For example, PSA_ALG_TLS12_PRF(PSA_ALG_SHA_256) represents

the TLS 1.2 PRF using HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

Description

TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in The Transport Layer

Security (TLS) Protocol Version 1.2 [RFC5246] §5. It is based on HMAC and can be used with either

SHA-256 or SHA-384.

This key derivation algorithm uses the following inputs, which must be passed in the order given here:

∙ PSA_KEY_DERIVATION_INPUT_SEED is the seed.

∙ PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.

∙ PSA_KEY_DERIVATION_INPUT_LABEL is the label.

Each input may only be passed once.

For the application to TLS-1.2 key expansion:

∙ The seed is the concatenation of ServerHello.Random + ClientHello.Random.

∙ The label is "key expansion".

Compatible key types

PSA_KEY_TYPE_DERIVE (for the secret key)

PSA_KEY_TYPE_RAW_DATA (for the other inputs)

PSA_ALG_TLS12_PSK_TO_MS (macro)

Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm.

#define PSA_ALG_TLS12_PSK_TO_MS(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 TLS-1.2 PSK to MS algorithm. For example, PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA_256)

represents the TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

IHI 0086

Page 210

1.1.2

Non-confidential

Description

In a pure-PSK handshake in TLS 1.2, the master secret (MS) is derived from the pre-shared key (PSK)

through the application of padding (Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) [RFC4279]

§2) and the TLS-1.2 PRF (The Transport Layer Security (TLS) Protocol Version 1.2 [RFC5246] §5). The latter is

based on HMAC and can be used with either SHA-256 or SHA-384.

This key derivation algorithm uses the following inputs, which must be passed in the order given here:

∙ PSA_KEY_DERIVATION_INPUT_SEED is the seed.

∙ PSA_KEY_DERIVATION_INPUT_OTHER_SECRET is the other secret for the computation of the premaster

secret. This input is optional; if omitted, it defaults to a string of null bytes with the same length as

the secret (PSK) input.

∙ PSA_KEY_DERIVATION_INPUT_SECRET is the PSK. The PSK must not be larger than

PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE.

∙ PSA_KEY_DERIVATION_INPUT_LABEL is the label.

Each input may only be passed once.

For the application to TLS-1.2:

∙ The seed, which is forwarded to the TLS-1.2 PRF, is the concatenation of the ClientHello.Random +

ServerHello.Random.

∙ The other secret depends on the key exchange specified in the cipher suite: * For a plain PSK cipher

suite ([RFC4279] §2), omit PSA_KEY_DERIVATION_INPUT_OTHER_SECRET. * For a DHE-PSK ([RFC4279] §3)

or ECDHE-PSK cipher suite (ECDHE_PSK Cipher Suites for Transport Layer Security (TLS) [RFC5489]

§2), the other secret should be the output of the PSA_ALG_FFDH or PSA_ALG_ECDH key agreement

performed with the peer. The recommended way to pass this input is to use a key derivation

algorithm constructed as PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg)) and to

call psa_key_derivation_key_agreement(). Alternatively, this input may be an output of

psa_raw_key_agreement() passed with psa_key_derivation_input_bytes(), or an equivalent input

passed with psa_key_derivation_input_bytes() or psa_key_derivation_input_key(). * For a RSA-PSK

cipher suite ([RFC4279] §4), the other secret should be the 48-byte client challenge (the

PreMasterSecret of [RFC5246] §7.4.7.1) concatenation of the TLS version and a 46-byte random

string chosen by the client. On the server, this is typically an output of psa_asymmetric_decrypt()

using PSA_ALG_RSA_PKCS1V15_CRYPT, passed to the key derivation operation with

psa_key_derivation_input_bytes().

∙ The label is "master secret" or "extended master secret".

IHI 0086

Page 211

1.1.2

Non-confidential

Compatible key types

PSA_KEY_TYPE_DERIVE (for the PSK)

PSA_KEY_TYPE_RAW_DATA (for the other inputs)

PSA_ALG_PBKDF2_HMAC (macro)

Macro to build a PBKDF2-HMAC password-hashing or key-stretching algorithm.

#define PSA_ALG_PBKDF2_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 PBKDF2-HMAC-XXX algorithm. For example, PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256) is

the algorithm identifier for PBKDF2-HMAC-SHA-256.

Unspecified if hash_alg is not a supported hash algorithm.

Description

PBKDF2 is specified by PKCS #5: Password-Based Cryptography Specification Version 2.1 [RFC8018] §5.2.

This macro constructs a PBKDF2 algorithm that uses a pseudo-random function based on HMAC with the

specified hash.

This key derivation algorithm uses the following inputs, which must be provided in the following order:

∙ PSA_KEY_DERIVATION_INPUT_COST is the iteration count. This input step must be used exactly once.

∙ PSA_KEY_DERIVATION_INPUT_SALT is the salt. This input step must be used one or more times; if used

several times, the inputs will be concatenated. This can be used to build the final salt from multiple

sources, both public and secret (also known as pepper).

∙ PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed. This input step must be used

exactly once.

Compatible key types

PSA_KEY_TYPE_DERIVE (for password input)

PSA_KEY_TYPE_PASSWORD (for password input)

PSA_KEY_TYPE_PEPPER (for salt input)

PSA_KEY_TYPE_RAW_DATA (for salt input)

PSA_KEY_TYPE_PASSWORD_HASH (for key verification)

IHI 0086

Page 212

1.1.2

Non-confidential

PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (macro)

The PBKDF2-AES-CMAC-PRF-128 password-hashing or key-stretching algorithm.

#define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200)

PBKDF2 is specified by PKCS #5: Password-Based Cryptography Specification Version 2.1 [RFC8018] §5.2.

This algorithm specifies the PBKDF2 algorithm using the AES-CMAC-PRF-128 pseudo-random function

specified by [RFC4615]

This key derivation algorithm uses the same inputs as PSA_ALG_PBKDF2_HMAC() with the same constraints.

Compatible key types

PSA_KEY_TYPE_DERIVE (for password input)

PSA_KEY_TYPE_PASSWORD (for password input)

PSA_KEY_TYPE_PEPPER (for salt input)

PSA_KEY_TYPE_RAW_DATA (for salt input)

PSA_KEY_TYPE_PASSWORD_HASH (for key verification)

10.6.2 Input step types

psa_key_derivation_step_t (typedef)

Encoding of the step of a key derivation.

typedef uint16_t psa_key_derivation_step_t;

PSA_KEY_DERIVATION_INPUT_SECRET (macro)

A high-entropy secret input for key derivation.

#define PSA_KEY_DERIVATION_INPUT_SECRET /* implementation-defined value */

This is typically a key of type PSA_KEY_TYPE_DERIVE passed to psa_key_derivation_input_key(), or the shared

secret resulting from a key agreement obtained via psa_key_derivation_key_agreement().

The secret can also be a direct input passed to psa_key_derivation_input_bytes(). In this case, the

derivation operation cannot be used to derive keys: the operation will not permit a call to

psa_key_derivation_output_key().

PSA_KEY_DERIVATION_INPUT_OTHER_SECRET (macro)

A high-entropy additional secret input for key derivation.

#define PSA_KEY_DERIVATION_INPUT_OTHER_SECRET \

/* implementation-defined value */

This is typically the shared secret resulting from a key agreement obtained via

psa_key_derivation_key_agreement(). It may alternatively be a key of type PSA_KEY_TYPE_DERIVE passed to

psa_key_derivation_input_key(), or a direct input passed to psa_key_derivation_input_bytes().

IHI 0086

Page 213

1.1.2

Non-confidential

PSA_KEY_DERIVATION_INPUT_PASSWORD (macro)

A low-entropy secret input for password hashing or key stretching.

#define PSA_KEY_DERIVATION_INPUT_PASSWORD /* implementation-defined value */

This is usually a key of type PSA_KEY_TYPE_PASSWORD passed to psa_key_derivation_input_key() or a direct

input passed to psa_key_derivation_input_bytes() that is a password or passphrase. It can also be

high-entropy secret, for example, a key of type PSA_KEY_TYPE_DERIVE, or the shared secret resulting from a

key agreement.

If the secret is a direct input, the derivation operation cannot be used to derive keys: the operation will not

permit a call to psa_key_derivation_output_key().

PSA_KEY_DERIVATION_INPUT_LABEL (macro)

A label for key derivation.

#define PSA_KEY_DERIVATION_INPUT_LABEL /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_CONTEXT (macro)

A context for key derivation.

#define PSA_KEY_DERIVATION_INPUT_CONTEXT /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_SALT (macro)

A salt for key derivation.

#define PSA_KEY_DERIVATION_INPUT_SALT /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA or PSA_KEY_TYPE_PEPPER.

PSA_KEY_DERIVATION_INPUT_INFO (macro)

An information string for key derivation.

#define PSA_KEY_DERIVATION_INPUT_INFO /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

IHI 0086

Page 214

1.1.2

Non-confidential

PSA_KEY_DERIVATION_INPUT_SEED (macro)

A seed for key derivation.

#define PSA_KEY_DERIVATION_INPUT_SEED /* implementation-defined value */

This is typically a direct input. It can also be a key of type PSA_KEY_TYPE_RAW_DATA.

PSA_KEY_DERIVATION_INPUT_COST (macro)

A cost parameter for password hashing or key stretching.

#define PSA_KEY_DERIVATION_INPUT_COST /* implementation-defined value */

This must be a direct input, passed to psa_key_derivation_input_integer().

10.6.3 Key derivation functions

psa_key_derivation_operation_t (typedef)

The type of the state object for key derivation operations.

typedef /* implementation-defined type */ psa_key_derivation_operation_t;

Before calling any function on a key derivation operation object, the application must initialize it by any of

the following means:

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

psa_key_derivation_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_key_derivation_operation_t operation;

∙ Initialize the object to the initializer PSA_KEY_DERIVATION_OPERATION_INIT, for example:

psa_key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;

∙ Assign the result of the function psa_key_derivation_operation_init() to the object, for example:

psa_key_derivation_operation_t operation;

operation = psa_key_derivation_operation_init();

This is an implementation-defined type. Applications that make assumptions about the content of this

object will result in in implementation-specific behavior, and are non-portable.

IHI 0086

Page 215

1.1.2

Non-confidential

PSA_KEY_DERIVATION_OPERATION_INIT (macro)

This macro returns a suitable initializer for a key derivation operation object of type

psa_key_derivation_operation_t.

#define PSA_KEY_DERIVATION_OPERATION_INIT /* implementation-defined value */

psa_key_derivation_operation_init (function)

Return an initial value for a key derivation operation object.

psa_key_derivation_operation_t psa_key_derivation_operation_init(void);

Returns: psa_key_derivation_operation_t

psa_key_derivation_setup (function)

Set up a key derivation operation.

psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t * operation,

psa_algorithm_t alg);

Parameters

operation

The key derivation operation object to set up. It must have been

initialized but not set up yet.

alg

The algorithm to compute. This must be one of the following:

∙ A key derivation algorithm: a value of type psa_algorithm_t such

that PSA_ALG_IS_KEY_DERIVATION(alg) is true.

∙ A key agreement and derivation algorithm: a value of type

psa_algorithm_t such that PSA_ALG_IS_KEY_AGREEMENT(alg) is true

and PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) is false.

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_ARGUMENT

alg is neither a key derivation algorithm, nor a key agreement and

derivation algorithm.

PSA_ERROR_NOT_SUPPORTED

alg is not supported or is not a key derivation algorithm, or a key

agreement and derivation algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

IHI 0086

Page 216

1.1.2

Non-confidential

Description

A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic

way. This byte stream can be used to produce keys and other cryptographic material.

A key agreement and derivation algorithm uses a key agreement protocol to provide a shared secret which

is used for the key derivation. See psa_key_derivation_key_agreement().

The sequence of operations to derive a key is as follows:

1. Allocate a key derivation 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_key_derivation_operation_t, e.g. PSA_KEY_DERIVATION_OPERATION_INIT.

3. Call psa_key_derivation_setup() to specify the algorithm.

4. Provide the inputs for the key derivation by calling psa_key_derivation_input_bytes() or

psa_key_derivation_input_key() as appropriate. Which inputs are needed, in what order, whether

keys are permitted, and what type of keys depends on the algorithm.

5. Optionally set the operation’s maximum capacity with psa_key_derivation_set_capacity(). This can

be done before, in the middle of, or after providing inputs. For some algorithms, this step is

mandatory because the output depends on the maximum capacity.

6. To derive a key, call psa_key_derivation_output_key(). To derive a byte string for a different purpose,

call psa_key_derivation_output_bytes(). Successive calls to these functions use successive output

bytes calculated by the key derivation algorithm.

7. Clean up the key derivation operation object with psa_key_derivation_abort().

After a successful call to psa_key_derivation_setup(), the operation is active, and the application must

eventually terminate the operation with a call to psa_key_derivation_abort().

If psa_key_derivation_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_key_derivation_abort().

See Multi-part operations on page 24.

psa_key_derivation_get_capacity (function)

Retrieve the current capacity of a key derivation operation.

psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t * operation,

size_t * capacity);

Parameters

operation

The operation to query.

capacity

On success, the capacity of the operation.

IHI 0086

Page 217

1.1.2

Non-confidential

Returns: psa_status_t

PSA_SUCCESS

Success. The maximum number of bytes that this key derivation can

return is (*capacity).

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_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The capacity of a key derivation is the maximum number of bytes that it can return. Reading N bytes of

output from a key derivation operation reduces its capacity by at least N. The capacity can be reduced by

more than N in the following situations:

∙ Calling psa_key_derivation_output_key() can reduce the capacity by more than the key size,

depending on the type of key being generated. See psa_key_derivation_output_key() for details of

the key derivation process.

∙ When the psa_key_derivation_operation_t object is operating as a deterministic random bit

generator (DBRG), which reduces capacity in whole blocks, even when less than a block is read.

psa_key_derivation_set_capacity (function)

Set the maximum capacity of a key derivation operation.

psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t * operation,

size_t capacity);

Parameters

operation

The key derivation operation object to modify.

capacity

The new capacity of the operation. It must be less or equal to the

operation’s current capacity.

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

capacity is larger than the operation’s current capacity. In this case,

the operation object remains valid and its capacity remains

unchanged.

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

IHI 0086

Page 218

1.1.2

Non-confidential

Description

The capacity of a key derivation operation is the maximum number of bytes that the key derivation

operation can return from this point onwards.

psa_key_derivation_input_bytes (function)

Provide an input for key derivation or key agreement.

psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t * operation,

psa_key_derivation_step_t step,

const uint8_t * data,

size_t data_length);

Parameters

operation

The key derivation operation object to use. It must have been set up

with psa_key_derivation_setup() and must not have produced any

output yet.

step

Which step the input data is for.

data

Input data to use.

data_length

Size of the data 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 for this input step. This can

happen if the application provides a step out of order or repeats

a step that may not be repeated.

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

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

∙ step is not compatible with the operation’s algorithm.

∙ step does not permit direct inputs.

∙ data_length is too small or too large for step in this particular

algorithm.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ step is not supported with the operation’s algorithm.

∙ data_length is is not supported for step in this particular

algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

IHI 0086

Page 219

1.1.2

Non-confidential

PSA_ERROR_DATA_INVALID

Description

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of

each key derivation or key agreement algorithm for information.

This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input,

which is normally in a key object, call psa_key_derivation_input_key() instead of this function. Refer to the

documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type

psa_key_derivation_step_t) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling

psa_key_derivation_abort().

psa_key_derivation_input_integer (function)

Provide a numeric input for key derivation or key agreement.

psa_status_t psa_key_derivation_input_integer(psa_key_derivation_operation_t * operation,

psa_key_derivation_step_t step,

uint64_t value);

Parameters

operation

The key derivation operation object to use. It must have been set up

with psa_key_derivation_setup() and must not have produced any

output yet.

step

Which step the input data is for.

value

The value of the numeric input.

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 for this input step. This can

happen if the application provides a step out of order or repeats

a step that may not be repeated.

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

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

∙ step is not compatible with the operation’s algorithm.

∙ step does not permit numerical inputs.

∙ value is not valid for step in the operation’s algorithm.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ step is not supported with the operation’s algorithm.

∙ value is not supported for step in the operation’s algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

IHI 0086

Page 220

1.1.2

Non-confidential

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

Which inputs are required and in what order depends on the algorithm. However, when an algorithm

requires a particular order, numeric inputs usually come first as they tend to be configuration parameters.

Refer to the documentation of each key derivation or key agreement algorithm for information.

This function is used for inputs which are fixed-size non-negative integers.

If this function returns an error status, the operation enters an error state and must be aborted by calling

psa_key_derivation_abort().

psa_key_derivation_input_key (function)

Provide an input for key derivation in the form of a key.

psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t * operation,

psa_key_derivation_step_t step,

psa_key_id_t key);

Parameters

operation

The key derivation operation object to use. It must have been set up

with psa_key_derivation_setup() and must not have produced any

output yet.

step

Which step the input data is for.

key

Identifier of the key. The key must have an appropriate type for step,

it must permit the usage PSA_KEY_USAGE_DERIVE or

PSA_KEY_USAGE_VERIFY_DERIVATION (see note), and it must permit the

algorithm used by the operation.

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 for this input step. This can

happen if the application provides a step out of order or repeats

a step that may not be repeated.

∙ 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 has neither the PSA_KEY_USAGE_DERIVE nor the

PSA_KEY_USAGE_VERIFY_DERIVATION usage flag, or it does not permit the

operation’s algorithm.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

IHI 0086

Page 221

1.1.2

Non-confidential

∙ step is not compatible with the operation’s algorithm.

∙ step does not permit key inputs of the given type, or does not

permit key inputs at all.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ step is not supported with the operation’s algorithm.

∙ Key inputs of the given type are not supported for step in the

operation’s algorithm.

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

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of

each key derivation or key agreement algorithm for information.

This function obtains input from a key object, which is usually correct for secret inputs or for non-secret

personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store,

call psa_key_derivation_input_bytes() instead of this function. Refer to the documentation of individual

step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

Note:

Once all inputs steps are completed, the following operations are permitted:

∙ psa_key_derivation_output_bytes() - if each input was either a direct input or a key with usage

flag PSA_KEY_USAGE_DERIVE.

∙ psa_key_derivation_output_key() - if the input for step PSA_KEY_DERIVATION_INPUT_SECRET or

PSA_KEY_DERIVATION_INPUT_PASSWORD was a key with usage flag PSA_KEY_USAGE_DERIVE, and every

other input was either a direct input or a key with usage flag PSA_KEY_USAGE_DERIVE.

∙ psa_key_derivation_verify_bytes() - if each input was either a direct input or a key with usage

flag PSA_KEY_USAGE_VERIFY_DERIVATION.

∙ psa_key_derivation_verify_key() - under the same conditions as

psa_key_derivation_verify_bytes().

If this function returns an error status, the operation enters an error state and must be aborted by calling

psa_key_derivation_abort().

IHI 0086

Page 222

1.1.2

Non-confidential

psa_key_derivation_output_bytes (function)

Read some data from a key derivation operation.

psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t * operation,

uint8_t * output,

size_t output_length);

Parameters

operation

The key derivation operation object to read from.

output

Buffer where the output will be written.

output_length

Number of bytes to output.

Returns: psa_status_t

PSA_SUCCESS

Success. The first output_length bytes of output contain the derived

data.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

∙ The operation state is not valid: it must be active, with all

required input steps complete.

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

PSA_ERROR_NOT_PERMITTED

One of the inputs was a key whose policy did not permit

PSA_KEY_USAGE_DERIVE.

PSA_ERROR_INSUFFICIENT_DATA

The operation’s capacity was less than output_length bytes. In this

case, the following occurs:

∙ No output is written to the output buffer.

∙ The operation’s capacity is set to zero - subsequent calls to this

function will not succeed, even with a smaller output buffer.

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 calculates output bytes from a key derivation algorithm and returns those bytes. If the key

derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes

from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes

read.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an

error state and must be aborted by calling psa_key_derivation_abort().

IHI 0086

Page 223

1.1.2

Non-confidential

psa_key_derivation_output_key (function)

Derive a key from an ongoing key derivation operation.

psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t * attributes,

psa_key_derivation_operation_t * operation,

psa_key_id_t * key);

Parameters

attributes

The attributes for the new key. This function uses the attributes as

follows:

∙ The key type is required. It cannot be an asymmetric public key.

∙ The key size is required. It must be a valid size for the key type.

∙ The key permitted-algorithm policy is required for keys that will

be used for a cryptographic operation, see Permitted algorithms

on page 83.

If the key type to be created is PSA_KEY_TYPE_PASSWORD_HASH, then

the permitted-algorithm policy must be the same as the current

operation’s algorithm.

∙ The key usage flags define what operations are permitted with

the key, see Key usage flags on page 85.

∙ The key lifetime and identifier are required for a persistent key.

Note:

This is an input parameter: it is not updated with the final key

attributes. The final attributes of the new key can be queried

by calling psa_get_key_attributes() with the key’s identifier.

operation

The key derivation operation object to read from.

key

On success, an identifier for the newly created key. PSA_KEY_ID_NULL

on failure.

Returns: psa_status_t

PSA_SUCCESS

Success. If the key is persistent, the key material and the key’s

metadata have been saved to persistent storage.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

∙ The operation state is not valid: it must be active, with all

required input steps complete.

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

PSA_ERROR_NOT_PERMITTED

The following conditions can result in this error:

∙ The PSA_KEY_DERIVATION_INPUT_SECRET input step was neither

provided through a key, nor the result of a key agreement.

∙ One of the inputs was a key whose policy did not permit

PSA_KEY_USAGE_DERIVE.

IHI 0086

Page 224

1.1.2

Non-confidential

∙ The implementation does not permit creating a key with the

specified attributes due to some implementation-specific policy.

PSA_ERROR_ALREADY_EXISTS

This is an attempt to create a persistent key, and there is already a

persistent key with the given identifier.

PSA_ERROR_INSUFFICIENT_DATA

There was not enough data to create the desired key. In this case, the

following occurs:

∙ No key is generated.

∙ The operation’s capacity is set to zero - subsequent calls to this

function will not succeed, even if they require less data.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

∙ The key type is invalid, or is an asymmetric public key type.

∙ The key type is PSA_KEY_TYPE_PASSWORD_HASH, and the

permitted-algorithm policy is not the same as the current

operation’s algorithm.

∙ The key size is not valid for the key type. Implementations must

reject an attempt to derive a key of size 0.

∙ The key lifetime is invalid.

∙ The key identifier is not valid for the key lifetime.

∙ The key usage flags include invalid values.

∙ The key’s permitted-usage algorithm is invalid.

∙ The key attributes, as a whole, are invalid.

PSA_ERROR_NOT_SUPPORTED

The key attributes, as a whole, are not supported, either by the

implementation in general or in the specified storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a

key deterministically. The key’s location, policy, type and size are taken from attributes.

If the key derivation’s output is viewed as a stream of bytes, this function consumes the required number of

bytes from the stream. The operation’s capacity decreases by the number of bytes used to derive the key.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an

error state and must be aborted by calling psa_key_derivation_abort().

How much output is produced and consumed from the operation, and how the key is derived, depends on

the key type. Table 9 on page 226 describes the required key derivation procedures for standard key

derivation algorithms. Implementations can use other methods for implementation-specific algorithms.

IHI 0086

Page 225

1.1.2

Non-confidential

In all cases, the data that is read is discarded from the operation. The operation’s capacity is decreased by

the number of bytes read.

Table 9 Standard key derivation process

Key type

Key type details and derivation procedure

AES

PSA_KEY_TYPE_AES

ARC4

PSA_KEY_TYPE_ARC4

ARIA

PSA_KEY_TYPE_ARIA

CAMELLIA

PSA_KEY_TYPE_CAMELLIA

ChaCha20

PSA_KEY_TYPE_CHACHA20

SM4

PSA_KEY_TYPE_SM4

Secrets for derivation

PSA_KEY_TYPE_DERIVE

HMAC

PSA_KEY_TYPE_HMAC

Password hashes

PSA_KEY_TYPE_PASSWORD_HASH

For key types for which the key is an arbitrary sequence of bytes of a

given size, this function is functionally equivalent to calling

psa_key_derivation_output_bytes() and passing the resulting output to

psa_import_key(). However, this function has a security benefit: if the

implementation provides an isolation boundary then the key material is

not exposed outside the isolation boundary. As a consequence, for these

key types, this function always consumes exactly (bits/8) bytes from the

operation.

DES

PSA_KEY_TYPE_DES, 64 bits.

This function generates a key using the following process:

1. Draw an 8-byte string.

2. Set/clear the parity bits in each byte.

3. If the result is a forbidden weak key, discard the result and return to

step 1.

4. Output the string.

2-key 3DES

PSA_KEY_TYPE_DES, 192 bits.

3-key 3DES

PSA_KEY_TYPE_DES, 128 bits.

The two or three keys are generated by repeated application of the

process used to generate a DES key.

For example, for 3-key 3DES, if the first 8 bytes specify a weak key and

the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as

the first key, and continue reading output from the operation to derive

the other two keys.

continues on next page

IHI 0086

Page 226

1.1.2

Non-confidential

Table 9 - continued from previous page

Key type

Key type details and derivation procedure

Finite-field Diffie-Hellman

PSA_KEY_TYPE_DH_KEY_PAIR(dh_family) where dh_family designates any

keys

Diffie-Hellman family.

ECC keys on a Weierstrass

PSA_KEY_TYPE_ECC_KEY_PAIR(ecc_family) where ecc_family designates a

elliptic curve

Weierstrass curve family.

These key types require the generation of a private key which is an

integer in the range [1, N - 1], where N is the boundary of the private key

domain: N is the prime p for Diffie-Hellman, or the order of the curve’s

base point for ECC.

Let m be the bit size of N, such that 2^m > N >= 2^(m-1). This function

generates the private key using the following process:

1. Draw a byte string of length ceiling(m/8) bytes.

2. If m is not a multiple of 8, set the most significant (8 * ceiling(m/8)

- m) bits of the first byte in the string to zero.

3. Convert the string to integer k by decoding it as a big-endian byte

string.

4. If k > N - 2, discard the result and return to step 1.

5. Output k + 1 as the private key.

This method allows compliance to NIST standards, specifically the

methods titled Key-Pair Generation by Testing Candidates in the following

publications:

∙ NIST Special Publication 800-56A: Recommendation for Pair-Wise

Key-Establishment Schemes Using Discrete Logarithm Cryptography

[SP800-56A] §5.6.1.1.4 for Diffie-Hellman keys.

∙ [SP800-56A] §5.6.1.2.2 or FIPS Publication 186-4: Digital Signature

Standard (DSS) [FIPS186-4] §B.4.2 for elliptic curve keys.

ECC keys on a Montgomery

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_MONTGOMERY)

elliptic curve

This function always draws a byte string whose length is determined by

the curve, and sets the mandatory bits accordingly. That is:

∙ Curve25519 (PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte

string and process it as specified in Elliptic Curves for Security

[RFC7748] §5.

∙ Curve448 (PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte

string and process it as specified in [RFC7748] §5.

Other key types

This includes PSA_KEY_TYPE_RSA_KEY_PAIR.

The way in which the operation output is consumed is

implementation-defined.

IHI 0086

Page 227

1.1.2

Non-confidential

For algorithms that take an input step PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be

provided with psa_key_derivation_input_key(). Future versions of this specification might include

additional restrictions on the derived key based on the attributes and strength of the secret key.

psa_key_derivation_verify_bytes (function)

Compare output data from a key derivation operation to an expected value.

psa_status_t psa_key_derivation_verify_bytes(psa_key_derivation_operation_t * operation,

const uint8_t *expected_output,

size_t output_length);

Parameters

operation

The key derivation operation object to read from.

expected_output

Buffer containing the expected derivation output.

output_length

Length ot the expected output. This is also the number of bytes that

will be read.

Returns: psa_status_t

PSA_SUCCESS

Success. The output of the key derivation operation matches

expected_output.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

∙ The operation state is not valid: it must be active, with all

required input steps complete.

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

PSA_ERROR_NOT_PERMITTED

One of the inputs is a key whose policy does not permit

PSA_KEY_USAGE_VERIFY_DERIVATION.

PSA_ERROR_INVALID_SIGNATURE

The output of the key derivation operation does not match the value

in expected_output.

PSA_ERROR_INSUFFICIENT_DATA

The operation’s capacity was less than output_length bytes. In this

case, the operation’s capacity is set to zero - subsequent calls to this

function will not succeed, even with a smaller expected output

length.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

IHI 0086

Page 228

1.1.2

Non-confidential

Description

This function calculates output bytes from a key derivation algorithm and compares those bytes to an

expected value. If the key derivation’s output is viewed as a stream of bytes, this function destructively

reads output_length bytes from the stream before comparing them with expected_output. The operation’s

capacity decreases by the number of bytes read.

This is functionally equivalent to the following code:

uint8_t tmp[output_length];

psa_key_derivation_output_bytes(operation, tmp, output_length);

if (memcmp(expected_output, tmp, output_length) != 0)

return PSA_ERROR_INVALID_SIGNATURE;

However, calling psa_key_derivation_verify_bytes() works even if the key’s policy does not permit output

of the bytes.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or

PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling

psa_key_derivation_abort().

Note:

Implementations must make the best effort to ensure that the comparison between the actual key

derivation output and the expected output is performed in constant time.

psa_key_derivation_verify_key (function)

Compare output data from a key derivation operation to an expected value stored in a key.

psa_status_t psa_key_derivation_verify_key(psa_key_derivation_operation_t * operation,

psa_key_id_t expected);

Parameters

operation

The key derivation operation object to read from.

expected

A key of type PSA_KEY_TYPE_PASSWORD_HASH containing the expected

output. The key must permit the usage

PSA_KEY_USAGE_VERIFY_DERIVATION, and the permitted algorithm must

match the operation’s algorithm.

The value of this key is typically computed by a previous call to

psa_key_derivation_output_key().

IHI 0086

Page 229

1.1.2

Non-confidential

Returns: psa_status_t

PSA_SUCCESS

Success. The output of the key derivation operation matches the

expected key value.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

∙ The operation state is not valid: it must be active, with all

required input steps complete.

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

PSA_ERROR_INVALID_HANDLE

expected is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

The following conditions can result in this error:

∙ The key does not have the PSA_KEY_USAGE_VERIFY_DERIVATION flag,

or it does not permit the requested algorithm.

∙ One of the inputs is a key whose policy does not permit

PSA_KEY_USAGE_VERIFY_DERIVATION.

PSA_ERROR_INVALID_SIGNATURE

The output of the key derivation operation does not match the value

of the expected key.

PSA_ERROR_INSUFFICIENT_DATA

The operation’s capacity was less than the length of the expected key.

In this case, the operation’s capacity is set to zero - subsequent calls

to this function will not succeed, even with a smaller expected key

length.

PSA_ERROR_INVALID_ARGUMENT

The key type is not PSA_KEY_TYPE_PASSWORD_HASH.

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 calculates output bytes from a key derivation algorithm and compares those bytes to an

expected value, provided as key of type PSA_KEY_TYPE_PASSWORD_HASH. If the key derivation’s output is

viewed as a stream of bytes, this function destructively reads the number of bytes corresponding to the

length of the expected key from the stream before comparing them with the key value. The operation’s

capacity decreases by the number of bytes read.

This is functionally equivalent to exporting the expected key and calling psa_key_derivation_verify_bytes()

on the result, except that it works when the key cannot be exported.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or

PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling

psa_key_derivation_abort().

Note:

Implementations must make the best effort to ensure that the comparison between the actual key

IHI 0086

Page 230

1.1.2

Non-confidential

derivation output and the expected output is performed in constant time.

psa_key_derivation_abort (function)

Abort a key derivation operation.

psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t * operation);

Parameters

operation

The operation to abort.

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

This function can be called at any time after the operation object has been initialized as described in

psa_key_derivation_operation_t.

In particular, it is valid to call psa_key_derivation_abort() twice, or to call psa_key_derivation_abort() on an

operation that has not been set up.

10.6.4 Support macros

PSA_ALG_IS_KEY_DERIVATION_STRETCHING (macro)

Whether the specified algorithm is a key-stretching or password-hashing algorithm.

#define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \

/* specification-defined value */

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a key-stretching or password-hashing algorithm, 0 otherwise. This macro can return either 0 or 1

if alg is not a supported key derivation algorithm algorithm identifier.

IHI 0086

Page 231

1.1.2

Non-confidential

Description

A key-stretching or password-hashing algorithm is a key derivation algorithm that is suitable for use with a

low-entropy secret such as a password. Equivalently, it’s a key derivation algorithm that uses a

PSA_KEY_DERIVATION_INPUT_PASSWORD input step.

PSA_ALG_IS_HKDF (macro)

Whether the specified algorithm is an HKDF algorithm (PSA_ALG_HKDF(hash_alg)).

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

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

derivation algorithm identifier.

Description

HKDF is a family of key derivation algorithms that are based on a hash function and the HMAC

construction.

PSA_ALG_IS_HKDF_EXTRACT (macro)

Whether the specified algorithm is an HKDF-Extract algorithm (PSA_ALG_HKDF_EXTRACT(hash_alg)).

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an HKDF-Extract algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a

supported key derivation algorithm identifier.

PSA_ALG_IS_HKDF_EXPAND (macro)

Whether the specified algorithm is an HKDF-Expand algorithm (PSA_ALG_HKDF_EXPAND(hash_alg)).

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

IHI 0086

Page 232

1.1.2

Non-confidential

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an HKDF-Expand algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a

supported key derivation algorithm identifier.

PSA_ALG_IS_TLS12_PRF (macro)

Whether the specified algorithm is a TLS-1.2 PRF algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a TLS-1.2 PRF algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a supported

key derivation algorithm identifier.

PSA_ALG_IS_TLS12_PSK_TO_MS (macro)

Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a TLS-1.2 PSK to MS algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a

supported key derivation algorithm identifier.

PSA_ALG_IS_PBKDF2_HMAC (macro)

Whether the specified algorithm is a PBKDF2-HMAC algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

IHI 0086

Page 233

1.1.2

Non-confidential

Returns

1 if alg is a PBKDF2-HMAC algorithm, 0 otherwise. This macro can return either 0 or 1 if alg is not a

supported key derivation algorithm identifier.

PSA_KEY_DERIVATION_UNLIMITED_CAPACITY (macro)

Use the maximum possible capacity for a key derivation operation.

#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY \

/* implementation-defined value */

Use this value as the capacity argument when setting up a key derivation to specify that the operation will

use the maximum possible capacity. The value of the maximum possible capacity depends on the key

derivation algorithm.

PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE (macro)

This macro returns the maximum supported length of the PSK for the TLS-1.2 PSK-to-MS key derivation.

#define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */

This implementation-defined value specifies the maximum length for the PSK input used with a

PSA_ALG_TLS12_PSK_TO_MS() key agreement algorithm.

Quoting Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) [RFC4279] §5.3:

TLS implementations supporting these cipher suites MUST support arbitrary PSK identities up

to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer

identities and keys is RECOMMENDED.

Therefore, it is recommended that implementations define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE with a value

greater than or equal to 64.

10.7 Asymmetric signature

There are two pairs of single-part functions for asymmetric signature:

∙ The signature and verification functions psa_sign_message() and psa_verify_message() take a message

as one of their inputs and perform a hash-and-sign algorithm.

∙ The functions psa_sign_hash() and psa_verify_hash() take a message hash as one of their inputs. This

is useful for signing pre-computed hashes, or for implementing hash-and-sign using a multi-part hash

operation before signing the resulting hash. To determine which hash algorithm to use, call the macro

PSA_ALG_GET_HASH() on the corresponding signature algorithm.

Some hash-and-sign algorithms add padding to the message hash before completing the signing

operation. The format of the padding that is used depends on the algorithm used to construct the

signature, see the description of the specific algorithm for details.

IHI 0086

Page 234

1.1.2

Non-confidential

10.7.1 Asymmetric signature algorithms

PSA_ALG_RSA_PKCS1V15_SIGN (macro)

The RSA PKCS#1 v1.5 message signature scheme, with hashing.

#define PSA_ALG_RSA_PKCS1V15_SIGN(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. This includes PSA_ALG_ANY_HASH

when specifying the algorithm in a key policy.

Returns

The corresponding RSA PKCS#1 v1.5 signature algorithm.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §8.2

under the name RSASSA-PKCS1-v1_5.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is used as H from step

2 onwards in the message encoding algorithm EMSA-PKCS1-V1_5-ENCODE() in [RFC8017] §9.2. H is the

message digest, computed using the hash_alg hash algorithm.

Compatible key types

PSA_KEY_TYPE_RSA_KEY_PAIR

PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

PSA_ALG_RSA_PKCS1V15_SIGN_RAW (macro)

The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.

#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW ((psa_algorithm_t) 0x06000200)

This algorithm can be only used with the psa_sign_hash() and psa_verify_hash() functions.

This signature scheme is defined by PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] §8.2

under the name RSASSA-PKCS1-v1_5.

The hash parameter to psa_sign_hash() or psa_verify_hash() is used as T from step 3 onwards in the

message encoding algorithm EMSA-PKCS1-V1_5-ENCODE() in [RFC8017] §9.2. T is normally the DER encoding

of the DigestInfo structure produced by step 2 in the message encoding algorithm, but it can be any byte

string within the available length.

The wildcard key policy PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH) also permits a key to be used with

the PSA_ALG_RSA_PKCS1V15_SIGN_RAW signature algorithm.

IHI 0086

Page 235

1.1.2

Non-confidential

Compatible key types

PSA_KEY_TYPE_RSA_KEY_PAIR

PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

PSA_ALG_RSA_PSS (macro)

The RSA PSS message signature scheme, with hashing.

#define PSA_ALG_RSA_PSS(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. This includes PSA_ALG_ANY_HASH

when specifying the algorithm in a key policy.

Returns

The corresponding RSA PSS signature algorithm.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

This algorithm is randomized: each invocation returns a different, equally valid signature.

This is the signature scheme defined by [RFC8017] §8.1 under the name RSASSA-PSS, with the following

options:

∙ The mask generation function is MGF1 defined by [RFC8017] Appendix B.

∙ When creating a signature, the salt length is equal to the length of the hash, or the largest possible

salt length for the algorithm and key size if that is smaller than the hash length.

∙ When verifying a signature, the salt length must be equal to the length of the hash, or the largest

possible salt length for the algorithm and key size if that is smaller than the hash length.

∙ The specified hash algorithm, hash_alg, is used to hash the input message, to create the salted hash,

and for the mask generation.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest,

computed using the hash_alg hash algorithm.

Note:

The PSA_ALG_RSA_PSS_ANY_SALT() algorithm is equivalent to PSA_ALG_RSA_PSS() when creating a

signature, but permits any salt length when verifying a signature.

IHI 0086

Page 236

1.1.2

Non-confidential

Compatible key types

PSA_KEY_TYPE_RSA_KEY_PAIR

PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

PSA_ALG_RSA_PSS_ANY_SALT (macro)

The RSA PSS message signature scheme, with hashing. This variant permits any salt length for signature

verification.

#define PSA_ALG_RSA_PSS_ANY_SALT(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. This includes PSA_ALG_ANY_HASH

when specifying the algorithm in a key policy.

Returns

The corresponding RSA PSS signature algorithm.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

This algorithm is randomized: each invocation returns a different, equally valid signature.

This is the signature scheme defined by [RFC8017] §8.1 under the name RSASSA-PSS, with the following

options:

∙ The mask generation function is MGF1 defined by [RFC8017] Appendix B.

∙ When creating a signature, the salt length is equal to the length of the hash, or the largest possible

salt length for the algorithm and key size if that is smaller than the hash length.

∙ When verifying a signature, any salt length permitted by the RSASSA-PSS signature algorithm is

accepted.

∙ The specified hash algorithm, hash_alg, is used to hash the input message, to create the salted hash,

and for the mask generation.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest,

computed using the hash_alg hash algorithm.

Note:

The PSA_ALG_RSA_PSS() algorithm is equivalent to PSA_ALG_RSA_PSS_ANY_SALT() when creating a

signature, but is strict about the permitted salt length when verifying a signature.

IHI 0086

Page 237

1.1.2

Non-confidential

Compatible key types

PSA_KEY_TYPE_RSA_KEY_PAIR

PSA_KEY_TYPE_RSA_PUBLIC_KEY (signature verification only)

PSA_ALG_ECDSA (macro)

The randomized ECDSA signature scheme, with hashing.

#define PSA_ALG_ECDSA(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. This includes PSA_ALG_ANY_HASH

when specifying the algorithm in a key policy.

Returns

The corresponding randomized ECDSA signature algorithm.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest,

computed using the hash_alg hash algorithm.

This algorithm is randomized: each invocation returns a different, equally valid signature.

Note:

When based on the same hash algorithm, the verification operations for PSA_ALG_ECDSA and

PSA_ALG_DETERMINISTIC_ECDSA are identical. A signature created using PSA_ALG_ECDSA can be verified

with the same key using either PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA. Similarly, a signature

created using PSA_ALG_DETERMINISTIC_ECDSA can be verified with the same key using either

PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA.

In particular, it is impossible to determine whether a signature was produced with deterministic

ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with

ECDSA with the private key corresponding to the public key used for the verification.

This signature scheme is defined by SEC 1: Elliptic Curve Cryptography [SEC1], and also by Public Key

Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)

[X9-62], with a random per-message secret number k.

The representation of the signature as a byte string consists of the concatenation of the signature values r

and s. Each of r and s is encoded as an N-octet string, where N is the length of the base point of the curve

in octets. Each value is represented in big-endian order, with the most significant octet first.

IHI 0086

Page 238

1.1.2

Non-confidential

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(family)

PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

∙ PSA_ECC_FAMILY_SECT_XX

∙ PSA_ECC_FAMILY_SECP_XX

∙ PSA_ECC_FAMILY_FRP

∙ PSA_ECC_FAMILY_BRAINPOOL_P_R1

PSA_ALG_ECDSA_ANY (macro)

The randomized ECDSA signature scheme, without hashing.

#define PSA_ALG_ECDSA_ANY ((psa_algorithm_t) 0x06000600)

This algorithm can be only used with the psa_sign_hash() and psa_verify_hash() functions.

This algorithm is randomized: each invocation returns a different, equally valid signature.

This is the same signature scheme as PSA_ALG_ECDSA(), but without specifying a hash algorithm, and

skipping the message hashing operation.

This algorithm is only recommended to sign or verify a sequence of bytes that are an already-calculated

hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the

curve size.

This algorithm cannot be used with the wildcard key policy PSA_ALG_ECDSA(PSA_ALG_ANY_HASH). It is only

permitted when PSA_ALG_ECDSA_ANY is the key’s permitted-algorithm policy.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(family)

PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

∙ PSA_ECC_FAMILY_SECT_XX

∙ PSA_ECC_FAMILY_SECP_XX

∙ PSA_ECC_FAMILY_FRP

∙ PSA_ECC_FAMILY_BRAINPOOL_P_R1

IHI 0086

Page 239

1.1.2

Non-confidential

PSA_ALG_DETERMINISTIC_ECDSA (macro)

Deterministic ECDSA signature scheme, with hashing.

#define PSA_ALG_DETERMINISTIC_ECDSA(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. This includes PSA_ALG_ANY_HASH

when specifying the algorithm in a key policy.

Returns

The corresponding deterministic ECDSA signature algorithm.

Unspecified if hash_alg is not a supported hash algorithm.

Description

This algorithm can be used with both the message and hash signature functions.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the message digest,

computed using the hash_alg hash algorithm.

This is the deterministic ECDSA signature scheme defined by Deterministic Usage of the Digital Signature

Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) [RFC6979].

The representation of a signature is the same as with PSA_ALG_ECDSA().

Note:

When based on the same hash algorithm, the verification operations for PSA_ALG_ECDSA and

PSA_ALG_DETERMINISTIC_ECDSA are identical. A signature created using PSA_ALG_ECDSA can be verified

with the same key using either PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA. Similarly, a signature

created using PSA_ALG_DETERMINISTIC_ECDSA can be verified with the same key using either

PSA_ALG_ECDSA or PSA_ALG_DETERMINISTIC_ECDSA.

In particular, it is impossible to determine whether a signature was produced with deterministic

ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with

ECDSA with the private key corresponding to the public key used for the verification.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(family)

PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) (signature verification only)

where family is a Weierstrass Elliptic curve family. That is, one of the following values:

∙ PSA_ECC_FAMILY_SECT_XX

∙ PSA_ECC_FAMILY_SECP_XX

∙ PSA_ECC_FAMILY_FRP

∙ PSA_ECC_FAMILY_BRAINPOOL_P_R1

IHI 0086

Page 240

1.1.2

Non-confidential

PSA_ALG_PURE_EDDSA (macro)

Edwards-curve digital signature algorithm without prehashing (PureEdDSA), using standard parameters.

#define PSA_ALG_PURE_EDDSA ((psa_algorithm_t) 0x06000800)

This algorithm can be only used with the psa_sign_message() and psa_verify_message() functions.

This is the PureEdDSA digital signature algorithm defined by Edwards-Curve Digital Signature Algorithm

(EdDSA) [RFC8032], using standard parameters.

PureEdDSA requires an elliptic curve key on a twisted Edwards curve. The following curves are supported:

∙ Edwards25519: the Ed25519 algorithm is computed. The output signature is a 64-byte string: the

concatenation of R and S as defined by [RFC8032] §5.1.6.

∙ Edwards448: the Ed448 algorithm is computed with an empty string as the context. The output

signature is a 114-byte string: the concatenation of R and S as defined by [RFC8032] §5.2.6.

Note:

Contexts are not supported in the current version of this specification because there is no suitable

signature interface that can take the context as a parameter. A future version of this specification

may add suitable functions and extend this algorithm to support contexts.

Note:

To sign or verify the pre-computed hash of a message using EdDSA, the HashEdDSA algorithms

(PSA_ALG_ED25519PH and PSA_ALG_ED448PH) can be used with psa_sign_hash() and psa_verify_hash().

The signature produced by HashEdDSA is distinct from that produced by PureEdDSA.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)

PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

PSA_ALG_ED25519PH (macro)

Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards25519 curve.

#define PSA_ALG_ED25519PH ((psa_algorithm_t) 0x0600090B)

This algorithm can be used with both the message and hash signature functions.

This computes the Ed25519ph algorithm as specified in Edwards-Curve Digital Signature Algorithm (EdDSA)

[RFC8032] §5.1, and requires an Edwards25519 curve key. An empty string is used as the context. The

prehash function is SHA-512.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the SHA-512

message digest.

IHI 0086

Page 241

1.1.2

Non-confidential

Implementation note

When used with psa_sign_hash() or psa_verify_hash(), the hash parameter to the call should be used

as PH(M) in the algorithms defined in [RFC8032] §5.1.

Usage

This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:

∙ Call psa_sign_message() with the message.

∙ Calculate the SHA-512 hash of the message with psa_hash_compute(), or with a multi-part hash

operation, using the hash algorithm PSA_ALG_SHA_512. Then sign the calculated hash with

psa_sign_hash().

Verifying a signature is similar, using psa_verify_message() or psa_verify_hash() instead of the signature

function.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)

PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

PSA_ALG_ED448PH (macro)

Edwards-curve digital signature algorithm with prehashing (HashEdDSA), using the Edwards448 curve.

#define PSA_ALG_ED448PH ((psa_algorithm_t) 0x06000915)

This algorithm can be used with both the message and hash signature functions.

This computes the Ed448ph algorithm as specified in Edwards-Curve Digital Signature Algorithm (EdDSA)

[RFC8032] §5.2, and requires an Edwards448 curve key. An empty string is used as the context. The

prehash function is the first 64 bytes of the output from SHAKE256.

When used with psa_sign_hash() or psa_verify_hash(), the provided hash parameter is the truncated

SHAKE256 message digest.

Implementation note

When used with psa_sign_hash() or psa_verify_hash(), the hash parameter to the call should be used

as PH(M) in the algorithms defined in [RFC8032] §5.2.

IHI 0086

Page 242

1.1.2

Non-confidential

Usage

This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches:

∙ Call psa_sign_message() with the message.

∙ Calculate the first 64 bytes of the SHAKE256 output of the message with psa_hash_compute(), or

with a multi-part hash operation, using the hash algorithm PSA_ALG_SHAKE256_512. Then sign the

calculated hash with psa_sign_hash().

Verifying a signature is similar, using psa_verify_message() or psa_verify_hash() instead of the signature

function.

Compatible key types

PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_TWISTED_EDWARDS)

PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_TWISTED_EDWARDS) (signature verification only)

10.7.2 Asymmetric signature functions

psa_sign_message (function)

Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.

psa_status_t psa_sign_message(psa_key_id_t key,

psa_algorithm_t alg,

const uint8_t * input,

size_t input_length,

uint8_t * signature,

size_t signature_size,

size_t * signature_length);

Parameters

key

Identifier of the key to use for the operation. It must be an

asymmetric key pair. The key must permit the usage

PSA_KEY_USAGE_SIGN_MESSAGE.

alg

An asymmetric signature algorithm: a value of type psa_algorithm_t

such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true.

input

The input message to sign.

input_length

Size of the input buffer in bytes.

signature

Buffer where the signature is to be written.

signature_size

Size of the signature buffer in bytes. This must be appropriate for the

selected algorithm and key:

∙ The required signature size is PSA_SIGN_OUTPUT_SIZE(key_type,

key_bits, alg) where key_type and key_bits are the type and

bit-size respectively of key.

∙ PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size

of any supported signature algorithm.

IHI 0086

Page 243

1.1.2

Non-confidential

signature_length

On success, the number of bytes that make up the returned signature

value.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*signature_length) bytes of signature contain the

signature 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 signature buffer is too small. PSA_SIGN_OUTPUT_SIZE()

or PSA_SIGNATURE_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 an asymmetric signature algorithm.

∙ key is not an asymmetric key pair, that is compatible with alg.

∙ input_length is too large for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ alg is not supported or is not an asymmetric signature algorithm.

∙ key is not supported for use with alg.

∙ input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_ENTROPY

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 perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and

then pass the resulting hash to psa_sign_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the

hash algorithm to use.

IHI 0086

Page 244

1.1.2

Non-confidential

psa_verify_message (function)

Verify the signature of a message with a public key. For hash-and-sign algorithms, this includes the hashing

step.

psa_status_t psa_verify_message(psa_key_id_t key,

psa_algorithm_t alg,

const uint8_t * input,

size_t input_length,

const uint8_t * signature,

size_t signature_length);

Parameters

key

Identifier of the key to use for the operation. It must be a public key

or an asymmetric key pair. The key must permit the usage

PSA_KEY_USAGE_VERIFY_MESSAGE.

alg

An asymmetric signature algorithm: a value of type psa_algorithm_t

such that PSA_ALG_IS_SIGN_MESSAGE(alg) is true.

input

The message whose signature is to be verified.

input_length

Size of the input buffer in bytes.

signature

Buffer containing the signature to verify.

signature_length

Size of the signature buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. The signature is valid.

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

signature is not the result of signing the input message with

algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

∙ alg is not an asymmetric signature algorithm.

∙ key is not a public key or an asymmetric key pair, that is

compatible with alg.

∙ input_length is too large for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ alg is not supported or is not an asymmetric signature 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

IHI 0086

Page 245

1.1.2

Non-confidential

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

Note:

To perform a multi-part hash-and-sign signature verification algorithm, first use a multi-part hash

operation to hash the message and then pass the resulting hash to psa_verify_hash().

PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

psa_sign_hash (function)

Sign an already-calculated hash with a private key.

psa_status_t psa_sign_hash(psa_key_id_t key,

psa_algorithm_t alg,

const uint8_t * hash,

size_t hash_length,

uint8_t * signature,

size_t signature_size,

size_t * signature_length);

Parameters

key

Identifier of the key to use for the operation. It must be an

asymmetric key pair. The key must permit the usage

PSA_KEY_USAGE_SIGN_HASH.

alg

An asymmetric signature algorithm that separates the hash and sign

operations: a value of type psa_algorithm_t such that

PSA_ALG_IS_SIGN_HASH(alg) is true.

hash

The input to sign. This is usually the hash of a message.

See the description of this function, or the description of individual

signature algorithms, for details of the acceptable inputs.

hash_length

Size of the hash buffer in bytes.

signature

Buffer where the signature is to be written.

signature_size

Size of the signature buffer in bytes. This must be appropriate for the

selected algorithm and key:

∙ The required signature size is PSA_SIGN_OUTPUT_SIZE(key_type,

key_bits, alg) where key_type and key_bits are the type and

bit-size respectively of key.

∙ PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size

of any supported signature algorithm.

IHI 0086

Page 246

1.1.2

Non-confidential

signature_length

On success, the number of bytes that make up the returned signature

value.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*signature_length) bytes of signature contain the

signature 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_HASH flag, or it does

not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL

The size of the signature buffer is too small. PSA_SIGN_OUTPUT_SIZE()

or PSA_SIGNATURE_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 an asymmetric signature algorithm.

∙ key is not an asymmetric key pair, that is compatible with alg.

∙ hash_length is not valid for the algorithm and key type.

∙ hash is not a valid input value for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ alg is not supported or is not an asymmetric signature algorithm.

∙ key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_ENTROPY

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

With most signature algorithms that follow the hash-and-sign paradigm, the hash input to this function is

the hash of the message to sign. The algorithm used to compute this hash is encoded in the signature

algorithm. For such algorithms, hash_length must equal the length of the hash output, and the following

condition is true:

hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg))

The current version of this specification defines the following signature algorithms with this property:

PSA_ALG_RSA_PKCS1V15_SIGN, PSA_ALG_RSA_PSS, PSA_ALG_ECDSA, PSA_ALG_DETERMINISTIC_ECDSA, PSA_ALG_ED25519PH,

and PSA_ALG_ED448PH.

Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded

hash must be passed to this function. The current version of this specification defines one such signature

IHI 0086

Page 247

1.1.2

Non-confidential

algorithm: PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

Note:

To perform a hash-and-sign signature algorithm, the hash must be calculated before passing it to this

function. This can be done by calling psa_hash_compute() or with a multi-part hash operation. The

correct hash algorithm to use can be determined using PSA_ALG_GET_HASH().

Alternatively, to hash and sign a message in a single call, use psa_sign_message().

psa_verify_hash (function)

Verify the signature of a hash or short message using a public key.

psa_status_t psa_verify_hash(psa_key_id_t key,

psa_algorithm_t alg,

const uint8_t * hash,

size_t hash_length,

const uint8_t * signature,

size_t signature_length);

Parameters

key

Identifier of the key to use for the operation. It must be a public key

or an asymmetric key pair. The key must permit the usage

PSA_KEY_USAGE_VERIFY_HASH.

alg

An asymmetric signature algorithm that separates the hash and sign

operations: a value of type psa_algorithm_t such that

PSA_ALG_IS_SIGN_HASH(alg) is true.

hash

The input whose signature is to be verified. This is usually the hash of

a message.

See the description of this function, or the description of individual

signature algorithms, for details of the acceptable inputs.

hash_length

Size of the hash buffer in bytes.

signature

Buffer containing the signature to verify.

signature_length

Size of the signature buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. The signature is valid.

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_HASH flag, or it does

not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE

signature is not the result of signing hash with algorithm alg using the

private key corresponding to key.

IHI 0086

Page 248

1.1.2

Non-confidential

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

∙ alg is not an asymmetric signature algorithm.

∙ key is not a public key or an asymmetric key pair, that is

compatible with alg.

∙ hash_length is not valid for the algorithm and key type.

∙ hash is not a valid input value for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

∙ alg is not supported or is not an asymmetric signature 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

With most signature algorithms that follow the hash-and-sign paradigm, the hash input to this function is

the hash of the message to verify. The algorithm used to compute this hash is encoded in the signature

algorithm. For such algorithms, hash_length must equal the length of the hash output, and the following

condition is true:

hash_length == PSA_HASH_LENGTH(PSA_ALG_GET_HASH(alg))

The current version of this specification defines the following signature algorithms with this property:

PSA_ALG_RSA_PKCS1V15_SIGN, PSA_ALG_RSA_PSS, PSA_ALG_ECDSA, PSA_ALG_DETERMINISTIC_ECDSA, PSA_ALG_ED25519PH,

and PSA_ALG_ED448PH.

Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded

hash must be passed to this function. The current version of this specification defines one such signature

algorithm: PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

Note:

To perform a hash-and-sign verification algorithm, the hash must be calculated before passing it to

this function. This can be done by calling psa_hash_compute() or with a multi-part hash operation. The

correct hash algorithm to use can be determined using PSA_ALG_GET_HASH().

Alternatively, to hash and verify a message in a single call, use psa_verify_message().

IHI 0086

Page 249

1.1.2

Non-confidential

10.7.3 Support macros

PSA_ALG_IS_SIGN_MESSAGE (macro)

Whether the specified algorithm is a signature algorithm that can be used with psa_sign_message() and

psa_verify_message().

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a signature algorithm that can be used to sign a message. 0 if alg is a signature algorithm that can

only be used to sign an already-calculated hash. 0 if alg is not a signature algorithm. This macro can return

either 0 or 1 if alg is not a supported algorithm identifier.

PSA_ALG_IS_SIGN_HASH (macro)

Whether the specified algorithm is a signature algorithm that can be used with psa_sign_hash() and

psa_verify_hash().

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a signature algorithm that can be used to sign a hash. 0 if alg is a signature algorithm that can

only be used to sign a message. 0 if alg is not a signature algorithm. This macro can return either 0 or 1 if

alg is not a supported algorithm identifier.

Description

This includes all algorithms such that PSA_ALG_IS_HASH_AND_SIGN() is true, as well as signature algorithms for

which the input to psa_sign_hash() or psa_verify_hash() is not directly a hash, such as

PSA_ALG_IS_RSA_PKCS1V15_SIGN.

PSA_ALG_IS_RSA_PKCS1V15_SIGN (macro)

Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm.

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

IHI 0086

Page 250

1.1.2

Non-confidential

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an RSA PKCS#1 v1.5 signature algorithm, 0 otherwise.

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

PSA_ALG_IS_RSA_PSS (macro)

Whether the specified algorithm is an RSA PSS signature algorithm.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an RSA PSS signature algorithm, 0 otherwise.

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

Description

This macro returns 1 for algorithms constructed using either PSA_ALG_RSA_PSS() or

PSA_ALG_RSA_PSS_ANY_SALT().

PSA_ALG_IS_RSA_PSS_ANY_SALT (macro)

Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an RSA PSS signature algorithm that permits any salt length, 0 otherwise.

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

Description

An RSA PSS signature algorithm that permits any salt length is constructed using

PSA_ALG_RSA_PSS_ANY_SALT().

See also PSA_ALG_IS_RSA_PSS() and PSA_ALG_IS_RSA_PSS_STANDARD_SALT().

IHI 0086

Page 251

1.1.2

Non-confidential

PSA_ALG_IS_RSA_PSS_STANDARD_SALT (macro)

Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an RSA PSS signature algorithm that requires the standard salt length, 0 otherwise.

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

Description

An RSA PSS signature algorithm that requires the standard salt length is constructed using

PSA_ALG_RSA_PSS().

See also PSA_ALG_IS_RSA_PSS() and PSA_ALG_IS_RSA_PSS_ANY_SALT().

PSA_ALG_IS_ECDSA (macro)

Whether the specified algorithm is ECDSA.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is an ECDSA algorithm, 0 otherwise.

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

PSA_ALG_IS_DETERMINISTIC_ECDSA (macro)

Whether the specified algorithm is deterministic ECDSA.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

IHI 0086

Page 252

1.1.2

Non-confidential

Returns

1 if alg is a deterministic ECDSA algorithm, 0 otherwise.

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

Description

See also PSA_ALG_IS_ECDSA() and PSA_ALG_IS_RANDOMIZED_ECDSA().

PSA_ALG_IS_RANDOMIZED_ECDSA (macro)

Whether the specified algorithm is randomized ECDSA.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a randomized ECDSA algorithm, 0 otherwise.

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

Description

See also PSA_ALG_IS_ECDSA() and PSA_ALG_IS_DETERMINISTIC_ECDSA().

PSA_ALG_IS_HASH_EDDSA (macro)

Whether the specified algorithm is HashEdDSA.

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

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a HashEdDSA algorithm, 0 otherwise.

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

PSA_ALG_IS_HASH_AND_SIGN (macro)

Whether the specified algorithm is a hash-and-sign algorithm that signs exactly the hash value.

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

IHI 0086

Page 253

1.1.2

Non-confidential

Parameters

alg

An algorithm identifier: a value of type psa_algorithm_t.

Returns

1 if alg is a hash-and-sign algorithm that signs exactly the hash value, 0 otherwise. This macro can return

either 0 or 1 if alg is not a supported algorithm identifier.

A wildcard signature algorithm policy, using PSA_ALG_ANY_HASH, returns the same value as the signature

algorithm parameterised with a valid hash algorithm.

Description

This macro identifies algorithms that can be used with psa_sign_hash() that use the exact message hash

value as an input the signature operation. For example, if PSA_ALG_IS_HASH_AND_SIGN(alg) is true, the

following call sequence is equivalent to psa_sign_message(key, alg, msg, msg_len, ...):

psa_hash_operation_t op = {0};

uint8_t hash[PSA_HASH_MAX_SIZE];

size_t hash_len;

psa_hash_setup(&op, PSA_ALG_GET_HASH(alg));

psa_hash_update(&op, msg, msg_len);

psa_hash_finish(&op, hash, sizeof(hash), &hash_len);

psa_sign_hash(key, alg, hash, hash_len, ...);

This excludes hash-and-sign algorithms that require a encoded or modified hash for the signature step in

the algorithm, such as PSA_ALG_RSA_PKCS1V15_SIGN_RAW. For such algorithms, PSA_ALG_IS_SIGN_HASH() is true

but PSA_ALG_IS_HASH_AND_SIGN() is false.

PSA_ALG_ANY_HASH (macro)

When setting a hash-and-sign algorithm in a key policy, permit any hash algorithm.

#define PSA_ALG_ANY_HASH ((psa_algorithm_t)0x020000ff)

This value can be used to form the permitted-algorithm attribute of a key policy for a signature algorithm

that is parametrized by a hash. A key with this policy can then be used to perform operations using the

same signature algorithm parametrized with any supported hash. A signature algorithm created using this

macro is a wildcard algorithm, and PSA_ALG_IS_WILDCARD() will return true.

This value must not be used to build other algorithms that are parametrized over a hash. For any valid use

of this macro to build an algorithm alg, PSA_ALG_IS_HASH_AND_SIGN(alg) is true.

This value cannot be used to build an algorithm specification to perform an operation. If used in this way,

the operation will fail with an error.

IHI 0086

Page 254

1.1.2

Non-confidential

Usage

For example, suppose that PSA_xxx_SIGNATURE is one of the following macros:

∙ PSA_ALG_RSA_PKCS1V15_SIGN

∙ PSA_ALG_RSA_PSS

∙ PSA_ALG_RSA_PSS_ANY_SALT

∙ PSA_ALG_ECDSA

∙ PSA_ALG_DETERMINISTIC_ECDSA

The following sequence of operations shows how PSA_ALG_ANY_HASH can be used in a key policy:

1. Set the key usage flags using PSA_ALG_ANY_HASH, for example:

psa_set_key_usage_flags(&attributes, PSA_KEY_USAGE_SIGN_MESSAGE); // or VERIFY_MESSAGE

psa_set_key_algorithm(&attributes, PSA_xxx_SIGNATURE(PSA_ALG_ANY_HASH));

2. Import or generate key material.

3. Call psa_sign_message() or psa_verify_message(), passing an algorithm built from PSA_xxx_SIGNATURE

and a specific hash. Each call to sign or verify a message can use a different hash algorithm.

psa_sign_message(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_256), ...);

psa_sign_message(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA_512), ...);

psa_sign_message(key, PSA_xxx_SIGNATURE(PSA_ALG_SHA3_256), ...);

PSA_SIGN_OUTPUT_SIZE (macro)

Sufficient signature buffer size for psa_sign_message() and psa_sign_hash().

#define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \

/* implementation-defined value */

Parameters

key_type

An asymmetric key type. This can be a key pair type or a public key

type.

key_bits

The size of the key in bits.

alg

The signature algorithm.

Returns

A sufficient signature buffer size for the specified asymmetric signature algorithm and key parameters. An

implementation can return either 0 or a correct size for an asymmetric signature algorithm and key

parameters that it recognizes, but does not support. If the parameters are not valid, the return value is

unspecified.

IHI 0086

Page 255

1.1.2

Non-confidential

Description

If the size of the signature buffer is at least this large, it is guaranteed that psa_sign_message() and

psa_sign_hash() will not fail due to an insufficient buffer size. The actual size of the output might be

smaller in any given call.

PSA Certified Crypto API 1.1 (2023) - page 3