10.5. Authenticated encryption with associated data (AEAD)¶

The single-part AEAD functions are:

psa_aead_encrypt() to encrypt a message using an authenticated symmetric cipher.
psa_aead_decrypt() to decrypt a message using an authenticated symmetric cipher.

These functions follow the interface recommended by An Interface and Algorithms for Authenticated Encryption [RFC5116].

The encryption function requires a nonce to be provided. To generate a random nonce, either call psa_generate_random() or use the AEAD multi-part API.

The psa_aead_operation_t multi-part operation permits alternative initialization parameters and allows messages to be processed in fragments. A multi-part AEAD operation is used as follows:

Initialize the psa_aead_operation_t object to zero, or by assigning the value of the associated macro PSA_AEAD_OPERATION_INIT.
Call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() to specify the algorithm and key.
Provide additional parameters:
- If the algorithm requires it, call psa_aead_set_lengths() to specify the length of the non-encrypted and encrypted inputs to the operation.
- When encrypting, call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce.
- When decrypting, call psa_aead_set_nonce() to set the nonce.
Call psa_aead_update_ad() zero or more times with fragments of the non-encrypted additional data.
Call psa_aead_update() zero or more times with fragments of the plaintext or ciphertext to encrypt or decrypt.
At the end of the message, call the required finishing function:
- To complete an encryption operation, call psa_aead_finish() to compute and return authentication tag.
- To complete a decryption operation, call psa_aead_verify() to compute the authentication tag and verify it against a reference value.

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

Note

Using a multi-part interface to authenticated encryption raises specific issues.

Multi-part authenticated decryption produces intermediate results that are not authenticated. Revealing unauthenticated results, either directly or indirectly through the application’s behavior, can compromise the confidentiality of all inputs that are encrypted with the same key. See the detailed warning.
For encryption, some common algorithms cannot be processed in a streaming fashion. For SIV mode, the whole plaintext must be known before the encryption can start; the multi-part AEAD API is not meant to be usable with SIV mode. For CCM mode, the length of the plaintext must be known before the encryption can start; the application can call the function psa_aead_set_lengths() to provide these lengths before providing input.

10.5.1. AEAD algorithms¶

`PSA_ALG_CCM` (macro)¶

The Counter with CBC-MAC (CCM) authenticated encryption algorithm.

#define PSA_ALG_CCM ((psa_algorithm_t)0x05500100)

CCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined by the key type.

To use PSA_ALG_CCM with a multi-part AEAD operation, the application must call psa_aead_set_lengths() before providing the nonce, the additional data and plaintext to the operation.

CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce affects the maximum length of the plaintext than can be encrypted or decrypted. If the nonce has length \(N\), then the plaintext length \(pLen\) is encoded in \(L = 15 - N\) octets, this requires that \(pLen < 2^{8L}\).

The value for \(L\) that is used with PSA_ALG_CCM depends on the function used to provide the nonce:

A call to psa_aead_encrypt(), psa_aead_decrypt(), or psa_aead_set_nonce() will set \(L = 15 - \mathtt{nonce\_length}\). If the plaintext length cannot be encoded in \(L\) octets, then a PSA_ERROR_INVALID_ARGUMENT error is returned.
A call to psa_aead_generate_nonce() on a multi-part cipher operation will select the smallest integer \(L \geq 2\), where \(pLen < 2^{8L}\), with \(pLen\) being the plaintext_length provided to psa_aead_set_lengths(). The call to psa_aead_generate_nonce() will generate and return a random nonce of length \(15 - L\) bytes.

CCM supports authentication tag sizes of 4, 6, 8, 10, 12, 14, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_CCM, tag_length), where tag_length is a valid CCM tag length.

The CCM block cipher mode is defined in Counter with CBC-MAC (CCM) [RFC3610].

Usage in Zigbee

The CCM* algorithm is required by zigbee Specification [ZIGBEE].

PSA_ALG_CCM, and its truncated variants, can be used to implement CCM* for non-zero tag lengths.
For unauthenticated CCM*, with a zero-length tag, use the PSA_ALG_CCM_STAR_NO_TAG cipher algorithm.

Compatible key types

PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4

`PSA_ALG_GCM` (macro)¶

The Galois/Counter Mode (GCM) authenticated encryption algorithm.

#define PSA_ALG_GCM ((psa_algorithm_t)0x05500200)

GCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined by the key type.

GCM requires a nonce of at least 1 byte in length. The maximum supported nonce size is implementation defined. Calling psa_aead_generate_nonce() will generate a random 12-byte nonce.

GCM supports authentication tag sizes of 4, 8, 12, 13, 14, 15, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, tag_length), where tag_length is a valid GCM tag length.

The GCM block cipher mode is defined in NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC [SP800-38D].

Compatible key types

PSA_KEY_TYPE_AES
PSA_KEY_TYPE_ARIA
PSA_KEY_TYPE_CAMELLIA
PSA_KEY_TYPE_SM4

`PSA_ALG_CHACHA20_POLY1305` (macro)¶

The ChaCha20-Poly1305 AEAD algorithm.

#define PSA_ALG_CHACHA20_POLY1305 ((psa_algorithm_t)0x05100500)

There are two defined variants of ChaCha20-Poly1305:

An implementation that supports ChaCha20-Poly1305 must support the variant defined by ChaCha20 and Poly1305 for IETF Protocols [RFC8439], which has a 96-bit nonce and 32-bit counter.
An implementation can optionally also support the original variant defined by ChaCha, a variant of Salsa20 [CHACHA20], which has a 64-bit nonce and 64-bit counter.

The variant used for the AEAD encryption or decryption operation, depends on the nonce provided for an AEAD operation using PSA_ALG_CHACHA20_POLY1305:

A nonce provided in a call to psa_aead_encrypt(), psa_aead_decrypt() or psa_aead_set_nonce() must be 8 or 12 bytes. The size of nonce will select the appropriate variant of the algorithm.
A nonce generated by a call to psa_aead_generate_nonce() will be 12 bytes, and will use the [RFC8439] variant.

Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.

Compatible key types

PSA_KEY_TYPE_CHACHA20

`PSA_ALG_XCHACHA20_POLY1305` (macro)¶

The XChaCha20-Poly1305 AEAD algorithm.

#define PSA_ALG_XCHACHA20_POLY1305 ((psa_algorithm_t)0x05100600)

XChaCha20-Poly1305 is a variation of the ChaCha20-Poly1305 AEAD algorithm, but uses a 192-bit nonce. The larger nonce provides much lower probability of nonce misuse.

XChaCha20-Poly1305 requires a 24-byte nonce.

Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.

XChaCha20-Poly1305 is defined in XChaCha: eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 [XCHACHA].

Compatible key types

PSA_KEY_TYPE_XCHACHA20

`PSA_ALG_AEAD_WITH_SHORTENED_TAG` (macro)¶

Macro to build a AEAD algorithm with a shortened tag.

#define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \
    /* specification-defined value */

Parameters

aead_alg: An AEAD algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_AEAD(aead_alg) is true.
tag_length: Desired length of the authentication tag in bytes.

Returns

The corresponding AEAD algorithm with the specified tag length.

Unspecified if aead_alg is not a supported AEAD algorithm or if tag_length is not valid for the specified AEAD algorithm.

Description

An AEAD algorithm with a shortened tag is similar to the corresponding AEAD algorithm, but has an authentication tag that consists of fewer bytes. Depending on the algorithm, the tag length might affect the calculation of the ciphertext.

The AEAD algorithm with a default length tag can be recovered using PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG().

Compatible key types

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

`PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG` (macro)¶

An AEAD algorithm with the default tag length.

#define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(aead_alg) \
    /* specification-defined value */

Parameters

aead_alg: An AEAD algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_AEAD(aead_alg) is true.

Returns

The corresponding AEAD algorithm with the default tag length for that algorithm.

Description

This macro can be used to construct the AEAD algorithm with default tag length from an AEAD algorithm with a shortened tag. See also PSA_ALG_AEAD_WITH_SHORTENED_TAG().

Compatible key types

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

`PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG` (macro)¶

Macro to build an AEAD minimum-tag-length wildcard algorithm.

#define PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG(aead_alg, min_tag_length) \
    /* specification-defined value */

Parameters

aead_alg: An AEAD algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_AEAD(aead_alg) is true.
min_tag_length: Desired minimum length of the authentication tag in bytes. This must be at least 1 and at most the largest permitted tag length of the algorithm.

Returns

The corresponding AEAD wildcard algorithm with the specified minimum tag length.

Unspecified if aead_alg is not a supported AEAD algorithm or if min_tag_length is less than 1 or too large for the specified AEAD algorithm.

Description

A key with a minimum-tag-length AEAD wildcard algorithm as permitted-algorithm policy can be used with all AEAD algorithms sharing the same base algorithm, and where the tag length of the specific algorithm is equal to or larger then the minimum tag length specified by the wildcard algorithm.

Note

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

The AEAD algorithm with a default length tag can be recovered using PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG().

Compatible key types

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

10.5.2. Single-part AEAD functions¶

`psa_aead_encrypt` (function)¶

Process an authenticated encryption operation.

psa_status_t psa_aead_encrypt(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t * nonce,
                              size_t nonce_length,
                              const uint8_t * additional_data,
                              size_t additional_data_length,
                              const uint8_t * plaintext,
                              size_t plaintext_length,
                              uint8_t * ciphertext,
                              size_t ciphertext_size,
                              size_t * ciphertext_length);

Parameters

key

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

alg

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

nonce

Nonce or IV to use.

nonce_length

Size of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of key.

additional_data

Additional data that will be authenticated but not encrypted.

additional_data_length

Size of additional_data in bytes.

plaintext

Data that will be authenticated and encrypted.

plaintext_length

Size of plaintext in bytes.

ciphertext

Output buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.

ciphertext_size

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

A sufficient output size is PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) where key_type is the type of key.
PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(plaintext_length) evaluates to the maximum ciphertext size of any supported AEAD encryption.

ciphertext_length

On success, the size of the output in the ciphertext buffer.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*ciphertext_length) bytes of ciphertext contain the output.

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_ENCRYPT flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL

The size of the ciphertext buffer is too small. PSA_AEAD_ENCRYPT_OUTPUT_SIZE() or PSA_AEAD_ENCRYPT_OUTPUT_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 AEAD algorithm.
key is not compatible with alg.
nonce_length is not valid for use with alg and key.
additional_data_length or plaintext_length are too large for alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not an AEAD algorithm.
key is not supported for use with alg.
nonce_length is not supported for use with alg and key.
additional_data_length or plaintext_length are too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

`psa_aead_decrypt` (function)¶

Process an authenticated decryption operation.

psa_status_t psa_aead_decrypt(psa_key_id_t key,
                              psa_algorithm_t alg,
                              const uint8_t * nonce,
                              size_t nonce_length,
                              const uint8_t * additional_data,
                              size_t additional_data_length,
                              const uint8_t * ciphertext,
                              size_t ciphertext_length,
                              uint8_t * plaintext,
                              size_t plaintext_size,
                              size_t * plaintext_length);

Parameters

key

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

alg

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

nonce

Nonce or IV to use.

nonce_length

Size of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of key.

additional_data

Additional data that has been authenticated but not encrypted.

additional_data_length

Size of additional_data in bytes.

ciphertext

Data that has been authenticated and encrypted. For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer must contain the encrypted data followed by the authentication tag.

ciphertext_length

Size of ciphertext in bytes.

plaintext

Output buffer for the decrypted data.

plaintext_size

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

A sufficient output size is PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) where key_type is the type of key.
PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(ciphertext_length) evaluates to the maximum plaintext size of any supported AEAD decryption.

plaintext_length

On success, the size of the output in the plaintext buffer.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*plaintext_length) bytes of plaintext contain the output.

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_DECRYPT flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE

The ciphertext is not authentic.

PSA_ERROR_BUFFER_TOO_SMALL

The size of the plaintext buffer is too small. PSA_AEAD_DECRYPT_OUTPUT_SIZE() or PSA_AEAD_DECRYPT_OUTPUT_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 AEAD algorithm.
key is not compatible with alg.
nonce_length is not valid for use with alg and key.
additional_data_length or ciphertext_length are too large for alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not an AEAD algorithm.
key is not supported for use with alg.
nonce_length is not supported for use with alg and key.
additional_data_length or plaintext_length are too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

10.5.3. Multi-part AEAD operations¶

Warning

When decrypting using a multi-part AEAD operation, there is no guarantee that the input or output is valid until psa_aead_verify() has returned PSA_SUCCESS.

A call to psa_aead_update() or psa_aead_update_ad() returning PSA_SUCCESS does not indicate that the input and output is valid.

Until an application calls psa_aead_verify() and it has returned PSA_SUCCESS, the following rules apply to input and output data from a multi-part AEAD operation:

Do not trust the input. If the application takes any action that depends on the input data, this action will need to be undone if the input turns out to be invalid.
Store the output in a confidential location. In particular, the application must not copy the output to a memory or storage space which is shared.
Do not trust the output. If the application takes any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out to be invalid. Furthermore, if an adversary can observe that this action took place, for example, through timing, they might be able to use this fact as an oracle to decrypt any message encrypted with the same key.

An application that does not follow these rules might be vulnerable to maliciously constructed AEAD input data.

`psa_aead_operation_t` (typedef)¶

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

typedef /* implementation-defined type */ psa_aead_operation_t;

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

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

psa_aead_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_aead_operation_t operation;
```
Initialize the object to the initializer PSA_AEAD_OPERATION_INIT, for example:
```
psa_aead_operation_t operation = PSA_AEAD_OPERATION_INIT;
```
Assign the result of the function psa_aead_operation_init() to the object, for example:
```
psa_aead_operation_t operation;
operation = psa_aead_operation_init();
```

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

`PSA_AEAD_OPERATION_INIT` (macro)¶

This macro returns a suitable initializer for an AEAD operation object of type psa_aead_operation_t.

#define PSA_AEAD_OPERATION_INIT /* implementation-defined value */

`psa_aead_operation_init` (function)¶

Return an initial value for an AEAD operation object.

psa_aead_operation_t psa_aead_operation_init(void);

Returns: psa_aead_operation_t

`psa_aead_encrypt_setup` (function)¶

Set the key for a multi-part authenticated encryption operation.

psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t * operation,
                                    psa_key_id_t key,
                                    psa_algorithm_t alg);

Parameters

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

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

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

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

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

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not an AEAD algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not an AEAD 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

The sequence of operations to encrypt a message with authentication is as follows:

Allocate an AEAD operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
Call psa_aead_encrypt_setup() to specify the algorithm and key.
If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details.
Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce. It is recommended to use psa_aead_generate_nonce() unless the protocol being implemented requires a specific nonce value.
Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time.
Call psa_aead_finish().

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

A successful call to psa_aead_finish().
A call to psa_aead_abort().

If psa_aead_encrypt_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_aead_abort().

See Multi-part operations.

`psa_aead_decrypt_setup` (function)¶

Set the key for a multi-part authenticated decryption operation.

psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t * operation,
                                    psa_key_id_t key,
                                    psa_algorithm_t alg);

Parameters

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

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

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

PSA_ERROR_INVALID_HANDLE

key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED

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

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

alg is not an AEAD algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED

The following conditions can result in this error:

alg is not supported or is not an AEAD 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

The sequence of operations to decrypt a message with authentication is as follows:

Allocate an AEAD operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
Call psa_aead_decrypt_setup() to specify the algorithm and key.
If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details.
Call psa_aead_set_nonce() with the nonce for the decryption.
Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
Call psa_aead_update() zero, one or more times, passing a fragment of the ciphertext to decrypt each time.
Call psa_aead_verify().

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

A successful call to psa_aead_verify().
A call to psa_aead_abort().

If psa_aead_decrypt_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_aead_abort().

See Multi-part operations.

`psa_aead_set_lengths` (function)¶

Declare the lengths of the message and additional data for AEAD.

psa_status_t psa_aead_set_lengths(psa_aead_operation_t * operation,
                                  size_t ad_length,
                                  size_t plaintext_length);

Parameters

operation: Active AEAD operation.
ad_length: Size of the non-encrypted additional authenticated data in bytes.
plaintext_length: Size of the plaintext to encrypt in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active, and psa_aead_set_nonce() and psa_aead_generate_nonce() must not have been called yet.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

ad_length or plaintext_length are too large for the chosen algorithm.

PSA_ERROR_NOT_SUPPORTED

ad_length or plaintext_length are too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The application must call this function before calling psa_aead_set_nonce() or psa_aead_generate_nonce(), if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.

For PSA_ALG_CCM, calling this function is required.
For the other AEAD algorithms defined in this specification, calling this function is not required.
For vendor-defined algorithm, refer to the vendor documentation.

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

`psa_aead_generate_nonce` (function)¶

Generate a random nonce for an authenticated encryption operation.

psa_status_t psa_aead_generate_nonce(psa_aead_operation_t * operation,
                                     uint8_t * nonce,
                                     size_t nonce_size,
                                     size_t * nonce_length);

Parameters

operation

Active AEAD operation.

nonce

Buffer where the generated nonce is to be written.

nonce_size

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

A sufficient output size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
PSA_AEAD_NONCE_MAX_SIZE evaluates to a sufficient output size for any supported AEAD algorithm.

nonce_length

On success, the number of bytes of the generated nonce.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*nonce_length) bytes of nonce contain the generated nonce.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be an active AEAD encryption operation, with no nonce set.
The operation state is not valid: this is an algorithm which requires psa_aead_set_lengths() to be called before setting the nonce.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the nonce buffer is too small. PSA_AEAD_NONCE_LENGTH() or PSA_AEAD_NONCE_MAX_SIZE can be used to determine a sufficient buffer size.

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

This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.

Most algorithms generate a default-length nonce, as returned by PSA_AEAD_NONCE_LENGTH(). Some algorithms can return a shorter nonce from psa_aead_generate_nonce(), see the individual algorithm descriptions for details.

The application must call psa_aead_encrypt_setup() before calling this function. If applicable for the algorithm, the application must call psa_aead_set_lengths() before calling this function.

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

`psa_aead_set_nonce` (function)¶

Set the nonce for an authenticated encryption or decryption operation.

psa_status_t psa_aead_set_nonce(psa_aead_operation_t * operation,
                                const uint8_t * nonce,
                                size_t nonce_length);

Parameters

operation: Active AEAD operation.
nonce: Buffer containing the nonce to use.
nonce_length: Size of the nonce in bytes. This must be a valid nonce size for the chosen algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(key_type, alg) where key_type and alg are type of key and the algorithm respectively that were used to set up the AEAD 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: it must be active, with no nonce set.
The operation state is not valid: this is an algorithm which requires psa_aead_set_lengths() to be called before setting the nonce.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

nonce_length is not valid for the chosen algorithm.

PSA_ERROR_NOT_SUPPORTED

nonce_length is not supported for use with the operation’s algorithm and key.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

This function sets the nonce for the authenticated encryption or decryption operation.

The application must call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() before calling this function. If applicable for the algorithm, the application must call psa_aead_set_lengths() before calling this function.

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

Note

When encrypting, psa_aead_generate_nonce() is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.

`psa_aead_update_ad` (function)¶

Pass additional data to an active AEAD operation.

psa_status_t psa_aead_update_ad(psa_aead_operation_t * operation,
                                const uint8_t * input,
                                size_t input_length);

Parameters

operation: Active AEAD operation.
input: Buffer containing the fragment of additional data.
input_length: Size of the input buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

Warning

When decrypting, do not trust the additional data until psa_aead_verify() succeeds.

See the detailed warning.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active, have a nonce set, have lengths set if required by the algorithm, and psa_aead_update() must not have been called yet.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

Excess additional data: the total input length to psa_aead_update_ad() is greater than the additional data length that was previously specified with psa_aead_set_lengths(), or is too large for the chosen AEAD algorithm.

PSA_ERROR_NOT_SUPPORTED

The total additional data length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

Additional data is authenticated, but not encrypted.

This function can be called multiple times to pass successive fragments of the additional data. This function must not be called after passing data to encrypt or decrypt with psa_aead_update().

The following must occur before calling this function:

Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().

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

`psa_aead_update` (function)¶

Encrypt or decrypt a message fragment in an active AEAD operation.

psa_status_t psa_aead_update(psa_aead_operation_t * operation,
                             const uint8_t * input,
                             size_t input_length,
                             uint8_t * output,
                             size_t output_size,
                             size_t * output_length);

Parameters

operation

Active AEAD operation.

input

Buffer containing the message fragment to encrypt or decrypt.

input_length

Size of the input buffer in bytes.

output

Buffer where the output is to be written.

output_size

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

A sufficient output size is PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) evaluates to the maximum output size of any supported AEAD algorithm.

output_length

On success, the number of bytes that make up the returned output.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*output_length) of output contains the output data.

Warning

When decrypting, do not use the output until psa_aead_verify() succeeds.

See the detailed warning.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active, have a nonce set, and have lengths set if required by the algorithm.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the output buffer is too small. PSA_AEAD_UPDATE_OUTPUT_SIZE() or PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE() can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

Incomplete additional data: the total length of input to psa_aead_update_ad() is less than the additional data length that was previously specified with psa_aead_set_lengths().
Excess input data: the total length of input to psa_aead_update() is greater than the plaintext length that was previously specified with psa_aead_set_lengths(), or is too large for the specific AEAD algorithm.

PSA_ERROR_NOT_SUPPORTED

The total input length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

The following must occur before calling this function:

Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
Call psa_aead_update_ad() to pass all the additional data.

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

Note

This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it might delay the end of the corresponding output until a subsequent call to psa_aead_update() provides sufficient input, or a subsequent call to psa_aead_finish() or psa_aead_verify() indicates the end of the input. The amount of data that can be delayed in this way is bounded by the associated output size macro: PSA_AEAD_UPDATE_OUTPUT_SIZE(), PSA_AEAD_FINISH_OUTPUT_SIZE(), or PSA_AEAD_VERIFY_OUTPUT_SIZE().

`psa_aead_finish` (function)¶

Finish encrypting a message in an AEAD operation.

psa_status_t psa_aead_finish(psa_aead_operation_t * operation,
                             uint8_t * ciphertext,
                             size_t ciphertext_size,
                             size_t * ciphertext_length,
                             uint8_t * tag,
                             size_t tag_size,
                             size_t * tag_length);

Parameters

operation

Active AEAD operation.

ciphertext

Buffer where the last part of the ciphertext is to be written.

ciphertext_size

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

A sufficient output size is PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.

ciphertext_length

On success, the number of bytes of returned ciphertext.

tag

Buffer where the authentication tag is to be written.

tag_size

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

The exact tag size is PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) where key_type and key_bits are the type and bit-size of the key, and alg is the algorithm that were used in the call to psa_aead_encrypt_setup().
PSA_AEAD_TAG_MAX_SIZE evaluates to the maximum tag size of any supported AEAD algorithm.

tag_length

On success, the number of bytes that make up the returned tag.

Returns: psa_status_t

PSA_SUCCESS

Success. The first (*tag_length) bytes of tag contain the authentication tag.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be an active encryption operation with a nonce set.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL

The size of the ciphertext or tag buffer is too small. PSA_AEAD_FINISH_OUTPUT_SIZE() or PSA_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the required ciphertext buffer size. PSA_AEAD_TAG_LENGTH() or PSA_AEAD_TAG_MAX_SIZE can be used to determine the required tag buffer size.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

Incomplete additional data: the total length of input to psa_aead_update_ad() is less than the additional data length that was previously specified with psa_aead_set_lengths().
Incomplete plaintext: the total length of input to psa_aead_update() is less than the plaintext length that was previously specified with psa_aead_set_lengths().

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

The operation must have been set up with psa_aead_encrypt_setup().

This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to psa_aead_update().

This function has two output buffers:

ciphertext contains trailing ciphertext that was buffered from preceding calls to psa_aead_update().
tag contains the authentication tag.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

`psa_aead_verify` (function)¶

Finish authenticating and decrypting a message in an AEAD operation.

psa_status_t psa_aead_verify(psa_aead_operation_t * operation,
                             uint8_t * plaintext,
                             size_t plaintext_size,
                             size_t * plaintext_length,
                             const uint8_t * tag,
                             size_t tag_length);

Parameters

operation

Active AEAD operation.

plaintext

Buffer where the last part of the plaintext is to be written. This is the remaining data from previous calls to psa_aead_update() that could not be processed until the end of the input.

plaintext_size

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

A sufficient output size is PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) where key_type is the type of key and alg is the algorithm that were used to set up the operation.
PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.

plaintext_length

On success, the number of bytes of returned plaintext.

tag

Buffer containing the expected authentication tag.

tag_length

Size of the tag buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success. For a decryption operation, it is now safe to use the additional data and the plaintext output.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be an active decryption operation with a nonce set.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE

The calculated authentication tag does not match the value in tag.

PSA_ERROR_BUFFER_TOO_SMALL

The size of the plaintext buffer is too small. PSA_AEAD_VERIFY_OUTPUT_SIZE() or PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

Incomplete additional data: the total length of input to psa_aead_update_ad() is less than the additional data length that was previously specified with psa_aead_set_lengths().
Incomplete ciphertext: the total length of input to psa_aead_update() is less than the plaintext length that was previously specified with psa_aead_set_lengths().

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

Description

The operation must have been set up with psa_aead_decrypt_setup().

This function finishes the authenticated decryption of the message components:

The additional data consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update_ad().
The ciphertext consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update().
The tag passed to this function call.

If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns PSA_ERROR_INVALID_SIGNATURE.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Implementation note

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

`psa_aead_abort` (function)¶

Abort an AEAD operation.

psa_status_t psa_aead_abort(psa_aead_operation_t * operation);

Parameters

operation: Initialized AEAD operation.

Returns: psa_status_t

PSA_SUCCESS: Success. The operation object can now be discarded or reused.
PSA_ERROR_BAD_STATE: The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED

Description

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_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.

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.

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

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

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.

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

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

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

`PSA_AEAD_NONCE_MAX_SIZE` (macro)¶

A sufficient buffer size for storing the nonce generated by psa_aead_generate_nonce(), for any of the supported key types and AEAD algorithms.

#define PSA_AEAD_NONCE_MAX_SIZE /* implementation-defined value */

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.

`PSA_AEAD_UPDATE_OUTPUT_SIZE` (macro)¶

A sufficient output buffer size for psa_aead_update().

#define PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_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.
input_length: Size of the input in bytes.

Returns

A sufficient output buffer 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 output buffer is at least this large, it is guaranteed that psa_aead_update() will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.

`PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE` (macro)¶

A sufficient output buffer size for psa_aead_update(), for any of the supported key types and AEAD algorithms.

#define PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(input_length) \
    /* implementation-defined value */

Parameters

input_length: Size of the input in bytes.

Description

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

`PSA_AEAD_FINISH_OUTPUT_SIZE` (macro)¶

A sufficient ciphertext buffer size for psa_aead_finish().

#define PSA_AEAD_FINISH_OUTPUT_SIZE(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

A sufficient ciphertext buffer 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_finish() will not fail due to an insufficient ciphertext buffer size. The actual size of the output might be smaller in any given call.

`PSA_AEAD_FINISH_OUTPUT_MAX_SIZE` (macro)¶

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

#define PSA_AEAD_FINISH_OUTPUT_MAX_SIZE /* implementation-defined value */

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

`PSA_AEAD_TAG_LENGTH` (macro)¶

The length of a tag for an AEAD algorithm, in bytes.

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

Parameters

key_type: The type of the AEAD key.
key_bits: The size of the AEAD key in bits.
alg: An AEAD algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_AEAD(alg) is true.

Returns

The tag length for the specified algorithm and key. If the AEAD algorithm does not have an identified tag that can be distinguished from the rest of the ciphertext, return 0. If the AEAD algorithm is not recognized, return 0. An implementation can return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support.

Description

This is the size of the tag output from psa_aead_finish().

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

`PSA_AEAD_TAG_MAX_SIZE` (macro)¶

A sufficient buffer size for storing the tag output by psa_aead_finish(), for any of the supported key types and AEAD algorithms.

#define PSA_AEAD_TAG_MAX_SIZE /* implementation-defined value */

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

`PSA_AEAD_VERIFY_OUTPUT_SIZE` (macro)¶

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

#define PSA_AEAD_VERIFY_OUTPUT_SIZE(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

A sufficient plaintext buffer 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_verify() will not fail due to an insufficient plaintext buffer size. The actual size of the output might be smaller in any given call.

`PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE` (macro)¶

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

#define PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE /* implementation-defined value */

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

10.5. Authenticated encryption with associated data (AEAD)¶

10.5.1. AEAD algorithms¶

PSA_ALG_CCM (macro)¶

PSA_ALG_GCM (macro)¶

PSA_ALG_CHACHA20_POLY1305 (macro)¶

PSA_ALG_XCHACHA20_POLY1305 (macro)¶

PSA_ALG_AEAD_WITH_SHORTENED_TAG (macro)¶

PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG (macro)¶

PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG (macro)¶

10.5.2. Single-part AEAD functions¶

psa_aead_encrypt (function)¶

psa_aead_decrypt (function)¶

10.5.3. Multi-part AEAD operations¶

psa_aead_operation_t (typedef)¶

PSA_AEAD_OPERATION_INIT (macro)¶

psa_aead_operation_init (function)¶

psa_aead_encrypt_setup (function)¶

psa_aead_decrypt_setup (function)¶

psa_aead_set_lengths (function)¶

psa_aead_generate_nonce (function)¶

psa_aead_set_nonce (function)¶

psa_aead_update_ad (function)¶

psa_aead_update (function)¶

psa_aead_finish (function)¶

psa_aead_verify (function)¶

psa_aead_abort (function)¶

10.5.4. Support macros¶

PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER (macro)¶

PSA_AEAD_ENCRYPT_OUTPUT_SIZE (macro)¶

PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE (macro)¶

PSA_AEAD_DECRYPT_OUTPUT_SIZE (macro)¶

PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE (macro)¶

PSA_AEAD_NONCE_LENGTH (macro)¶

PSA_AEAD_NONCE_MAX_SIZE (macro)¶

PSA_AEAD_UPDATE_OUTPUT_SIZE (macro)¶

PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE (macro)¶

PSA_AEAD_FINISH_OUTPUT_SIZE (macro)¶

PSA_AEAD_FINISH_OUTPUT_MAX_SIZE (macro)¶

PSA_AEAD_TAG_LENGTH (macro)¶

PSA_AEAD_TAG_MAX_SIZE (macro)¶

PSA_AEAD_VERIFY_OUTPUT_SIZE (macro)¶

PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE (macro)¶

`PSA_ALG_CCM` (macro)¶

`PSA_ALG_GCM` (macro)¶

`PSA_ALG_CHACHA20_POLY1305` (macro)¶

`PSA_ALG_XCHACHA20_POLY1305` (macro)¶

`PSA_ALG_AEAD_WITH_SHORTENED_TAG` (macro)¶

`PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG` (macro)¶

`PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG` (macro)¶

`psa_aead_encrypt` (function)¶

`psa_aead_decrypt` (function)¶

`psa_aead_operation_t` (typedef)¶

`PSA_AEAD_OPERATION_INIT` (macro)¶

`psa_aead_operation_init` (function)¶

`psa_aead_encrypt_setup` (function)¶

`psa_aead_decrypt_setup` (function)¶

`psa_aead_set_lengths` (function)¶

`psa_aead_generate_nonce` (function)¶

`psa_aead_set_nonce` (function)¶

`psa_aead_update_ad` (function)¶

`psa_aead_update` (function)¶

`psa_aead_finish` (function)¶

`psa_aead_verify` (function)¶

`psa_aead_abort` (function)¶

`PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER` (macro)¶

`PSA_AEAD_ENCRYPT_OUTPUT_SIZE` (macro)¶

`PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE` (macro)¶

`PSA_AEAD_DECRYPT_OUTPUT_SIZE` (macro)¶

`PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE` (macro)¶

`PSA_AEAD_NONCE_LENGTH` (macro)¶

`PSA_AEAD_NONCE_MAX_SIZE` (macro)¶

`PSA_AEAD_UPDATE_OUTPUT_SIZE` (macro)¶

`PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE` (macro)¶

`PSA_AEAD_FINISH_OUTPUT_SIZE` (macro)¶

`PSA_AEAD_FINISH_OUTPUT_MAX_SIZE` (macro)¶

`PSA_AEAD_TAG_LENGTH` (macro)¶

`PSA_AEAD_TAG_MAX_SIZE` (macro)¶

`PSA_AEAD_VERIFY_OUTPUT_SIZE` (macro)¶

`PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE` (macro)¶