Platform Security Architecture — cryptography and keystore interface  Working draft
Macros | Functions
Authenticated encryption with associated data (AEAD)

Macros

#define PSA_AEAD_TAG_SIZE(alg)
 

Functions

psa_status_t psa_aead_encrypt (psa_key_slot_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)
 
psa_status_t psa_aead_decrypt (psa_key_slot_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)
 

Detailed Description

Macro Definition Documentation

◆ PSA_AEAD_TAG_SIZE

#define PSA_AEAD_TAG_SIZE (   alg)
Value:
((alg) == PSA_ALG_GCM ? 16 : \
(alg) == PSA_ALG_CCM ? 16 : \
0)

The tag size for an AEAD algorithm, in bytes.

Parameters
algAn AEAD algorithm (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
Returns
The tag size for the specified algorithm. 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 may return either 0 or a correct size for an AEAD algorithm that it recognizes, but does not support.

Function Documentation

◆ psa_aead_decrypt()

psa_status_t psa_aead_decrypt ( psa_key_slot_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 
)

Process an authenticated decryption operation.

Parameters
keySlot containing the key to use.
algThe AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
[in]nonceNonce or IV to use.
nonce_lengthSize of the nonce buffer in bytes.
[in]additional_dataAdditional data that has been authenticated but not encrypted.
additional_data_lengthSize of additional_data in bytes.
[in]ciphertextData 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_lengthSize of ciphertext in bytes.
[out]plaintextOutput buffer for the decrypted data.
plaintext_sizeSize of the plaintext buffer in bytes. This must be at least PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length).
[out]plaintext_lengthOn success, the size of the output in the plaintext buffer.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_INVALID_SIGNATUREThe ciphertext is not authentic.
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTkey is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg 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_aead_encrypt()

psa_status_t psa_aead_encrypt ( psa_key_slot_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 
)

Process an authenticated encryption operation.

Parameters
keySlot containing the key to use.
algThe AEAD algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_AEAD(alg) is true).
[in]nonceNonce or IV to use.
nonce_lengthSize of the nonce buffer in bytes.
[in]additional_dataAdditional data that will be authenticated but not encrypted.
additional_data_lengthSize of additional_data in bytes.
[in]plaintextData that will be authenticated and encrypted.
plaintext_lengthSize of plaintext in bytes.
[out]ciphertextOutput 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_sizeSize of the ciphertext buffer in bytes. This must be at least PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length).
[out]ciphertext_lengthOn success, the size of the output in the ciphertext buffer.
Return values
PSA_SUCCESSSuccess.
PSA_ERROR_EMPTY_SLOT
PSA_ERROR_NOT_PERMITTED
PSA_ERROR_INVALID_ARGUMENTkey is not compatible with alg.
PSA_ERROR_NOT_SUPPORTEDalg 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