|
Platform Security Architecture — cryptography and keystore interface
beta 2 — 2019-02-22
|
Macros | |
| #define | PSA_AEAD_OPERATION_INIT {0} |
Typedefs | |
| typedef struct psa_aead_operation_s | psa_aead_operation_t |
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) |
| 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) |
| psa_status_t | psa_aead_encrypt_setup (psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg) |
| psa_status_t | psa_aead_decrypt_setup (psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg) |
| psa_status_t | psa_aead_generate_nonce (psa_aead_operation_t *operation, unsigned char *nonce, size_t nonce_size, size_t *nonce_length) |
| psa_status_t | psa_aead_set_nonce (psa_aead_operation_t *operation, const unsigned char *nonce, size_t nonce_length) |
| psa_status_t | psa_aead_set_lengths (psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length) |
| psa_status_t | psa_aead_update_ad (psa_aead_operation_t *operation, const uint8_t *input, size_t input_length) |
| psa_status_t | psa_aead_update (psa_aead_operation_t *operation, const uint8_t *input, size_t input_length, unsigned char *output, size_t output_size, size_t *output_length) |
| 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) |
| psa_status_t | psa_aead_verify (psa_aead_operation_t *operation, const uint8_t *tag, size_t tag_length) |
| psa_status_t | psa_aead_abort (psa_aead_operation_t *operation) |
| #define PSA_AEAD_OPERATION_INIT {0} |
This macro returns a suitable initializer for an AEAD operation object of type psa_aead_operation_t.
| 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:
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.
| 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 by any of the following methods:
struct to all-bits-zero.struct to logical zeros, e.g. psa_aead_operation_t operation = {0}.In particular, calling psa_aead_abort() after the operation has been terminated by a call to psa_aead_abort() or psa_aead_finish() is safe and has no effect.
| [in,out] | operation | Initialized AEAD operation. |
| PSA_SUCCESS | |
| PSA_ERROR_BAD_STATE | operation is not an active AEAD operation. |
| PSA_ERROR_COMMUNICATION_FAILURE | |
| PSA_ERROR_HARDWARE_FAILURE | |
| PSA_ERROR_TAMPERING_DETECTED |
| 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.
| 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. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_INVALID_SIGNATURE | The ciphertext is not authentic. |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | key is not compatible with alg. |
| 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_TAMPERING_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_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:
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:
psa_aead_xxx functions.| [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). |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | key is not compatible with alg. |
| 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_TAMPERING_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_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.
| 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. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | key is not compatible with alg. |
| 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_TAMPERING_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_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:
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:
psa_aead_xxx functions.| [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). |
| PSA_SUCCESS | Success. |
| PSA_ERROR_INVALID_HANDLE | |
| PSA_ERROR_EMPTY_SLOT | |
| PSA_ERROR_NOT_PERMITTED | |
| PSA_ERROR_INVALID_ARGUMENT | key is not compatible with alg. |
| 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_TAMPERING_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_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(). For all standard AEAD algorithms, psa_aead_update() does not buffer any output and therefore ciphertext will not contain any output and can be a 0-sized buffer.tag contains the authentication tag. Its length is always PSA_AEAD_TAG_LENGTH(alg) where alg is the AEAD algorithm that the operation performs.When this function returns, the operation becomes inactive.
| [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. | |
| [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. | |
| [out] | tag_length | On success, the number of bytes that make up the returned tag. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, nonce not set, decryption, or already completed). |
| PSA_ERROR_BUFFER_TOO_SMALL | The size of the output buffer is too small. |
| 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_TAMPERING_DETECTED |
| psa_status_t psa_aead_generate_nonce | ( | psa_aead_operation_t * | operation, |
| unsigned char * | 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 becomes inactive.
| [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. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, or nonce already 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_TAMPERING_DETECTED |
| 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().
| [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. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, already completed, or psa_aead_update_ad() or psa_aead_update() already called). |
| 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_TAMPERING_DETECTED |
| psa_status_t psa_aead_set_nonce | ( | psa_aead_operation_t * | operation, |
| const unsigned char * | 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() before calling this function.
If this function returns an error status, the operation becomes inactive.
| [in,out] | operation | Active AEAD operation. |
| [in] | nonce | Buffer containing the nonce to use. |
| nonce_length | Size of the nonce in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, or nonce already 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_TAMPERING_DETECTED |
| psa_status_t psa_aead_update | ( | psa_aead_operation_t * | operation, |
| const uint8_t * | input, | ||
| size_t | input_length, | ||
| unsigned char * | 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:
If this function returns an error status, the operation becomes inactive.
| [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. | |
| [out] | output_length | On success, the number of bytes that make up the returned output. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, nonce not set or already completed). |
| PSA_ERROR_BUFFER_TOO_SMALL | The size of the output buffer is too small. |
| 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_TAMPERING_DETECTED |
| 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:
If this function returns an error status, the operation becomes inactive.
| [in,out] | operation | Active AEAD operation. |
| [in] | input | Buffer containing the fragment of additional data. |
| input_length | Size of the input buffer in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, nonce not set, psa_aead_update() already called, or operation already completed). |
| 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_TAMPERING_DETECTED |
| psa_status_t psa_aead_verify | ( | psa_aead_operation_t * | operation, |
| 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 authentication of the additional data formed by concatenating the inputs passed to preceding calls to psa_aead_update_ad() with the ciphertext formed by concatenating the inputs passed to preceding calls to psa_aead_update().
When this function returns, the operation becomes inactive.
| [in,out] | operation | Active AEAD operation. |
| [in] | tag | Buffer containing the authentication tag. |
| tag_length | Size of the tag buffer in bytes. |
| PSA_SUCCESS | Success. |
| PSA_ERROR_BAD_STATE | The operation state is not valid (not set up, nonce not set, encryption, or already completed). |
| PSA_ERROR_BUFFER_TOO_SMALL | The size of the output buffer is too small. |
| 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_TAMPERING_DETECTED |
1.8.11