Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
Typedefs | |
typedef struct psa_aead_operation_s | psa_aead_operation_t |
The type of the state data structure for multipart AEAD operations. | |
Functions | |
psa_status_t | psa_aead_encrypt (psa_key_handle_t handle, 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) |
Process an authenticated encryption operation. | |
psa_status_t | psa_aead_decrypt (psa_key_handle_t handle, 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) |
Process an authenticated decryption operation. | |
static psa_aead_operation_t | psa_aead_operation_init (void) |
Return an initial value for an AEAD operation object. | |
psa_status_t | psa_aead_encrypt_setup (psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg) |
Set the key for a multipart authenticated encryption operation. | |
psa_status_t | psa_aead_decrypt_setup (psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg) |
Set the key for a multipart authenticated decryption operation. | |
psa_status_t | psa_aead_generate_nonce (psa_aead_operation_t *operation, uint8_t *nonce, size_t nonce_size, size_t *nonce_length) |
Generate a random nonce for an authenticated encryption operation. | |
psa_status_t | psa_aead_set_nonce (psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length) |
Set the nonce for an authenticated encryption or decryption operation. | |
psa_status_t | psa_aead_set_lengths (psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length) |
Declare the lengths of the message and additional data for AEAD. | |
psa_status_t | psa_aead_update_ad (psa_aead_operation_t *operation, const uint8_t *input, size_t input_length) |
Pass additional data to 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) |
Encrypt or decrypt a message fragment in an active 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) |
Finish encrypting 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) |
Finish authenticating and decrypting a message in an AEAD operation. | |
psa_status_t | psa_aead_abort (psa_aead_operation_t *operation) |
Abort an AEAD operation. |
Typedef Documentation
typedef struct psa_aead_operation_s psa_aead_operation_t |
The type of the state data structure for multipart AEAD operations.
Before calling any function on an AEAD operation object, the application must initialize it by any of the following means:
- Set the structure to all-bits-zero, for example:
psa_aead_operation_t operation; memset(&operation, 0, sizeof(operation));
- Initialize the structure to logical zero values, for example:
psa_aead_operation_t operation = {0};
- Initialize the structure 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 structure, for example:
psa_aead_operation_t operation; operation = psa_aead_operation_init();
This is an implementation-defined struct
. Applications should not make any assumptions about the content of this structure except as directed by the documentation of a specific implementation.
Function Documentation
psa_status_t psa_aead_abort | ( | psa_aead_operation_t * | operation ) |
Abort an AEAD operation.
Aborting an operation frees all associated resources except for the operation
structure itself. Once aborted, the operation object can be reused for another operation by calling psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.
You may call this function 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.
- Parameters:
-
[in,out] operation Initialized AEAD operation.
- Return values:
-
PSA_SUCCESS PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_aead_decrypt | ( | psa_key_handle_t | handle, |
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 | ||
) |
Process an authenticated decryption operation.
- Parameters:
-
handle Handle to the key to use for the operation. alg The AEAD algorithm to compute ( PSA_ALG_XXX
value such that PSA_ALG_IS_AEAD(alg
) is true).[in] nonce Nonce or IV to use. nonce_length Size of the nonce
buffer in bytes.[in] additional_data Additional data that has been authenticated but not encrypted. additional_data_length Size of additional_data
in bytes.[in] 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.[out] plaintext Output buffer for the decrypted data. plaintext_size Size of the plaintext
buffer in bytes. This must be at least PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg
,ciphertext_length
).[out] plaintext_length On success, the size of the output in the plaintext
buffer.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_INVALID_HANDLE PSA_ERROR_INVALID_SIGNATURE The ciphertext is not authentic. PSA_ERROR_NOT_PERMITTED PSA_ERROR_INVALID_ARGUMENT handle
is not compatible withalg
.PSA_ERROR_NOT_SUPPORTED alg
is not supported or is not an AEAD algorithm.PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_BUFFER_TOO_SMALL plaintext_size
ornonce_length
is too smallPSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
Definition at line 4239 of file psa_crypto.c.
psa_status_t psa_aead_decrypt_setup | ( | psa_aead_operation_t * | operation, |
psa_key_handle_t | handle, | ||
psa_algorithm_t | alg | ||
) |
Set the key for a multipart authenticated decryption operation.
The sequence of operations to decrypt a message with authentication is as follows:
- Allocate an 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().
If an error occurs at any step after a call to psa_aead_decrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized.
After a successful call to psa_aead_decrypt_setup(), 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().
- Parameters:
-
[in,out] 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. handle Handle to the key to use for the operation. It must remain valid until the operation terminates. alg The AEAD algorithm to compute ( PSA_ALG_XXX
value such that PSA_ALG_IS_AEAD(alg
) is true).
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be inactive). PSA_ERROR_INVALID_HANDLE PSA_ERROR_NOT_PERMITTED PSA_ERROR_INVALID_ARGUMENT handle
is not compatible withalg
.PSA_ERROR_NOT_SUPPORTED alg
is not supported or is not an AEAD algorithm.PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_aead_encrypt | ( | psa_key_handle_t | handle, |
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 | ||
) |
Process an authenticated encryption operation.
- Parameters:
-
handle Handle to the key to use for the operation. alg The AEAD algorithm to compute ( PSA_ALG_XXX
value such that PSA_ALG_IS_AEAD(alg
) is true).[in] nonce Nonce or IV to use. nonce_length Size of the nonce
buffer in bytes.[in] additional_data Additional data that will be authenticated but not encrypted. additional_data_length Size of additional_data
in bytes.[in] plaintext Data that will be authenticated and encrypted. plaintext_length Size of plaintext
in bytes.[out] 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 at least PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg
,plaintext_length
).[out] ciphertext_length On success, the size of the output in the ciphertext
buffer.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_INVALID_HANDLE PSA_ERROR_NOT_PERMITTED PSA_ERROR_INVALID_ARGUMENT handle
is not compatible withalg
.PSA_ERROR_NOT_SUPPORTED alg
is not supported or is not an AEAD algorithm.PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_BUFFER_TOO_SMALL ciphertext_size
is too smallPSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
Definition at line 4125 of file psa_crypto.c.
psa_status_t psa_aead_encrypt_setup | ( | psa_aead_operation_t * | operation, |
psa_key_handle_t | handle, | ||
psa_algorithm_t | alg | ||
) |
Set the key for a multipart authenticated encryption operation.
The sequence of operations to encrypt a message with authentication is as follows:
- Allocate an 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. You should use psa_aead_generate_nonce() unless the protocol you are implementing 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().
If an error occurs at any step after a call to psa_aead_encrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application may call psa_aead_abort() at any time after the operation has been initialized.
After a successful call to psa_aead_encrypt_setup(), 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().
- Parameters:
-
[in,out] 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. handle Handle to the key to use for the operation. It must remain valid until the operation terminates. alg The AEAD algorithm to compute ( PSA_ALG_XXX
value such that PSA_ALG_IS_AEAD(alg
) is true).
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be inactive). PSA_ERROR_INVALID_HANDLE PSA_ERROR_NOT_PERMITTED PSA_ERROR_INVALID_ARGUMENT handle
is not compatible withalg
.PSA_ERROR_NOT_SUPPORTED alg
is not supported or is not an AEAD algorithm.PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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 | ||
) |
Finish encrypting a message in an AEAD operation.
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. Its length is always PSA_AEAD_TAG_LENGTH(alg
) wherealg
is the AEAD algorithm that the operation performs.
When this function returns successfuly, 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().
- Parameters:
-
[in,out] operation Active AEAD operation. [out] 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 at least PSA_AEAD_FINISH_OUTPUT_SIZE(alg
) wherealg
is the algorithm that is being calculated.[out] ciphertext_length On success, the number of bytes of returned ciphertext. [out] tag Buffer where the authentication tag is to be written. tag_size Size of the tag
buffer in bytes. This must be at least PSA_AEAD_TAG_LENGTH(alg
) wherealg
is the algorithm that is being calculated.[out] tag_length On success, the number of bytes that make up the returned tag.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be an active encryption operation with a nonce set). PSA_ERROR_BUFFER_TOO_SMALL The size of the ciphertext
ortag
buffer is too small. You can determine a sufficient buffer size forciphertext
by calling PSA_AEAD_FINISH_OUTPUT_SIZE(alg
) wherealg
is the algorithm that is being calculated. You can determine a sufficient buffer size fortag
by calling PSA_AEAD_TAG_LENGTH(alg
).PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(). PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update() so far 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_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_aead_generate_nonce | ( | psa_aead_operation_t * | operation, |
uint8_t * | nonce, | ||
size_t | nonce_size, | ||
size_t * | nonce_length | ||
) |
Generate a random nonce for an authenticated encryption operation.
This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.
The application must call psa_aead_encrypt_setup() before calling this function.
If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
- Parameters:
-
[in,out] operation Active AEAD operation. [out] nonce Buffer where the generated nonce is to be written. nonce_size Size of the nonce
buffer in bytes.[out] nonce_length On success, the number of bytes of the generated nonce.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be an active aead encrypt operation, with no nonce set). PSA_ERROR_BUFFER_TOO_SMALL The size of the nonce
buffer is too small.PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
static psa_aead_operation_t psa_aead_operation_init | ( | void | ) | [static] |
Return an initial value for an AEAD operation object.
psa_status_t psa_aead_set_lengths | ( | psa_aead_operation_t * | operation, |
size_t | ad_length, | ||
size_t | plaintext_length | ||
) |
Declare the lengths of the message and additional data for AEAD.
The application must call this function before calling psa_aead_update_ad() or psa_aead_update() 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.
You may call this function before or after setting the nonce with psa_aead_set_nonce() or psa_aead_generate_nonce().
- 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().
- Parameters:
-
[in,out] 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.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be active, and psa_aead_update_ad() and psa_aead_update() must not have been called yet). PSA_ERROR_INVALID_ARGUMENT At least one of the lengths is not acceptable for the chosen algorithm. PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_aead_set_nonce | ( | psa_aead_operation_t * | operation, |
const uint8_t * | nonce, | ||
size_t | nonce_length | ||
) |
Set the nonce for an authenticated encryption or decryption operation.
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 this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().
- Note:
- When encrypting, applications should use psa_aead_generate_nonce() instead of this function, unless implementing a protocol that requires a non-random IV.
- Parameters:
-
[in,out] operation Active AEAD operation. [in] nonce Buffer containing the nonce to use. nonce_length Size of the nonce in bytes.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be active, with no nonce set). PSA_ERROR_INVALID_ARGUMENT The size of nonce
is not acceptable for the chosen algorithm.PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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 | ||
) |
Encrypt or decrypt a message fragment in an active AEAD operation.
Before calling this function, you must: 1. 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. 2. Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce(). 3. 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().
- Warning:
- When decrypting, until psa_aead_verify() has returned PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned PSA_SUCCESS:
- Do not use the output in any way other than storing it in a confidential location. If you take any action that depends on the tentative decrypted data, this action will need to be undone if the input turns out not to be valid. Furthermore, if an adversary can observe that this action took place (for example through timing), they may be able to use this fact as an oracle to decrypt any message encrypted with the same key.
- In particular, do not copy the output anywhere but to a memory or storage space that you have exclusive access to.
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 may delay the end of the corresponding output until a subsequent call to psa_aead_update(), psa_aead_finish() or psa_aead_verify() provides sufficient input. The amount of data that can be delayed in this way is bounded by PSA_AEAD_UPDATE_OUTPUT_SIZE.
- Parameters:
-
[in,out] operation Active AEAD operation. [in] input Buffer containing the message fragment to encrypt or decrypt. input_length Size of the input
buffer in bytes.[out] output Buffer where the output is to be written. output_size Size of the output
buffer in bytes. This must be at least PSA_AEAD_UPDATE_OUTPUT_SIZE(alg
,input_length
) wherealg
is the algorithm that is being calculated.[out] output_length On success, the number of bytes that make up the returned output.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE The operation state is not valid (it must be active, have a nonce set, and have lengths set if required by the algorithm). PSA_ERROR_BUFFER_TOO_SMALL The size of the output
buffer is too small. You can determine a sufficient buffer size by calling PSA_AEAD_UPDATE_OUTPUT_SIZE(alg
,input_length
) wherealg
is the algorithm that is being calculated.PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(). PSA_ERROR_INVALID_ARGUMENT The total input length overflows the plaintext length that was previously specified with psa_aead_set_lengths(). PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
psa_status_t psa_aead_update_ad | ( | psa_aead_operation_t * | operation, |
const uint8_t * | input, | ||
size_t | input_length | ||
) |
Pass additional data to an active AEAD operation.
Additional data is authenticated, but not encrypted.
You may call this function multiple times to pass successive fragments of the additional data. You may not call this function after passing data to encrypt or decrypt with psa_aead_update().
Before calling this function, you must: 1. Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). 2. 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().
- Warning:
- When decrypting, until psa_aead_verify() has returned PSA_SUCCESS, there is no guarantee that the input is valid. Therefore, until you have called psa_aead_verify() and it has returned PSA_SUCCESS, treat the input as untrusted and prepare to undo any action that depends on the input if psa_aead_verify() returns an error status.
- Parameters:
-
[in,out] operation Active AEAD operation. [in] input Buffer containing the fragment of additional data. input_length Size of the input
buffer in bytes.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_BAD_STATE 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). PSA_ERROR_INVALID_ARGUMENT The total input length overflows the additional data length that was previously specified with psa_aead_set_lengths(). PSA_ERROR_INSUFFICIENT_MEMORY PSA_ERROR_COMMUNICATION_FAILURE PSA_ERROR_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
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 | ||
) |
Finish authenticating and decrypting a message in an AEAD operation.
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 successfuly, 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().
- Note:
- Implementations shall make the best effort to ensure that the comparison between the actual tag and the expected tag is performed in constant time.
- Parameters:
-
[in,out] operation Active AEAD operation. [out] 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 at least PSA_AEAD_VERIFY_OUTPUT_SIZE(alg
) wherealg
is the algorithm that is being calculated.[out] plaintext_length On success, the number of bytes of returned plaintext. [in] tag Buffer containing the authentication tag. tag_length Size of the tag
buffer in bytes.
- Return values:
-
PSA_SUCCESS Success. PSA_ERROR_INVALID_SIGNATURE The calculations were successful, but the authentication tag is not correct. PSA_ERROR_BAD_STATE The operation state is not valid (it must be an active decryption operation with a nonce set). PSA_ERROR_BUFFER_TOO_SMALL The size of the plaintext
buffer is too small. You can determine a sufficient buffer size forplaintext
by calling PSA_AEAD_VERIFY_OUTPUT_SIZE(alg
) wherealg
is the algorithm that is being calculated.PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(). PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update() so far 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_HARDWARE_FAILURE PSA_ERROR_CORRUPTION_DETECTED PSA_ERROR_STORAGE_FAILURE PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.
Generated on Tue Jul 12 2022 13:55:24 by
