From eb1a301321830ced38759f3613db993f99b7b93c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Sz=C3=A9pk=C3=BAti?= Date: Thu, 18 Mar 2021 10:33:33 +0100 Subject: [PATCH] Update documentation references to the AEAD macros MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Where a change was necessary, the new documentation was copied from the PSA Crypto API spec exactly, with the exception of PSA_AEAD_TAG_LENGTH, which needed some adjustment. Signed-off-by: Bence Szépkúti --- include/psa/crypto.h | 109 +++++++++++++++++++++++++------------ include/psa/crypto_sizes.h | 69 ++++++++++++++++++----- 2 files changed, 129 insertions(+), 49 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 81e1f28697..98de3359e3 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -2113,9 +2113,16 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation); * authentication tag is appended to the * encrypted data. * \param ciphertext_size Size of the \p ciphertext buffer in bytes. - * This must be at least - * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg, - * \p plaintext_length). + * This must be appropriate for the selected + * algorithm and key: + * - A sufficient output size is + * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\c key_type, + * \p alg, \p plaintext_length) where + * \c key_type is the type of \p key. + * - #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p + * plaintext_length) evaluates to the maximum + * ciphertext size of any supported AEAD + * encryption. * \param[out] ciphertext_length On success, the size of the output * in the \p ciphertext buffer. * @@ -2173,9 +2180,16 @@ psa_status_t psa_aead_encrypt(mbedtls_svc_key_id_t key, * \param ciphertext_length Size of \p ciphertext in bytes. * \param[out] plaintext Output buffer for the decrypted data. * \param plaintext_size Size of the \p plaintext buffer in bytes. - * This must be at least - * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg, - * \p ciphertext_length). + * This must be appropriate for the selected + * algorithm and key: + * - A sufficient output size is + * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\c key_type, + * \p alg, \p ciphertext_length) where + * \c key_type is the type of \p key. + * - #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p + * ciphertext_length) evaluates to the maximum + * plaintext size of any supported AEAD + * decryption. * \param[out] plaintext_length On success, the size of the output * in the \p plaintext buffer. * @@ -2612,10 +2626,18 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, * \param input_length Size of the \p input buffer in bytes. * \param[out] output Buffer where the output is to be written. * \param output_size Size of the \p output buffer in bytes. - * This must be at least - * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, - * \p input_length) where \c alg is the - * algorithm that is being calculated. + * This must be appropriate for the selected + * algorithm and key: + * - A sufficient output size is + * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, + * \c alg, \p input_length) where + * \c key_type is the type of key and \c alg is + * the algorithm that were used to set up the + * operation. + * - #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p + * input_length) evaluates to the maximum + * output size of any supported AEAD + * algorithm. * \param[out] output_length On success, the number of bytes * that make up the returned output. * @@ -2626,9 +2648,9 @@ psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, * set, and have lengths set if required by the algorithm). * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p output buffer is too small. - * You can determine a sufficient buffer size by calling - * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c alg, \p input_length) - * where \c alg is the algorithm that is being calculated. + * #PSA_AEAD_UPDATE_OUTPUT_SIZE(\c key_type, \c alg, \p input_length) or + * #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length) can be used to + * determine the required buffer size. * \retval #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 @@ -2665,9 +2687,7 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation, * This function has two output buffers: * - \p ciphertext contains trailing ciphertext that was buffered from * preceding calls to psa_aead_update(). - * - \p tag contains the authentication tag. Its length is always - * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is the AEAD algorithm - * that the operation performs. + * - \p tag contains the authentication tag. * * When this function returns successfuly, the operation becomes inactive. * If this function returns an error status, the operation enters an error @@ -2677,18 +2697,32 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation, * \param[out] ciphertext Buffer where the last part of the ciphertext * is to be written. * \param ciphertext_size Size of the \p ciphertext buffer in bytes. - * This must be at least - * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) where - * \c alg is the algorithm that is being - * calculated. + * This must be appropriate for the selected + * algorithm and key: + * - A sufficient output size is + * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, + * \c alg) where \c key_type is the type of key + * and \c 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. * \param[out] ciphertext_length On success, the number of bytes of * returned ciphertext. * \param[out] tag Buffer where the authentication tag is * to be written. * \param tag_size Size of the \p tag buffer in bytes. - * This must be at least - * #PSA_AEAD_TAG_LENGTH(\c alg) where \c alg is - * the algorithm that is being calculated. + * This must be appropriate for the selected + * algorithm and key: + * - The exact tag size is #PSA_AEAD_TAG_LENGTH(\c + * key_type, \c key_bits, \c alg) where + * \c key_type and \c key_bits are the type and + * bit-size of the key, and \c 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. * \param[out] tag_length On success, the number of bytes * that make up the returned tag. * @@ -2699,11 +2733,11 @@ psa_status_t psa_aead_update(psa_aead_operation_t *operation, * operation with a nonce set). * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p ciphertext or \p tag buffer is too small. - * You can determine a sufficient buffer size for \p ciphertext by - * calling #PSA_AEAD_FINISH_OUTPUT_SIZE(\c alg) - * where \c alg is the algorithm that is being calculated. - * You can determine a sufficient buffer size for \p tag by - * calling #PSA_AEAD_TAG_LENGTH(\c alg). + * #PSA_AEAD_FINISH_OUTPUT_SIZE(\c key_type, \c alg) or + * #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the + * required \p ciphertext buffer size. #PSA_AEAD_TAG_LENGTH(\c key_type, + * \c key_bits, \c alg) or #PSA_AEAD_TAG_MAX_SIZE can be used to + * determine the required \p tag buffer size. * \retval #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 @@ -2762,10 +2796,15 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation, * that could not be processed until the end * of the input. * \param plaintext_size Size of the \p plaintext buffer in bytes. - * This must be at least - * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) where - * \c alg is the algorithm that is being - * calculated. + * This must be appropriate for the selected algorithm and key: + * - A sufficient output size is + * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type, + * \c alg) where \c key_type is the type of key + * and \c 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. * \param[out] plaintext_length On success, the number of bytes of * returned plaintext. * \param[in] tag Buffer containing the authentication tag. @@ -2781,9 +2820,9 @@ psa_status_t psa_aead_finish(psa_aead_operation_t *operation, * operation with a nonce set). * \retval #PSA_ERROR_BUFFER_TOO_SMALL * The size of the \p plaintext buffer is too small. - * You can determine a sufficient buffer size for \p plaintext by - * calling #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c alg) - * where \c alg is the algorithm that is being calculated. + * #PSA_AEAD_VERIFY_OUTPUT_SIZE(\c key_type, \c alg) or + * #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine the + * required buffer size. * \retval #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 diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index 10151c6afd..e4c5a36276 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -117,17 +117,26 @@ */ #define PSA_MAC_MAX_SIZE PSA_HASH_MAX_SIZE -/** The tag size for an AEAD algorithm, in bytes. +/** The length of a tag for an AEAD algorithm, in bytes. * + * This macro can be used to allocate a buffer of sufficient size to store the + * tag output from psa_aead_finish(). + * + * See also #PSA_AEAD_TAG_MAX_SIZE. + * + * \param key_type The type of the AEAD key. + * \param key_bits The size of the AEAD key in bits. * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). * - * \return The tag size for the specified algorithm. + * \return The tag size 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. + * If the key type or AEAD algorithm is not + * recognized, or the parameters are incompatible, + * return 0. */ #define PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) \ (PSA_AEAD_NONCE_LENGTH(key_type, alg) ? \ @@ -136,7 +145,7 @@ /** The maximum tag size for all supported AEAD algorithms, in bytes. * - * See also #PSA_AEAD_TAG_LENGTH(\p alg). + * See also #PSA_AEAD_TAG_LENGTH(\p key_type, \p key_bits, \p alg). */ #define PSA_AEAD_TAG_MAX_SIZE 16 @@ -241,10 +250,14 @@ * insufficient buffer size. Depending on the algorithm, the actual size of * the ciphertext may be smaller. * + * See also #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length). + * * \warning This macro may evaluate its arguments multiple times or * zero times, so you should not pass arguments that contain * side effects. * + * \param key_type A symmetric key type that is + * compatible with algorithm \p alg. * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). @@ -252,7 +265,9 @@ * * \return The AEAD ciphertext size for the specified * algorithm. - * If the AEAD algorithm is not recognized, return 0. + * If the key type or AEAD algorithm is not + * recognized, or the parameters are incompatible, + * return 0. */ #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) \ (PSA_AEAD_NONCE_LENGTH(key_type, alg) ? \ @@ -268,7 +283,8 @@ * \note This macro returns a compile-time constant if its arguments are * compile-time constants. * - * See also #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg, \p plaintext_length). + * See also #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p key_type, \p alg, + * \p plaintext_length). * * \param plaintext_length Size of the plaintext in bytes. * @@ -287,10 +303,14 @@ * insufficient buffer size. Depending on the algorithm, the actual size of * the plaintext may be smaller. * + * See also #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length). + * * \warning This macro may evaluate its arguments multiple times or * zero times, so you should not pass arguments that contain * side effects. * + * \param key_type A symmetric key type that is + * compatible with algorithm \p alg. * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). @@ -298,7 +318,9 @@ * * \return The AEAD ciphertext size for the specified * algorithm. - * If the AEAD algorithm is not recognized, return 0. + * If the key type or AEAD algorithm is not + * recognized, or the parameters are incompatible, + * return 0. */ #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \ (PSA_AEAD_NONCE_LENGTH(key_type, alg) ? \ @@ -314,7 +336,8 @@ * \note This macro returns a compile-time constant if its arguments are * compile-time constants. * - * See also #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg, \p ciphertext_length). + * See also #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p key_type, \p alg, + * \p ciphertext_length). * * \param ciphertext_length Size of the ciphertext in bytes. * @@ -379,10 +402,14 @@ * insufficient buffer size. The actual size of the output may be smaller * in any given call. * + * See also #PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(\p input_length). + * * \warning This macro may evaluate its arguments multiple times or * zero times, so you should not pass arguments that contain * side effects. * + * \param key_type A symmetric key type that is + * compatible with algorithm \p alg. * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). @@ -390,7 +417,9 @@ * * \return A sufficient output buffer size for the specified * algorithm. - * If the AEAD algorithm is not recognized, return 0. + * If the key type or AEAD algorithm is not + * recognized, or the parameters are incompatible, + * return 0. */ /* For all the AEAD modes defined in this specification, it is possible * to emit output without delay. However, hardware may not always be @@ -409,7 +438,7 @@ * 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. * - * See also #PSA_AEAD_UPDATE_OUTPUT_SIZE(\p alg, \p input_length). + * See also #PSA_AEAD_UPDATE_OUTPUT_SIZE(\p key_type, \p alg, \p input_length). * * \param input_length Size of the input in bytes. */ @@ -423,13 +452,19 @@ * insufficient ciphertext buffer size. The actual size of the output may * be smaller in any given call. * + * See also #PSA_AEAD_FINISH_OUTPUT_MAX_SIZE. + * + * \param key_type A symmetric key type that is + compatible with algorithm \p alg. * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). * * \return A sufficient ciphertext buffer size for the * specified algorithm. - * If the AEAD algorithm is not recognized, return 0. + * If the key type or AEAD algorithm is not + * recognized, or the parameters are incompatible, + * return 0. */ #define PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) \ (PSA_AEAD_NONCE_LENGTH(key_type, alg) && PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \ @@ -439,7 +474,7 @@ /** A sufficient ciphertext buffer size for psa_aead_finish(), for any of the * supported key types and AEAD algorithms. * - * See also #PSA_AEAD_FINISH_OUTPUT_SIZE(\p alg). + * See also #PSA_AEAD_FINISH_OUTPUT_SIZE(\p key_type, \p alg). */ #define PSA_AEAD_FINISH_OUTPUT_MAX_SIZE (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE) @@ -450,13 +485,19 @@ * insufficient plaintext buffer size. The actual size of the output may * be smaller in any given call. * + * See also #PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE. + * + * \param key_type A symmetric key type that is + * compatible with algorithm \p alg. * \param alg An AEAD algorithm * (\c PSA_ALG_XXX value such that * #PSA_ALG_IS_AEAD(\p alg) is true). * * \return A sufficient plaintext buffer size for the * specified algorithm. - * If the AEAD algorithm is not recognized, return 0. + * If the key type or AEAD algorithm is not + * recognized, or the parameters are incompatible, + * return 0. */ #define PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) \ (PSA_AEAD_NONCE_LENGTH(key_type, alg) && PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \ @@ -466,7 +507,7 @@ /** A sufficient plaintext buffer size for psa_aead_verify(), for any of the * supported key types and AEAD algorithms. * - * See also #PSA_AEAD_VERIFY_OUTPUT_SIZE(\p alg). + * See also #PSA_AEAD_VERIFY_OUTPUT_SIZE(\p key_type, \p alg). */ #define PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE (PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE)