yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Fix documentation

Browse source 
Signed-off-by: gabor-mezei-arm <gabor.mezei@arm.com>
This commit is contained in:
gabor-mezei-arm 2021-02-15 15:56:29 +01:00
parent ceface2247
commit c6f2480854
No known key found for this signature in database
GPG key ID: 106F5A41ECC305BD
1 changed files with 39 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

121
include/psa/crypto_sizes.h
View file

@ -65,8 +65,6 @@
* *
* \return The hash size for the specified hash algorithm. * \return The hash size for the specified hash algorithm.
* If the hash algorithm is not recognized, return 0. * If the hash algorithm is not recognized, return 0.
* An implementation may return either 0 or the correct size
* for a hash algorithm that it recognizes, but does not support.
*/ */
#define PSA_HASH_LENGTH(alg) \ #define PSA_HASH_LENGTH(alg) \
( \ ( \
@ -91,9 +89,8 @@
* *
* Maximum size of a hash. * Maximum size of a hash.
* *
* This macro must expand to a compile-time constant integer. This value * This macro expands to a compile-time constant integer. This value
* should be the maximum size of a hash supported by the implementation, * is the maximum size of a hash in bytes.
* in bytes, and must be no smaller than this maximum.
*/ */
/* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226, /* Note: for HMAC-SHA-3, the block size is 144 bytes for HMAC-SHA3-226,
* 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for * 136 bytes for HMAC-SHA3-256, 104 bytes for SHA3-384, 72 bytes for
@ -110,9 +107,8 @@
* *
* Maximum size of a MAC. * Maximum size of a MAC.
* *
* This macro must expand to a compile-time constant integer. This value * This macro expands to a compile-time constant integer. This value
* should be the maximum size of a MAC supported by the implementation, * is the maximum size of a MAC in bytes.
* in bytes, and must be no smaller than this maximum.
*/ */
/* All non-HMAC MACs have a maximum size that's smaller than the /* All non-HMAC MACs have a maximum size that's smaller than the
* minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */ * minimum possible value of PSA_HASH_MAX_SIZE in this implementation. */
@ -132,9 +128,6 @@
* tag that can be distinguished from the rest of * tag that can be distinguished from the rest of
* the ciphertext, return 0. * the ciphertext, return 0.
* If the AEAD algorithm is not recognized, 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.
*/ */
#define PSA_AEAD_TAG_LENGTH(alg) \ #define PSA_AEAD_TAG_LENGTH(alg) \
(PSA_ALG_IS_AEAD(alg) ? \ (PSA_ALG_IS_AEAD(alg) ? \
@ -211,7 +204,7 @@
*/ */
#define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE 128 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE 128
/** The maximum size of a block cipher supported by the implementation. */ /** The maximum size of a block cipher. */
#define PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE 16 #define PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE 16
/** The size of the output of psa_mac_sign_finish(), in bytes. /** The size of the output of psa_mac_sign_finish(), in bytes.
@ -260,9 +253,6 @@
* \return The AEAD ciphertext size for the specified * \return The AEAD ciphertext size for the specified
* algorithm. * algorithm.
* If the AEAD algorithm is not recognized, 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.
*/ */
#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \ #define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
(PSA_AEAD_TAG_LENGTH(alg) != 0 ? \ (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
@ -309,9 +299,6 @@
* \return The AEAD ciphertext size for the specified * \return The AEAD ciphertext size for the specified
* algorithm. * algorithm.
* If the AEAD algorithm is not recognized, 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.
*/ */
#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \ #define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
(PSA_AEAD_TAG_LENGTH(alg) != 0 ? \ (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
@ -324,6 +311,9 @@
* If the size of the plaintext buffer is at least this large, it is guaranteed * 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. * that psa_aead_decrypt() will not fail due to an insufficient buffer size.
* *
* \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 alg, \p ciphertext_length).
* *
* \param ciphertext_length Size of the ciphertext in bytes. * \param ciphertext_length Size of the ciphertext in bytes.
@ -359,8 +349,6 @@
* \return The default nonce size for the specified key type and algorithm. * \return The default nonce size for the specified key type and algorithm.
* If the key type or AEAD algorithm is not recognized, * If the key type or AEAD algorithm is not recognized,
* or the parameters are incompatible, return 0. * 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.
*/ */
#define PSA_AEAD_NONCE_LENGTH(key_type, alg) \ #define PSA_AEAD_NONCE_LENGTH(key_type, alg) \
(PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) == 16 && \ (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) == 16 && \
@ -402,9 +390,6 @@
* \return A sufficient output buffer size for the specified * \return A sufficient output buffer size for the specified
* algorithm. * algorithm.
* If the AEAD algorithm is not recognized, 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.
*/ */
/* For all the AEAD modes defined in this specification, it is possible /* For all the AEAD modes defined in this specification, it is possible
* to emit output without delay. However, hardware may not always be * to emit output without delay. However, hardware may not always be
@ -442,9 +427,6 @@
* \return A sufficient ciphertext buffer size for the * \return A sufficient ciphertext buffer size for the
* specified algorithm. * specified algorithm.
* If the AEAD algorithm is not recognized, 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.
*/ */
#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg) \ #define PSA_AEAD_FINISH_OUTPUT_SIZE(alg) \
(PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \ (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
@ -472,9 +454,6 @@
* \return A sufficient plaintext buffer size for the * \return A sufficient plaintext buffer size for the
* specified algorithm. * specified algorithm.
* If the AEAD algorithm is not recognized, 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.
*/ */
#define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg) \ #define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg) \
(PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \ (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
@ -524,9 +503,8 @@
* a buffer size in bytes that guarantees that * a buffer size in bytes that guarantees that
* psa_sign_hash() will not fail with * psa_sign_hash() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL. * #PSA_ERROR_BUFFER_TOO_SMALL.
* If the parameters are a valid combination that is not supported * If the parameters are a valid combination that is not supported,
* by the implementation, this macro shall return either a * return either a sensible size or 0.
* sensible size or 0.
* If the parameters are not valid, the * If the parameters are not valid, the
* return value is unspecified. * return value is unspecified.
*/ */
@ -542,9 +520,8 @@
* *
* Maximum size of an asymmetric signature. * Maximum size of an asymmetric signature.
* *
* This macro must expand to a compile-time constant integer. This value * This macro expands to a compile-time constant integer. This value
* should be the maximum size of a signature supported by the implementation, * is the maximum size of a signature in bytes.
* in bytes, and must be no smaller than this maximum.
*/ */
#define PSA_SIGNATURE_MAX_SIZE \ #define PSA_SIGNATURE_MAX_SIZE \
(PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) > PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE ? \ (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS) > PSA_VENDOR_ECDSA_SIGNATURE_MAX_SIZE ? \
@ -571,9 +548,8 @@
* a buffer size in bytes that guarantees that * a buffer size in bytes that guarantees that
* psa_asymmetric_encrypt() will not fail with * psa_asymmetric_encrypt() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL. * #PSA_ERROR_BUFFER_TOO_SMALL.
* If the parameters are a valid combination that is not supported * If the parameters are a valid combination that is not supported,
* by the implementation, this macro shall return either a * return either a sensible size or 0.
* sensible size or 0.
* If the parameters are not valid, the * If the parameters are not valid, the
* return value is unspecified. * return value is unspecified.
*/ */
@ -585,10 +561,9 @@
/** A sufficient output buffer size for psa_asymmetric_encrypt(), for any /** A sufficient output buffer size for psa_asymmetric_encrypt(), for any
* supported asymmetric encryption. * supported asymmetric encryption.
* *
* This macro assumes that RSA is the only supported asymmetric encryption.
*
* See also #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\p key_type, \p key_bits, \p alg). * See also #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(\p key_type, \p key_bits, \p alg).
*/ */
/* This macro assumes that RSA is the only supported asymmetric encryption. */
#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE \ #define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE \
(PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS)) (PSA_BITS_TO_BYTES(PSA_VENDOR_RSA_MAX_KEY_BITS))
@ -612,9 +587,8 @@
* a buffer size in bytes that guarantees that * a buffer size in bytes that guarantees that
* psa_asymmetric_decrypt() will not fail with * psa_asymmetric_decrypt() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL. * #PSA_ERROR_BUFFER_TOO_SMALL.
* If the parameters are a valid combination that is not supported * If the parameters are a valid combination that is not supported,
* by the implementation, this macro shall return either a * return either a sensible size or 0.
* sensible size or 0.
* If the parameters are not valid, the * If the parameters are not valid, the
* return value is unspecified. * return value is unspecified.
*/ */
@ -778,11 +752,9 @@
* a buffer size in bytes that guarantees that * a buffer size in bytes that guarantees that
* psa_export_key() or psa_export_public_key() will not fail with * psa_export_key() or psa_export_public_key() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL. * #PSA_ERROR_BUFFER_TOO_SMALL.
* If the parameters are a valid combination that is not supported * If the parameters are a valid combination that is not supported,
* by the implementation, this macro shall return either a * return either a sensible size or 0.
* sensible size or 0. * If the parameters are not valid, the return value is unspecified.
* If the parameters are not valid, the
* return value is unspecified.
*/ */
#define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \ #define PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits) \
(PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \ (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
@ -827,15 +799,14 @@
* \return If the parameters are valid and supported, return * \return If the parameters are valid and supported, return
* a buffer size in bytes that guarantees that * a buffer size in bytes that guarantees that
* psa_export_public_key() will not fail with * psa_export_public_key() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are * #PSA_ERROR_BUFFER_TOO_SMALL.
* a valid combination that is not supported by the * If the parameters are a valid combination that is not
* implementation, this macro must return either * supported, return either a sensible size or 0.
* a sensible size or 0. If the parameters are not valid, * If the parameters are not valid,
* the return value is unspecified. * the return value is unspecified.
* *
* If the parameters are valid and supported, * If the parameters are valid and supported,
* it is recommended that this macro returns the same * return the same result as
* result as
* #PSA_EXPORT_KEY_OUTPUT_SIZE( * #PSA_EXPORT_KEY_OUTPUT_SIZE(
* \p #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\p key_type), * \p #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(\p key_type),
* \p key_bits). * \p key_bits).
@ -847,10 +818,9 @@
/** Sufficient buffer size for exporting any asymmetric key pair. /** Sufficient buffer size for exporting any asymmetric key pair.
* *
* This macro must expand to a compile-time constant integer. This value must * This macro expands to a compile-time constant integer. This value is
* be a sufficient buffer size when calling psa_export_key() to export any * a sufficient buffer size when calling psa_export_key() to export any
* asymmetric key pair that is supported by the implementation, regardless of * asymmetric key pair, regardless of the exact key type and key size.
* the exact key type and key size.
* *
* See also #PSA_EXPORT_KEY_OUTPUT_SIZE(\p key_type, \p key_bits). * See also #PSA_EXPORT_KEY_OUTPUT_SIZE(\p key_type, \p key_bits).
*/ */
@ -862,11 +832,10 @@
/** Sufficient buffer size for exporting any asymmetric public key. /** Sufficient buffer size for exporting any asymmetric public key.
* *
* This macro must expand to a compile-time constant integer. This value must * This macro expands to a compile-time constant integer. This value is
* be a sufficient buffer size when calling psa_export_key() or * a sufficient buffer size when calling psa_export_key() or
* psa_export_public_key() to export any asymmetric public key that is * psa_export_public_key() to export any asymmetric public key,
* supported by the implementation, regardless of the exact key type and key * regardless of the exact key type and key size.
* size.
* *
* See also #PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(\p key_type, \p key_bits). * See also #PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE(\p key_type, \p key_bits).
*/ */
@ -893,10 +862,10 @@
* \return If the parameters are valid and supported, return * \return If the parameters are valid and supported, return
* a buffer size in bytes that guarantees that * a buffer size in bytes that guarantees that
* psa_raw_key_agreement() will not fail with * psa_raw_key_agreement() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL. If the parameters are * #PSA_ERROR_BUFFER_TOO_SMALL.
* a valid combination that is not supported by * If the parameters are a valid combination that
* the implementation, this macro must return either * is not supported, return either a sensible size or 0.
* a sensible size or 0. If the parameters are not valid, * If the parameters are not valid,
* the return value is unspecified. * the return value is unspecified.
*/ */
/* FFDH is not yet supported in PSA. */ /* FFDH is not yet supported in PSA. */
@ -907,10 +876,8 @@
/** Maximum size of the output from psa_raw_key_agreement(). /** Maximum size of the output from psa_raw_key_agreement().
* *
* This macro must expand to a compile-time constant integer. It is recommended * This macro expands to a compile-time constant integer. This value is the
* that this value is the maximum size of the output any raw key agreement * maximum size of the output any raw key agreement algorithm, in bytes.
* algorithm supported by the implementation, in bytes. The value must not be
* smaller than this maximum.
* *
* See also #PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(\p key_type, \p key_bits). * See also #PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(\p key_type, \p key_bits).
*/ */
@ -940,8 +907,6 @@
* If the algorithm does not use an IV, return 0. * If the algorithm does not use an IV, return 0.
* If the key type or cipher algorithm is not recognized, * If the key type or cipher algorithm is not recognized,
* or the parameters are incompatible, return 0. * or the parameters are incompatible, return 0.
* An implementation can return either 0 or a correct size for a key type
* and cipher algorithm that it recognizes, but does not support.
*/ */
#define PSA_CIPHER_IV_LENGTH(key_type, alg) \ #define PSA_CIPHER_IV_LENGTH(key_type, alg) \
(PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) > 1 && \ (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) > 1 && \
@ -1025,9 +990,7 @@
* \return A sufficient output size for the specified key type and * \return A sufficient output size for the specified key type and
* algorithm. If the key type or cipher algorithm is not * algorithm. If the key type or cipher algorithm is not
* recognized, or the parameters are incompatible, * recognized, or the parameters are incompatible,
* return 0. An implementation can return either 0 or * return 0.
* a correct size for a key type and cipher algorithm
* that it recognizes, but does not support.
*/ */
#define PSA_CIPHER_DECRYPT_OUTPUT_SIZE(key_type, alg, input_length) \ #define PSA_CIPHER_DECRYPT_OUTPUT_SIZE(key_type, alg, input_length) \
(PSA_ALG_IS_CIPHER(alg) && \ (PSA_ALG_IS_CIPHER(alg) && \
@ -1065,9 +1028,6 @@
* \return A sufficient output size for the specified key type and * \return A sufficient output size for the specified key type and
* algorithm. If the key type or cipher algorithm is not * algorithm. If the key type or cipher algorithm is not
* recognized, or the parameters are incompatible, return 0. * recognized, or the parameters are incompatible, return 0.
* An implementation can return either 0 or a correct size
* for a key type and cipher algorithm that it recognizes,
* but does not support.
*/ */
#define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \ #define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
(PSA_ALG_IS_CIPHER(alg) ? \ (PSA_ALG_IS_CIPHER(alg) ? \
@ -1108,9 +1068,6 @@
* \return A sufficient output size for the specified key type and * \return A sufficient output size for the specified key type and
* algorithm. If the key type or cipher algorithm is not * algorithm. If the key type or cipher algorithm is not
* recognized, or the parameters are incompatible, return 0. * recognized, or the parameters are incompatible, return 0.
* An implementation can return either 0 or a correct size
* for a key type and cipher algorithm that it recognizes,
* but does not support.
*/ */
#define PSA_CIPHER_FINISH_OUTPUT_SIZE(key_type, alg) \ #define PSA_CIPHER_FINISH_OUTPUT_SIZE(key_type, alg) \
(PSA_ALG_IS_CIPHER(alg) ? \ (PSA_ALG_IS_CIPHER(alg) ? \