Rename output buffer size macros
Rename existing support macros for output buffer sizes for PSA Crypto API 1.0.0
Signed-off-by: gabor-mezei-arm <gabor.mezei@arm.com>
diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h
index 3df01b2..001e628 100644
--- a/include/psa/crypto_sizes.h
+++ b/include/psa/crypto_sizes.h
@@ -68,8 +68,8 @@
* An implementation may return either 0 or the correct size
* for a hash algorithm that it recognizes, but does not support.
*/
-#define PSA_HASH_SIZE(alg) \
- ( \
+#define PSA_HASH_LENGTH(alg) \
+ ( \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD2 ? 16 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD4 ? 16 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_MD5 ? 16 : \
@@ -188,10 +188,10 @@
#define PSA_VENDOR_ECC_MAX_CURVE_BITS 0
#endif
-/** \def PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN
- *
- * This macro returns the maximum length of the PSK supported
- * by the TLS-1.2 PSK-to-MS key derivation.
+/** This macro returns the maximum length of the PSK supported
+ * by the TLS-1.2 PSK-to-MS key derivation
+ * (#PSA_ALG_TLS12_PSK_TO_MS(\p hash_alg)). It is independent from the
+ * choice of hash algorithms.
*
* Quoting RFC 4279, Sect 5.3:
* TLS implementations supporting these ciphersuites MUST support
@@ -200,17 +200,21 @@
* keys is RECOMMENDED.
*
* Therefore, no implementation should define a value smaller than 64
- * for #PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN.
+ * for #PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE.
*/
-#define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN 128
+#define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE 128
/** The maximum size of a block cipher supported by the implementation. */
-#define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE 16
+#define PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE 16
/** The size of the output of psa_mac_sign_finish(), in bytes.
*
* This is also the MAC size that psa_mac_verify_finish() expects.
*
+ * \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 The type of the MAC key.
* \param key_bits The size of the MAC key in bits.
* \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
@@ -224,10 +228,10 @@
* \return Unspecified if the key parameters are not consistent
* with the algorithm.
*/
-#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
- ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
- PSA_ALG_IS_HMAC(alg) ? PSA_HASH_SIZE(PSA_ALG_HMAC_GET_HASH(alg)) : \
- PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
+#define PSA_MAC_LENGTH(key_type, key_bits, alg) \
+ ((alg) & PSA_ALG_MAC_TRUNCATION_MASK ? PSA_MAC_TRUNCATED_LENGTH(alg) : \
+ PSA_ALG_IS_HMAC(alg) ? PSA_HASH_LENGTH(PSA_ALG_HMAC_GET_HASH(alg)) : \
+ PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
((void)(key_type), (void)(key_bits), 0))
/** The maximum size of the output of psa_aead_encrypt(), in bytes.
@@ -326,7 +330,7 @@
*/
#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg) \
(PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
- PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE : \
+ PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
0)
/** A sufficient plaintext buffer size for psa_aead_verify().
@@ -349,12 +353,12 @@
*/
#define PSA_AEAD_VERIFY_OUTPUT_SIZE(alg) \
(PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
- PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE : \
+ PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
0)
#define PSA_RSA_MINIMUM_PADDING_SIZE(alg) \
(PSA_ALG_IS_RSA_OAEP(alg) ? \
- 2 * PSA_HASH_SIZE(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
+ 2 * PSA_HASH_LENGTH(PSA_ALG_RSA_OAEP_GET_HASH(alg)) + 1 : \
11 /*PKCS#1v1.5*/)
/**
@@ -587,12 +591,12 @@
#define PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) \
(PSA_BITS_TO_BYTES(key_bits))
-/** Sufficient output buffer size for psa_export_key() or psa_export_public_key().
+/** Sufficient output buffer size for psa_export_key().
*
* This macro returns a compile-time constant if its arguments are
* compile-time constants.
*
- * \warning This function may call its arguments multiple times or
+ * \warning This macro may evaluate its arguments multiple times or
* zero times, so you should not pass arguments that contain
* side effects.
*
@@ -605,7 +609,7 @@
* if (status != PSA_SUCCESS) handle_error(...);
* psa_key_type_t key_type = psa_get_key_type(&attributes);
* size_t key_bits = psa_get_key_bits(&attributes);
- * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits);
+ * size_t buffer_size = PSA_EXPORT_KEY_OUTPUT_SIZE(key_type, key_bits);
* psa_reset_key_attributes(&attributes);
* uint8_t *buffer = malloc(buffer_size);
* if (buffer == NULL) handle_error(...);
@@ -614,32 +618,12 @@
* if (status != PSA_SUCCESS) handle_error(...);
* \endcode
*
- * For psa_export_public_key(), calculate the buffer size from the
- * public key type. You can use the macro #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR
- * to convert a key pair type to the corresponding public key type.
- * \code{c}
- * psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
- * psa_status_t status;
- * status = psa_get_key_attributes(key, &attributes);
- * if (status != PSA_SUCCESS) handle_error(...);
- * psa_key_type_t key_type = psa_get_key_type(&attributes);
- * psa_key_type_t public_key_type = PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(key_type);
- * size_t key_bits = psa_get_key_bits(&attributes);
- * size_t buffer_size = PSA_KEY_EXPORT_MAX_SIZE(public_key_type, key_bits);
- * psa_reset_key_attributes(&attributes);
- * uint8_t *buffer = malloc(buffer_size);
- * if (buffer == NULL) handle_error(...);
- * size_t buffer_length;
- * status = psa_export_public_key(key, buffer, buffer_size, &buffer_length);
- * if (status != PSA_SUCCESS) handle_error(...);
- * \endcode
- *
* \param key_type A supported key type.
* \param key_bits The size of the key in bits.
*
* \return If the parameters are valid and supported, return
* a buffer size in bytes that guarantees that
- * psa_sign_hash() will not fail with
+ * psa_export_key() will not fail with
* #PSA_ERROR_BUFFER_TOO_SMALL.
* If the parameters are a valid combination that is not supported
* by the implementation, this macro shall return either a
@@ -647,14 +631,14 @@
* If the parameters are not valid, the
* return value is unspecified.
*/
-#define PSA_KEY_EXPORT_MAX_SIZE(key_type, key_bits) \
- (PSA_KEY_TYPE_IS_UNSTRUCTURED(key_type) ? PSA_BITS_TO_BYTES(key_bits) : \
- (key_type) == PSA_KEY_TYPE_RSA_KEY_PAIR ? PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(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) : \
+ (key_type) == PSA_KEY_TYPE_RSA_KEY_PAIR ? PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE(key_bits) : \
(key_type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY ? PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
- (key_type) == PSA_KEY_TYPE_DSA_KEY_PAIR ? PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) : \
+ (key_type) == PSA_KEY_TYPE_DSA_KEY_PAIR ? PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE(key_bits) : \
(key_type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY ? PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE(key_bits) : \
- PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) : \
- PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
+ PSA_KEY_TYPE_IS_ECC_KEY_PAIR(key_type) ? PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE(key_bits) : \
+ PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(key_type) ? PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE(key_bits) : \
0)
/** The default nonce size for an AEAD algorithm, in bytes.
@@ -727,13 +711,13 @@
* and cipher algorithm that it recognizes, but does not support.
*/
#define PSA_CIPHER_IV_LENGTH(key_type, alg) \
- (PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) > 1 && \
+ (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) > 1 && \
((alg) == PSA_ALG_CTR || \
(alg) == PSA_ALG_CFB || \
(alg) == PSA_ALG_OFB || \
(alg) == PSA_ALG_XTS || \
(alg) == PSA_ALG_CBC_NO_PADDING || \
- (alg) == PSA_ALG_CBC_PKCS7) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
+ (alg) == PSA_ALG_CBC_PKCS7) ? PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
(key_type) == PSA_KEY_TYPE_CHACHA20 && \
(alg) == PSA_ALG_STREAM_CIPHER ? 12 : \
0)