aboutsummaryrefslogtreecommitdiff
path: root/interface/include
diff options
context:
space:
mode:
authorSummer Qin <summer.qin@arm.com>2021-07-05 18:11:50 +0800
committerKen Liu <ken.liu@arm.com>2021-07-21 09:22:38 +0200
commit359167d3a2fe109adb9fae3a086864489fdc1005 (patch)
tree5771dce1c2764d8b54848c04edca93d0bf92972b /interface/include
parented503e125fd3f6fcb7b7d2f820b7b6b064f61ebe (diff)
downloadtrusted-firmware-m-359167d3a2fe109adb9fae3a086864489fdc1005.tar.gz
Crypto: Upgrade mbedtls to v3.0.0
- Remove deprecated macros and functions - Enable SHA-224 cryptographic hash algorithm by 'define MBEDTLS_SHA224_C' - Enable SHA-384 cryptographic hash algorithm by 'define MBEDTLS_SHA384_C' - 'psa_cipher_encrypt' and 'psa_cipher_decrypt' is supported by mbedtls-3.0.0 - 'psa_mac_compute' and 'psa_mac_verify' is supported by mbedtls-3.0.0 - mbedtls-3.0.0 changes some internal mbedtls apis' name, mcuboot needs to align. Change-Id: Ia868c93deceee6c8042607acf35ce2f4c9c15e35 Signed-off-by: Summer Qin <summer.qin@arm.com>
Diffstat (limited to 'interface/include')
-rw-r--r--interface/include/psa/crypto.h560
-rw-r--r--interface/include/psa/crypto_compat.h211
-rw-r--r--interface/include/psa/crypto_sizes.h135
-rw-r--r--interface/include/psa/crypto_values.h446
4 files changed, 933 insertions, 419 deletions
diff --git a/interface/include/psa/crypto.h b/interface/include/psa/crypto.h
index 0099baab7d..5ccc5e7889 100644
--- a/interface/include/psa/crypto.h
+++ b/interface/include/psa/crypto.h
@@ -95,18 +95,6 @@ psa_status_t psa_crypto_init(void);
* @{
*/
-/** \def PSA_KEY_ATTRIBUTES_INIT
- *
- * This macro returns a suitable initializer for a key attribute structure
- * of type #psa_key_attributes_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_KEY_ATTRIBUTES_INIT {0}
-#endif
-
/** Return an initial value for a key attributes structure.
*/
static psa_key_attributes_t psa_key_attributes_init(void);
@@ -677,6 +665,8 @@ psa_status_t psa_import_key(const psa_key_attributes_t *attributes,
* For Weierstrass curves, this is the content of the `privateKey` field of
* the `ECPrivateKey` format defined by RFC 5915. For Montgomery curves,
* the format is defined by RFC 7748, and output is masked according to §5.
+ * For twisted Edwards curves, the private key is as defined by RFC 8032
+ * (a 32-byte string for Edwards25519, a 57-byte string for Edwards448).
* - For Diffie-Hellman key exchange key pairs (key types for which
* #PSA_KEY_TYPE_IS_DH_KEY_PAIR is true), the
* format is the representation of the private key `x` as a big-endian byte
@@ -742,7 +732,12 @@ psa_status_t psa_export_key(psa_key_id_t key,
* modulus INTEGER, -- n
* publicExponent INTEGER } -- e
* ```
- * - For elliptic curve public keys (key types for which
+ * - For elliptic curve keys on a twisted Edwards curve (key types for which
+ * #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true and #PSA_KEY_TYPE_ECC_GET_FAMILY
+ * returns #PSA_ECC_FAMILY_TWISTED_EDWARDS), the public key is as defined
+ * by RFC 8032
+ * (a 32-byte string for Edwards25519, a 57-byte string for Edwards448).
+ * - For other elliptic curve public keys (key types for which
* #PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY is true), the format is the uncompressed
* representation defined by SEC1 &sect;2.3.3 as the content of an ECPoint.
* Let `m` be the bit size associated with the curve, i.e. the bit size of
@@ -899,22 +894,10 @@ psa_status_t psa_hash_compare(psa_algorithm_t alg,
* \endcode
*
* This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure except
- * as directed by the documentation of a specific implementation. */
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice. */
typedef struct psa_hash_operation_s psa_hash_operation_t;
-/** \def PSA_HASH_OPERATION_INIT
- *
- * This macro returns a suitable initializer for a hash operation object
- * of type #psa_hash_operation_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_HASH_OPERATION_INIT {0}
-#endif
-
/** Return an initial value for a hash operation object.
*/
static psa_hash_operation_t psa_hash_operation_init(void);
@@ -1268,23 +1251,12 @@ psa_status_t psa_mac_verify(psa_key_id_t key,
* operation = psa_mac_operation_init();
* \endcode
*
+ *
* This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure except
- * as directed by the documentation of a specific implementation. */
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice. */
typedef struct psa_mac_operation_s psa_mac_operation_t;
-/** \def PSA_MAC_OPERATION_INIT
- *
- * This macro returns a suitable initializer for a MAC operation object of type
- * #psa_mac_operation_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_MAC_OPERATION_INIT {0}
-#endif
-
/** Return an initial value for a MAC operation object.
*/
static psa_mac_operation_t psa_mac_operation_init(void);
@@ -1693,22 +1665,10 @@ psa_status_t psa_cipher_decrypt(psa_key_id_t key,
* \endcode
*
* This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure except
- * as directed by the documentation of a specific implementation. */
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice. */
typedef struct psa_cipher_operation_s psa_cipher_operation_t;
-/** \def PSA_CIPHER_OPERATION_INIT
- *
- * This macro returns a suitable initializer for a cipher operation object of
- * type #psa_cipher_operation_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_CIPHER_OPERATION_INIT {0}
-#endif
-
/** Return an initial value for a cipher operation object.
*/
static psa_cipher_operation_t psa_cipher_operation_init(void);
@@ -2074,9 +2034,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.
*
@@ -2090,7 +2057,11 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
- * \p ciphertext_size is too small
+ * \p ciphertext_size is too small.
+ * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\c key_type, \p alg,
+ * \p plaintext_length) or
+ * #PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(\p plaintext_length) can be used to
+ * determine the required buffer size.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -2134,9 +2105,16 @@ psa_status_t psa_aead_encrypt(psa_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.
*
@@ -2152,7 +2130,11 @@ psa_status_t psa_aead_encrypt(psa_key_id_t key,
* \p alg is not supported or is not an AEAD algorithm.
* \retval #PSA_ERROR_INSUFFICIENT_MEMORY
* \retval #PSA_ERROR_BUFFER_TOO_SMALL
- * \p plaintext_size or \p nonce_length is too small
+ * \p plaintext_size is too small.
+ * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\c key_type, \p alg,
+ * \p ciphertext_length) or
+ * #PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(\p ciphertext_length) can be used
+ * to determine the required buffer size.
* \retval #PSA_ERROR_COMMUNICATION_FAILURE
* \retval #PSA_ERROR_HARDWARE_FAILURE
* \retval #PSA_ERROR_CORRUPTION_DETECTED
@@ -2200,22 +2182,10 @@ psa_status_t psa_aead_decrypt(psa_key_id_t key,
* \endcode
*
* This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure except
- * as directed by the documentation of a specific implementation. */
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice. */
typedef struct psa_aead_operation_s psa_aead_operation_t;
-/** \def PSA_AEAD_OPERATION_INIT
- *
- * This macro returns a suitable initializer for an AEAD operation object of
- * type #psa_aead_operation_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_AEAD_OPERATION_INIT {0}
-#endif
-
/** Return an initial value for an AEAD operation object.
*/
static psa_aead_operation_t psa_aead_operation_init(void);
@@ -2573,10 +2543,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.
*
@@ -2587,9 +2565,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
@@ -2626,9 +2604,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
@@ -2638,18 +2614,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.
*
@@ -2660,11 +2650,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
@@ -2723,10 +2713,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.
@@ -2742,9 +2737,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
@@ -2804,11 +2799,129 @@ psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
*/
/**
+ * \brief Sign a message with a private key. For hash-and-sign algorithms,
+ * this includes the hashing step.
+ *
+ * \note To perform a multi-part hash-and-sign signature algorithm, first use
+ * a multi-part hash operation and then pass the resulting hash to
+ * psa_sign_hash(). PSA_ALG_GET_HASH(\p alg) can be used to determine the
+ * hash algorithm to use.
+ *
+ * \param[in] key Identifier of the key to use for the operation.
+ * It must be an asymmetric key pair. The key must
+ * allow the usage #PSA_KEY_USAGE_SIGN_MESSAGE.
+ * \param[in] alg An asymmetric signature algorithm (PSA_ALG_XXX
+ * value such that #PSA_ALG_IS_SIGN_MESSAGE(\p alg)
+ * is true), that is compatible with the type of
+ * \p key.
+ * \param[in] input The input message to sign.
+ * \param[in] input_length Size of the \p input buffer in bytes.
+ * \param[out] signature Buffer where the signature is to be written.
+ * \param[in] signature_size Size of the \p signature buffer in bytes. This
+ * must be appropriate for the selected
+ * algorithm and key:
+ * - The required signature size is
+ * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
+ * where \c key_type and \c key_bits are the type and
+ * bit-size respectively of key.
+ * - #PSA_SIGNATURE_MAX_SIZE evaluates to the
+ * maximum signature size of any supported
+ * signature algorithm.
+ * \param[out] signature_length On success, the number of bytes that make up
+ * the returned signature value.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag,
+ * or it does not permit the requested algorithm.
+ * \retval #PSA_ERROR_BUFFER_TOO_SMALL
+ * The size of the \p signature buffer is too small. You can
+ * determine a sufficient buffer size by calling
+ * #PSA_SIGN_OUTPUT_SIZE(\c key_type, \c key_bits, \p alg)
+ * where \c key_type and \c key_bits are the type and bit-size
+ * respectively of \p key.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY
+ * \retval #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_sign_message( psa_key_id_t key,
+ psa_algorithm_t alg,
+ const uint8_t * input,
+ size_t input_length,
+ uint8_t * signature,
+ size_t signature_size,
+ size_t * signature_length );
+
+/** \brief Verify the signature of a message with a public key, using
+ * a hash-and-sign verification algorithm.
+ *
+ * \note To perform a multi-part hash-and-sign signature verification
+ * algorithm, first use a multi-part hash operation to hash the message
+ * and then pass the resulting hash to psa_verify_hash().
+ * PSA_ALG_GET_HASH(\p alg) can be used to determine the hash algorithm
+ * to use.
+ *
+ * \param[in] key Identifier of the key to use for the operation.
+ * It must be a public key or an asymmetric key
+ * pair. The key must allow the usage
+ * #PSA_KEY_USAGE_VERIFY_MESSAGE.
+ * \param[in] alg An asymmetric signature algorithm (PSA_ALG_XXX
+ * value such that #PSA_ALG_IS_SIGN_MESSAGE(\p alg)
+ * is true), that is compatible with the type of
+ * \p key.
+ * \param[in] input The message whose signature is to be verified.
+ * \param[in] input_length Size of the \p input buffer in bytes.
+ * \param[out] signature Buffer containing the signature to verify.
+ * \param[in] signature_length Size of the \p signature buffer in bytes.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * The key does not have the #PSA_KEY_USAGE_SIGN_MESSAGE flag,
+ * or it does not permit the requested algorithm.
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ * The calculation was performed successfully, but the passed signature
+ * is not a valid signature.
+ * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_DATA_CORRUPT
+ * \retval #PSA_ERROR_DATA_INVALID
+ * \retval #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_verify_message( psa_key_id_t key,
+ psa_algorithm_t alg,
+ const uint8_t * input,
+ size_t input_length,
+ const uint8_t * signature,
+ size_t signature_length );
+
+/**
* \brief Sign a hash or short message with a private key.
*
* Note that to perform a hash-and-sign signature algorithm, you must
* first calculate the hash by calling psa_hash_setup(), psa_hash_update()
- * and psa_hash_finish(). Then pass the resulting hash as the \p hash
+ * and psa_hash_finish(), or alternatively by calling psa_hash_compute().
+ * Then pass the resulting hash as the \p hash
* parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
* to determine the hash algorithm to use.
*
@@ -2855,11 +2968,12 @@ psa_status_t psa_sign_hash(psa_key_id_t key,
size_t *signature_length);
/**
- * \brief Verify the signature a hash or short message using a public key.
+ * \brief Verify the signature of a hash or short message using a public key.
*
* Note that to perform a hash-and-sign signature algorithm, you must
* first calculate the hash by calling psa_hash_setup(), psa_hash_update()
- * and psa_hash_finish(). Then pass the resulting hash as the \p hash
+ * and psa_hash_finish(), or alternatively by calling psa_hash_compute().
+ * Then pass the resulting hash as the \p hash
* parameter to this function. You can use #PSA_ALG_SIGN_GET_HASH(\p alg)
* to determine the hash algorithm to use.
*
@@ -3055,23 +3169,11 @@ psa_status_t psa_asymmetric_decrypt(psa_key_id_t key,
* \endcode
*
* This is an implementation-defined \c struct. Applications should not
- * make any assumptions about the content of this structure except
- * as directed by the documentation of a specific implementation.
+ * make any assumptions about the content of this structure.
+ * Implementation details can change in future versions without notice.
*/
typedef struct psa_key_derivation_s psa_key_derivation_operation_t;
-/** \def PSA_KEY_DERIVATION_OPERATION_INIT
- *
- * This macro returns a suitable initializer for a key derivation operation
- * object of type #psa_key_derivation_operation_t.
- */
-#ifdef __DOXYGEN_ONLY__
-/* This is an example definition for documentation purposes.
- * Implementations should define a suitable value in `crypto_struct.h`.
- */
-#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
-#endif
-
/** Return an initial value for a key derivation operation object.
*/
static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
@@ -3249,6 +3351,50 @@ psa_status_t psa_key_derivation_input_bytes(
const uint8_t *data,
size_t data_length);
+/** Provide a numeric input for key derivation or key agreement.
+ *
+ * Which inputs are required and in what order depends on the algorithm.
+ * However, when an algorithm requires a particular order, numeric inputs
+ * usually come first as they tend to be configuration parameters.
+ * Refer to the documentation of each key derivation or key agreement
+ * algorithm for information.
+ *
+ * This function is used for inputs which are fixed-size non-negative
+ * integers.
+ *
+ * If this function returns an error status, the operation enters an error
+ * state and must be aborted by calling psa_key_derivation_abort().
+ *
+ * \param[in,out] operation The key derivation operation object to use.
+ * It must have been set up with
+ * psa_key_derivation_setup() and must not
+ * have produced any output yet.
+ * \param step Which step the input data is for.
+ * \param[in] value The value of the numeric input.
+ *
+ * \retval #PSA_SUCCESS
+ * Success.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \c step is not compatible with the operation's algorithm.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * \c step does not allow numeric inputs.
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid for this input \p step.
+ * \retval #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_key_derivation_input_integer(
+ psa_key_derivation_operation_t *operation,
+ psa_key_derivation_step_t step,
+ uint64_t value);
+
/** Provide an input for key derivation in the form of a key.
*
* Which inputs are required and in what order depends on the algorithm.
@@ -3273,12 +3419,29 @@ psa_status_t psa_key_derivation_input_bytes(
* \param step Which step the input data is for.
* \param key Identifier of the key. It must have an
* appropriate type for step and must allow the
- * usage #PSA_KEY_USAGE_DERIVE.
+ * usage #PSA_KEY_USAGE_DERIVE or
+ * #PSA_KEY_USAGE_VERIFY_DERIVATION (see note)
+ * and the algorithm used by the operation.
+ *
+ * \note Once all inputs steps are completed, the operations will allow:
+ * - psa_key_derivation_output_bytes() if each input was either a direct input
+ * or a key with #PSA_KEY_USAGE_DERIVE set;
+ * - psa_key_derivation_output_key() if the input for step
+ * #PSA_KEY_DERIVATION_INPUT_SECRET or #PSA_KEY_DERIVATION_INPUT_PASSWORD
+ * was from a key slot with #PSA_KEY_USAGE_DERIVE and each other input was
+ * either a direct input or a key with #PSA_KEY_USAGE_DERIVE set;
+ * - psa_key_derivation_verify_bytes() if each input was either a direct input
+ * or a key with #PSA_KEY_USAGE_VERIFY_DERIVATION set;
+ * - psa_key_derivation_verify_key() under the same conditions as
+ * psa_key_derivation_verify_bytes().
*
* \retval #PSA_SUCCESS
* Success.
* \retval #PSA_ERROR_INVALID_HANDLE
* \retval #PSA_ERROR_NOT_PERMITTED
+ * The key allows neither #PSA_KEY_USAGE_DERIVE nor
+ * #PSA_KEY_USAGE_VERIFY_DERIVATION, or it doesn't allow this
+ * algorithm.
* \retval #PSA_ERROR_INVALID_ARGUMENT
* \c step is not compatible with the operation's algorithm.
* \retval #PSA_ERROR_INVALID_ARGUMENT
@@ -3391,6 +3554,9 @@ psa_status_t psa_key_derivation_key_agreement(
* \param output_length Number of bytes to output.
*
* \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * One of the inputs was a key whose policy didn't allow
+ * #PSA_KEY_USAGE_DERIVE.
* \retval #PSA_ERROR_INSUFFICIENT_DATA
* The operation's capacity was less than
* \p output_length bytes. Note that in this case,
@@ -3433,7 +3599,8 @@ psa_status_t psa_key_derivation_output_bytes(
* state and must be aborted by calling psa_key_derivation_abort().
*
* How much output is produced and consumed from the operation, and how
- * the key is derived, depends on the key type:
+ * the key is derived, depends on the key type and on the key size
+ * (denoted \c bits below):
*
* - For key types for which the key is an arbitrary sequence of bytes
* of a given size, this function is functionally equivalent to
@@ -3443,14 +3610,14 @@ psa_status_t psa_key_derivation_output_bytes(
* if the implementation provides an isolation boundary then
* the key material is not exposed outside the isolation boundary.
* As a consequence, for these key types, this function always consumes
- * exactly (\p bits / 8) bytes from the operation.
+ * exactly (\c bits / 8) bytes from the operation.
* The following key types defined in this specification follow this scheme:
*
* - #PSA_KEY_TYPE_AES;
- * - #PSA_KEY_TYPE_ARC4;
* - #PSA_KEY_TYPE_CAMELLIA;
* - #PSA_KEY_TYPE_DERIVE;
- * - #PSA_KEY_TYPE_HMAC.
+ * - #PSA_KEY_TYPE_HMAC;
+ * - #PSA_KEY_TYPE_PASSWORD_HASH.
*
* - For ECC keys on a Montgomery elliptic curve
* (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a
@@ -3464,8 +3631,8 @@ psa_status_t psa_key_derivation_output_bytes(
* string and process it as specified in RFC 7748 &sect;5.
*
* - For key types for which the key is represented by a single sequence of
- * \p bits bits with constraints as to which bit sequences are acceptable,
- * this function draws a byte string of length (\p bits / 8) bytes rounded
+ * \c bits bits with constraints as to which bit sequences are acceptable,
+ * this function draws a byte string of length (\c bits / 8) bytes rounded
* up to the nearest whole number of bytes. If the resulting byte string
* is acceptable, it becomes the key, otherwise the drawn bytes are discarded.
* This process is repeated until an acceptable byte string is drawn.
@@ -3512,6 +3679,10 @@ psa_status_t psa_key_derivation_output_bytes(
* on the derived key based on the attributes and strength of the secret key.
*
* \param[in] attributes The attributes for the new key.
+ * If the key type to be created is
+ * #PSA_KEY_TYPE_PASSWORD_HASH then the algorithm in
+ * the policy must be the same as in the current
+ * operation.
* \param[in,out] operation The key derivation operation object to read from.
* \param[out] key On success, an identifier for the newly created
* key. For persistent keys, this is the key
@@ -3536,8 +3707,10 @@ psa_status_t psa_key_derivation_output_bytes(
* \retval #PSA_ERROR_INVALID_ARGUMENT
* The provided key attributes are not valid for the operation.
* \retval #PSA_ERROR_NOT_PERMITTED
- * The #PSA_KEY_DERIVATION_INPUT_SECRET input was not provided through
- * a key.
+ * The #PSA_KEY_DERIVATION_INPUT_SECRET or
+ * #PSA_KEY_DERIVATION_INPUT_PASSWORD input was not provided through a
+ * key; or one of the inputs was a key whose policy didn't allow
+ * #PSA_KEY_USAGE_DERIVE.
* \retval #PSA_ERROR_BAD_STATE
* The operation state is not valid (it must be active and completed
* all required input steps).
@@ -3559,6 +3732,129 @@ psa_status_t psa_key_derivation_output_key(
psa_key_derivation_operation_t *operation,
psa_key_id_t *key);
+/** Compare output data from a key derivation operation to an expected value.
+ *
+ * This function calculates output bytes from a key derivation algorithm and
+ * compares those bytes to an expected value in constant time.
+ * If you view the key derivation's output as a stream of bytes, this
+ * function destructively reads the expected number of bytes from the
+ * stream before comparing them.
+ * The operation's capacity decreases by the number of bytes read.
+ *
+ * This is functionally equivalent to the following code:
+ * \code
+ * psa_key_derivation_output_bytes(operation, tmp, output_length);
+ * if (memcmp(output, tmp, output_length) != 0)
+ * return PSA_ERROR_INVALID_SIGNATURE;
+ * \endcode
+ * except (1) it works even if the key's policy does not allow outputting the
+ * bytes, and (2) the comparison will be done in constant time.
+ *
+ * If this function returns an error status other than
+ * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
+ * the operation enters an error state and must be aborted by calling
+ * psa_key_derivation_abort().
+ *
+ * \param[in,out] operation The key derivation operation object to read from.
+ * \param[in] expected_output Buffer containing the expected derivation output.
+ * \param output_length Length ot the expected output; this is also the
+ * number of bytes that will be read.
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ * The output was read successfully, but it differs from the expected
+ * output.
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * One of the inputs was a key whose policy didn't allow
+ * #PSA_KEY_USAGE_VERIFY_DERIVATION.
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
+ * The operation's capacity was less than
+ * \p output_length bytes. Note that in this case,
+ * the operation's capacity is set to 0, thus
+ * subsequent calls to this function will not
+ * succeed, even with a smaller expected output.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be active and completed
+ * all required input steps).
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #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_key_derivation_verify_bytes(
+ psa_key_derivation_operation_t *operation,
+ const uint8_t *expected_output,
+ size_t output_length);
+
+/** Compare output data from a key derivation operation to an expected value
+ * stored in a key object.
+ *
+ * This function calculates output bytes from a key derivation algorithm and
+ * compares those bytes to an expected value, provided as key of type
+ * #PSA_KEY_TYPE_PASSWORD_HASH.
+ * If you view the key derivation's output as a stream of bytes, this
+ * function destructively reads the number of bytes corresponding the the
+ * length of the expected value from the stream before comparing them.
+ * The operation's capacity decreases by the number of bytes read.
+ *
+ * This is functionally equivalent to exporting the key and calling
+ * psa_key_derivation_verify_bytes() on the result, except that it
+ * works even if the key cannot be exported.
+ *
+ * If this function returns an error status other than
+ * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
+ * the operation enters an error state and must be aborted by calling
+ * psa_key_derivation_abort().
+ *
+ * \param[in,out] operation The key derivation operation object to read from.
+ * \param[in] expected A key of type #PSA_KEY_TYPE_PASSWORD_HASH
+ * containing the expected output. Its policy must
+ * include the #PSA_KEY_USAGE_VERIFY_DERIVATION flag
+ * and the permitted algorithm must match the
+ * operation. The value of this key was likely
+ * computed by a previous call to
+ * psa_key_derivation_output_key().
+ *
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_INVALID_SIGNATURE
+ * The output was read successfully, but if differs from the expected
+ * output.
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * The key passed as the expected value does not exist.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * The key passed as the expected value has an invalid type.
+ * \retval #PSA_ERROR_NOT_PERMITTED
+ * The key passed as the expected value does not allow this usage or
+ * this algorithm; or one of the inputs was a key whose policy didn't
+ * allow #PSA_KEY_USAGE_VERIFY_DERIVATION.
+ * \retval #PSA_ERROR_INSUFFICIENT_DATA
+ * The operation's capacity was less than
+ * the length of the expected value. In this case,
+ * the operation's capacity is set to 0, thus
+ * subsequent calls to this function will not
+ * succeed, even with a smaller expected output.
+ * \retval #PSA_ERROR_BAD_STATE
+ * The operation state is not valid (it must be active and completed
+ * all required input steps).
+ * \retval #PSA_ERROR_INSUFFICIENT_MEMORY
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval #PSA_ERROR_HARDWARE_FAILURE
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval #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_key_derivation_verify_key(
+ psa_key_derivation_operation_t *operation,
+ psa_key_id_t expected);
+
/** Abort a key derivation operation.
*
* Aborting an operation frees all associated resources except for the \c
diff --git a/interface/include/psa/crypto_compat.h b/interface/include/psa/crypto_compat.h
index 17dcee2d9e..9a7de899f1 100644
--- a/interface/include/psa/crypto_compat.h
+++ b/interface/include/psa/crypto_compat.h
@@ -43,217 +43,6 @@ static inline int psa_key_handle_is_null(psa_key_handle_t handle)
return(handle == 0);
}
-#if !defined(MBEDTLS_DEPRECATED_REMOVED)
-
-/*
- * Mechanism for declaring deprecated values
- */
-#if defined(MBEDTLS_DEPRECATED_WARNING) && !defined(MBEDTLS_PSA_DEPRECATED)
-#define MBEDTLS_PSA_DEPRECATED __attribute__((deprecated))
-#else
-#define MBEDTLS_PSA_DEPRECATED
-#endif
-
-typedef MBEDTLS_PSA_DEPRECATED size_t mbedtls_deprecated_size_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_status_t mbedtls_deprecated_psa_status_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_key_usage_t mbedtls_deprecated_psa_key_usage_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_ecc_family_t mbedtls_deprecated_psa_ecc_family_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_dh_family_t mbedtls_deprecated_psa_dh_family_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_ecc_family_t psa_ecc_curve_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_dh_family_t psa_dh_group_t;
-typedef MBEDTLS_PSA_DEPRECATED psa_algorithm_t mbedtls_deprecated_psa_algorithm_t;
-
-#define PSA_KEY_TYPE_GET_CURVE PSA_KEY_TYPE_ECC_GET_FAMILY
-#define PSA_KEY_TYPE_GET_GROUP PSA_KEY_TYPE_DH_GET_FAMILY
-
-#define MBEDTLS_DEPRECATED_CONSTANT( type, value ) \
- ( (mbedtls_deprecated_##type) ( value ) )
-
-/*
- * Deprecated PSA Crypto error code definitions (PSA Crypto API <= 1.0 beta2)
- */
-#define PSA_ERROR_UNKNOWN_ERROR \
- MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_GENERIC_ERROR )
-#define PSA_ERROR_OCCUPIED_SLOT \
- MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_ALREADY_EXISTS )
-#define PSA_ERROR_EMPTY_SLOT \
- MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_DOES_NOT_EXIST )
-#define PSA_ERROR_INSUFFICIENT_CAPACITY \
- MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_INSUFFICIENT_DATA )
-#define PSA_ERROR_TAMPERING_DETECTED \
- MBEDTLS_DEPRECATED_CONSTANT( psa_status_t, PSA_ERROR_CORRUPTION_DETECTED )
-
-/*
- * Deprecated PSA Crypto numerical encodings (PSA Crypto API <= 1.0 beta3)
- */
-#define PSA_KEY_USAGE_SIGN \
- MBEDTLS_DEPRECATED_CONSTANT( psa_key_usage_t, PSA_KEY_USAGE_SIGN_HASH )
-#define PSA_KEY_USAGE_VERIFY \
- MBEDTLS_DEPRECATED_CONSTANT( psa_key_usage_t, PSA_KEY_USAGE_VERIFY_HASH )
-
-/*
- * Deprecated PSA Crypto size calculation macros (PSA Crypto API <= 1.0 beta3)
- */
-#define PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_SIGNATURE_MAX_SIZE )
-#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE( key_type, key_bits, alg ) \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_SIGN_OUTPUT_SIZE( key_type, key_bits, alg ) )
-#define PSA_KEY_EXPORT_MAX_SIZE( key_type, key_bits ) \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_EXPORT_KEY_OUTPUT_SIZE( key_type, key_bits ) )
-#define PSA_BLOCK_CIPHER_BLOCK_SIZE( type ) \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_BLOCK_CIPHER_BLOCK_LENGTH( type ) )
-#define PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE )
-#define PSA_HASH_SIZE( alg ) \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_HASH_LENGTH( alg ) )
-#define PSA_MAC_FINAL_SIZE( key_type, key_bits, alg ) \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_MAC_LENGTH( key_type, key_bits, alg ) )
-#define PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN \
- MBEDTLS_DEPRECATED_CONSTANT( size_t, PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE )
-/*
- * Deprecated PSA Crypto function names (PSA Crypto API <= 1.0 beta3)
- */
-MBEDTLS_PSA_DEPRECATED psa_status_t psa_asymmetric_sign( psa_key_handle_t key,
- psa_algorithm_t alg,
- const uint8_t *hash,
- size_t hash_length,
- uint8_t *signature,
- size_t signature_size,
- size_t *signature_length );
-
-MBEDTLS_PSA_DEPRECATED psa_status_t psa_asymmetric_verify( psa_key_handle_t key,
- psa_algorithm_t alg,
- const uint8_t *hash,
- size_t hash_length,
- const uint8_t *signature,
- size_t signature_length );
-
-
-/*
- * Size-specific elliptic curve families.
- */
-#define PSA_ECC_CURVE_SECP160K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
-#define PSA_ECC_CURVE_SECP192K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
-#define PSA_ECC_CURVE_SECP224K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
-#define PSA_ECC_CURVE_SECP256K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
-#define PSA_ECC_CURVE_SECP160R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP192R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP224R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP256R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP384R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP521R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP160R2 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2 )
-#define PSA_ECC_CURVE_SECT163K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT233K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT239K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT283K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT409K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT571K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT163R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT193R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT233R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT283R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT409R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT571R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT163R2 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
-#define PSA_ECC_CURVE_SECT193R2 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
-#define PSA_ECC_CURVE_BRAINPOOL_P256R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
-#define PSA_ECC_CURVE_BRAINPOOL_P384R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
-#define PSA_ECC_CURVE_BRAINPOOL_P512R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
-#define PSA_ECC_CURVE_CURVE25519 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
-#define PSA_ECC_CURVE_CURVE448 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
-
-/*
- * Curves that changed name due to PSA specification.
- */
-#define PSA_ECC_CURVE_SECP_K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_K1 )
-#define PSA_ECC_CURVE_SECP_R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R1 )
-#define PSA_ECC_CURVE_SECP_R2 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECP_R2 )
-#define PSA_ECC_CURVE_SECT_K1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_K1 )
-#define PSA_ECC_CURVE_SECT_R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R1 )
-#define PSA_ECC_CURVE_SECT_R2 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_SECT_R2 )
-#define PSA_ECC_CURVE_BRAINPOOL_P_R1 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_BRAINPOOL_P_R1 )
-#define PSA_ECC_CURVE_MONTGOMERY \
- MBEDTLS_DEPRECATED_CONSTANT( psa_ecc_family_t, PSA_ECC_FAMILY_MONTGOMERY )
-
-/*
- * Finite-field Diffie-Hellman families.
- */
-#define PSA_DH_GROUP_FFDHE2048 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
-#define PSA_DH_GROUP_FFDHE3072 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
-#define PSA_DH_GROUP_FFDHE4096 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
-#define PSA_DH_GROUP_FFDHE6144 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
-#define PSA_DH_GROUP_FFDHE8192 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
-
-/*
- * Diffie-Hellman families that changed name due to PSA specification.
- */
-#define PSA_DH_GROUP_RFC7919 \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_RFC7919 )
-#define PSA_DH_GROUP_CUSTOM \
- MBEDTLS_DEPRECATED_CONSTANT( psa_dh_family_t, PSA_DH_FAMILY_CUSTOM )
-
-/*
- * Deprecated PSA Crypto stream cipher algorithms (PSA Crypto API <= 1.0 beta3)
- */
-#define PSA_ALG_ARC4 \
- MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_STREAM_CIPHER)
-#define PSA_ALG_CHACHA20 \
- MBEDTLS_DEPRECATED_CONSTANT(psa_algorithm_t, PSA_ALG_STREAM_CIPHER)
-
-/*
- * Renamed AEAD tag length macros (PSA Crypto API <= 1.0 beta3)
- */
-#define PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH( aead_alg ) \
- MBEDTLS_DEPRECATED_CONSTANT( psa_algorithm_t, PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG( aead_alg ) )
-#define PSA_ALG_AEAD_WITH_TAG_LENGTH( aead_alg, tag_length ) \
- MBEDTLS_DEPRECATED_CONSTANT( psa_algorithm_t, PSA_ALG_AEAD_WITH_SHORTENED_TAG( aead_alg, tag_length ) )
-
-
-#endif /* MBEDTLS_DEPRECATED_REMOVED */
-
/** Open a handle to an existing persistent key.
*
* Open a handle to a persistent key. A key is persistent if it was created
diff --git a/interface/include/psa/crypto_sizes.h b/interface/include/psa/crypto_sizes.h
index 0608d71d10..1e282e26c1 100644
--- a/interface/include/psa/crypto_sizes.h
+++ b/interface/include/psa/crypto_sizes.h
@@ -50,8 +50,6 @@
*/
#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 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_RIPEMD160 ? 20 : \
PSA_ALG_HMAC_GET_HASH(alg) == PSA_ALG_SHA_1 ? 20 : \
@@ -77,8 +75,13 @@
/* 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
* HMAC-SHA3-512. */
+#if defined(MBEDTLS_SHA512_C)
#define PSA_HASH_MAX_SIZE 64
#define PSA_HMAC_MAX_HASH_BLOCK_SIZE 128
+#else
+#define PSA_HASH_MAX_SIZE 32
+#define PSA_HMAC_MAX_HASH_BLOCK_SIZE 64
+#endif
/** \def PSA_MAC_MAX_SIZE
*
@@ -94,26 +97,35 @@
*/
#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 length 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(alg) \
- (PSA_ALG_IS_AEAD(alg) ? \
- (((alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> PSA_AEAD_TAG_LENGTH_OFFSET) : \
- 0)
+#define PSA_AEAD_TAG_LENGTH(key_type, key_bits, alg) \
+ (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ? \
+ PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
+ ((void) (key_bits), 0))
/** 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
@@ -137,7 +149,7 @@
/** This macro returns the maximum supported length of the PSK for the
* TLS-1.2 PSK-to-MS key derivation
- * (#PSA_ALG_TLS12_PSK_TO_MS(\p hash_alg)).
+ * (#PSA_ALG_TLS12_PSK_TO_MS(\c hash_alg)).
*
* The maximum supported length does not depend on the chosen hash algorithm.
*
@@ -155,7 +167,6 @@
/** The maximum size of a block cipher. */
#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.
@@ -190,10 +201,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).
@@ -201,11 +216,13 @@
*
* \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(alg, plaintext_length) \
- (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
- (plaintext_length) + PSA_AEAD_TAG_LENGTH(alg) : \
+#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(key_type, alg, plaintext_length) \
+ (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ? \
+ (plaintext_length) + PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
0)
/** A sufficient output buffer size for psa_aead_encrypt(), for any of the
@@ -217,7 +234,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.
*
@@ -236,10 +254,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).
@@ -247,11 +269,14 @@
*
* \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(alg, ciphertext_length) \
- (PSA_AEAD_TAG_LENGTH(alg) != 0 ? \
- (ciphertext_length) - PSA_AEAD_TAG_LENGTH(alg) : \
+#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(key_type, alg, ciphertext_length) \
+ (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 && \
+ (ciphertext_length) > PSA_ALG_AEAD_GET_TAG_LENGTH(alg) ? \
+ (ciphertext_length) - PSA_ALG_AEAD_GET_TAG_LENGTH(alg) : \
0)
/** A sufficient output buffer size for psa_aead_decrypt(), for any of the
@@ -263,7 +288,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.
*
@@ -300,11 +326,12 @@
* or the parameters are incompatible, return 0.
*/
#define PSA_AEAD_NONCE_LENGTH(key_type, alg) \
- (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) == 16 && \
- (PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(alg) == PSA_ALG_CCM || \
- PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(alg) == PSA_ALG_GCM) ? 12 : \
+ (PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) == 16 ? \
+ MBEDTLS_PSA_ALG_AEAD_EQUAL(alg, PSA_ALG_CCM) ? 13 : \
+ MBEDTLS_PSA_ALG_AEAD_EQUAL(alg, PSA_ALG_GCM) ? 12 : \
+ 0 : \
(key_type) == PSA_KEY_TYPE_CHACHA20 && \
- PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(alg) == PSA_ALG_CHACHA20_POLY1305 ? 12 : \
+ MBEDTLS_PSA_ALG_AEAD_EQUAL(alg, PSA_ALG_CHACHA20_POLY1305) ? 12 : \
0)
/** The maximum default nonce size among all supported pairs of key types and
@@ -318,7 +345,7 @@
* just the largest size that may be generated by
* #psa_aead_generate_nonce().
*/
-#define PSA_AEAD_NONCE_MAX_SIZE 12
+#define PSA_AEAD_NONCE_MAX_SIZE 13
/** A sufficient output buffer size for psa_aead_update().
*
@@ -327,10 +354,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).
@@ -338,16 +369,20 @@
*
* \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
* capable of this. So for modes based on a block cipher, allow the
* implementation to delay the output until it has a full block. */
-#define PSA_AEAD_UPDATE_OUTPUT_SIZE(alg, input_length) \
- (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
- PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, (input_length)) : \
- (input_length))
+#define PSA_AEAD_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \
+ (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 ? \
+ PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
+ PSA_ROUND_UP_TO_MULTIPLE(PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type), (input_length)) : \
+ (input_length) : \
+ 0)
/** A sufficient output buffer size for psa_aead_update(), for any of the
* supported key types and AEAD algorithms.
@@ -355,7 +390,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.
*/
@@ -369,23 +404,30 @@
* 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(alg) \
- (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
- PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
+#define PSA_AEAD_FINISH_OUTPUT_SIZE(key_type, alg) \
+ (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 && \
+ PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
+ PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
0)
/** 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)
@@ -396,23 +438,30 @@
* 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(alg) \
- (PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
- PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE : \
+#define PSA_AEAD_VERIFY_OUTPUT_SIZE(key_type, alg) \
+ (PSA_AEAD_NONCE_LENGTH(key_type, alg) != 0 && \
+ PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) ? \
+ PSA_BLOCK_CIPHER_BLOCK_LENGTH(key_type) : \
0)
/** 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)
diff --git a/interface/include/psa/crypto_values.h b/interface/include/psa/crypto_values.h
index 25c6662c16..dc8d81a869 100644
--- a/interface/include/psa/crypto_values.h
+++ b/interface/include/psa/crypto_values.h
@@ -401,11 +401,55 @@
/** A secret for key derivation.
*
+ * This key type is for high-entropy secrets only. For low-entropy secrets,
+ * #PSA_KEY_TYPE_PASSWORD should be used instead.
+ *
+ * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_SECRET or
+ * #PSA_KEY_DERIVATION_INPUT_PASSWORD input of key derivation algorithms.
+ *
* The key policy determines which key derivation algorithm the key
* can be used for.
*/
#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200)
+/** A low-entropy secret for password hashing or key derivation.
+ *
+ * This key type is suitable for passwords and passphrases which are typically
+ * intended to be memorizable by humans, and have a low entropy relative to
+ * their size. It can be used for randomly generated or derived keys with
+ * maximum or near-maximum entropy, but #PSA_KEY_TYPE_DERIVE is more suitable
+ * for such keys. It is not suitable for passwords with extremely low entropy,
+ * such as numerical PINs.
+ *
+ * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_PASSWORD input of
+ * key derivation algorithms. Algorithms that accept such an input were
+ * designed to accept low-entropy secret and are known as password hashing or
+ * key stretching algorithms.
+ *
+ * These keys cannot be used as the #PSA_KEY_DERIVATION_INPUT_SECRET input of
+ * key derivation algorithms, as the algorithms that take such an input expect
+ * it to be high-entropy.
+ *
+ * The key policy determines which key derivation algorithm the key can be
+ * used for, among the permissible subset defined above.
+ */
+#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203)
+
+/** A secret value that can be used to verify a password hash.
+ *
+ * The key policy determines which key derivation algorithm the key
+ * can be used for, among the same permissible subset as for
+ * #PSA_KEY_TYPE_PASSWORD.
+ */
+#define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205)
+
+/** A secret value that can be used in when computing a password hash.
+ *
+ * The key policy determines which key derivation algorithm the key
+ * can be used for, among the subset of algorithms that can use pepper.
+ */
+#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1206)
+
/** Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.
*
* The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or
@@ -415,8 +459,8 @@
/** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
*
- * The size of the key can be 8 bytes (single DES), 16 bytes (2-key 3DES) or
- * 24 bytes (3-key 3DES).
+ * The size of the key can be 64 bits (single DES), 128 bits (2-key 3DES) or
+ * 192 bits (3-key 3DES).
*
* Note that single DES and 2-key 3DES are weak and strongly
* deprecated and should only be used to decrypt legacy data. 3-key 3DES
@@ -428,12 +472,6 @@
* Camellia block cipher. */
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403)
-/** Key for the RC4 stream cipher.
- *
- * Note that RC4 is weak and deprecated and should only be used in
- * legacy protocols. */
-#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002)
-
/** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.
*
* ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539.
@@ -443,9 +481,15 @@
*/
#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004)
-/** RSA public key. */
+/** RSA public key.
+ *
+ * The size of an RSA key is the bit size of the modulus.
+ */
#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001)
-/** RSA key pair (private and public key). */
+/** RSA key pair (private and public key).
+ *
+ * The size of an RSA key is the bit size of the modulus.
+ */
#define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001)
/** Whether a key type is an RSA key (pair or public-only). */
#define PSA_KEY_TYPE_IS_RSA(type) \
@@ -456,6 +500,10 @@
#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x00ff)
/** Elliptic curve key pair.
*
+ * The size of an elliptic curve key is the bit size associated with the curve,
+ * i.e. the bit size of *q* for a curve over a field *F<sub>q</sub>*.
+ * See the documentation of `PSA_ECC_FAMILY_xxx` curve families for details.
+ *
* \param curve A value of type ::psa_ecc_family_t that
* identifies the ECC curve to be used.
*/
@@ -463,6 +511,10 @@
(PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve))
/** Elliptic curve public key.
*
+ * The size of an elliptic curve public key is the same as the corresponding
+ * private key (see #PSA_KEY_TYPE_ECC_KEY_PAIR and the documentation of
+ * `PSA_ECC_FAMILY_xxx` curve families).
+ *
* \param curve A value of type ::psa_ecc_family_t that
* identifies the ECC curve to be used.
*/
@@ -561,6 +613,22 @@
*/
#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t) 0x41)
+/** The twisted Edwards curves Ed25519 and Ed448.
+ *
+ * These curves are suitable for EdDSA (#PSA_ALG_PURE_EDDSA for both curves,
+ * #PSA_ALG_ED25519PH for the 255-bit curve,
+ * #PSA_ALG_ED448PH for the 448-bit curve).
+ *
+ * This family comprises the following twisted Edwards curves:
+ * - 255-bit: Edwards25519, the twisted Edwards curve birationally equivalent
+ * to Curve25519.
+ * Bernstein et al., _Twisted Edwards curves_, Africacrypt 2008.
+ * - 448-bit: Edwards448, the twisted Edwards curve birationally equivalent
+ * to Curve448.
+ * Hamburg, _Ed448-Goldilocks, a new elliptic curve_, NIST ECC Workshop, 2015.
+ */
+#define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42)
+
#define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t)0x4200)
#define PSA_KEY_TYPE_DH_KEY_PAIR_BASE ((psa_key_type_t)0x7200)
#define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t)0x00ff)
@@ -748,11 +816,25 @@
#define PSA_ALG_IS_KEY_DERIVATION(alg) \
(((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
+/** Whether the specified algorithm is a key stretching / password hashing
+ * algorithm.
+ *
+ * A key stretching / password hashing algorithm is a key derivation algorithm
+ * that is suitable for use with a low-entropy secret such as a password.
+ * Equivalently, it's a key derivation algorithm that uses a
+ * #PSA_KEY_DERIVATION_INPUT_PASSWORD input step.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a key stretching / password hashing algorithm, 0
+ * otherwise. This macro may return either 0 or 1 if \p alg is not a
+ * supported algorithm identifier.
+ */
+#define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \
+ (PSA_ALG_IS_KEY_DERIVATION(alg) && \
+ (alg) & PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG)
+
#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)
-/** MD2 */
-#define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001)
-/** MD4 */
-#define PSA_ALG_MD4 ((psa_algorithm_t)0x02000002)
/** MD5 */
#define PSA_ALG_MD5 ((psa_algorithm_t)0x02000003)
/** PSA_ALG_RIPEMD160 */
@@ -779,6 +861,13 @@
#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012)
/** SHA3-512 */
#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013)
+/** The first 512 bits (64 bytes) of the SHAKE256 output.
+ *
+ * This is the prehashing for Ed448ph (see #PSA_ALG_ED448PH). For other
+ * scenarios where a hash function based on SHA3/SHAKE is desired, SHA3-512
+ * has the same output size and a (theoretically) higher security strength.
+ */
+#define PSA_ALG_SHAKE256_512 ((psa_algorithm_t)0x02000015)
/** In a hash-and-sign algorithm policy, allow any hash algorithm.
*
@@ -884,7 +973,7 @@
* for policy comparison purposes.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
* \param mac_length Desired length of the truncated MAC in bytes.
@@ -895,7 +984,7 @@
*
* \return The corresponding MAC algorithm with the specified
* length.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm or if \p mac_length is too small or
* too large for the specified MAC algorithm.
*/
@@ -908,12 +997,12 @@
* MAC algorithm.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true). This may be a truncated or untruncated
* MAC algorithm.
*
* \return The corresponding base MAC algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm.
*/
#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \
@@ -923,12 +1012,12 @@
/** Length to which a MAC algorithm is truncated.
*
* \param mac_alg A MAC algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_MAC(\p mac_alg)
* is true).
*
* \return Length of the truncated MAC in bytes.
- * \return 0 if \p alg is a non-truncated MAC algorithm.
- * \return Unspecified if \p alg is not a supported
+ * \return 0 if \p mac_alg is a non-truncated MAC algorithm.
+ * \return Unspecified if \p mac_alg is not a supported
* MAC algorithm.
*/
#define PSA_MAC_TRUNCATED_LENGTH(mac_alg) \
@@ -1007,7 +1096,6 @@
*
* The underlying stream cipher is determined by the key type.
* - To use ChaCha20, use a key type of #PSA_KEY_TYPE_CHACHA20.
- * - To use ARC4, use a key type of #PSA_KEY_TYPE_ARC4.
*/
#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800100)
@@ -1138,13 +1226,13 @@
* of the ciphertext.
*
* \param aead_alg An AEAD algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg)
* is true).
* \param tag_length Desired length of the authentication tag in bytes.
*
* \return The corresponding AEAD algorithm with the specified
* length.
- * \return Unspecified if \p alg is not a supported
+ * \return Unspecified if \p aead_alg is not a supported
* AEAD algorithm or if \p tag_length is not valid
* for the specified AEAD algorithm.
*/
@@ -1157,13 +1245,12 @@
/** Retrieve the tag length of a specified AEAD algorithm
*
* \param aead_alg An AEAD algorithm identifier (value of type
- * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p alg)
+ * #psa_algorithm_t such that #PSA_ALG_IS_AEAD(\p aead_alg)
* is true).
*
* \return The tag length specified by the input algorithm.
- * \return Unspecified if \p alg is not a supported
- * AEAD algorithm or if \p tag_length is not valid
- * for the specified AEAD algorithm.
+ * \return Unspecified if \p aead_alg is not a supported
+ * AEAD algorithm.
*/
#define PSA_ALG_AEAD_GET_TAG_LENGTH(aead_alg) \
(((aead_alg) & PSA_ALG_AEAD_TAG_LENGTH_MASK) >> \
@@ -1172,7 +1259,7 @@
/** Calculate the corresponding AEAD algorithm with the default tag length.
*
* \param aead_alg An AEAD algorithm (\c PSA_ALG_XXX value such that
- * #PSA_ALG_IS_AEAD(\p alg) is true).
+ * #PSA_ALG_IS_AEAD(\p aead_alg) is true).
*
* \return The corresponding AEAD algorithm with the default
* tag length for that algorithm.
@@ -1337,6 +1424,94 @@
#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \
(PSA_ALG_IS_ECDSA(alg) && !PSA_ALG_ECDSA_IS_DETERMINISTIC(alg))
+/** Edwards-curve digital signature algorithm without prehashing (PureEdDSA),
+ * using standard parameters.
+ *
+ * Contexts are not supported in the current version of this specification
+ * because there is no suitable signature interface that can take the
+ * context as a parameter. A future version of this specification may add
+ * suitable functions and extend this algorithm to support contexts.
+ *
+ * PureEdDSA requires an elliptic curve key on a twisted Edwards curve.
+ * In this specification, the following curves are supported:
+ * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 255-bit: Ed25519 as specified
+ * in RFC 8032.
+ * The curve is Edwards25519.
+ * The hash function used internally is SHA-512.
+ * - #PSA_ECC_FAMILY_TWISTED_EDWARDS, 448-bit: Ed448 as specified
+ * in RFC 8032.
+ * The curve is Edwards448.
+ * The hash function used internally is the first 114 bytes of the
+ * SHAKE256 output.
+ *
+ * This algorithm can be used with psa_sign_message() and
+ * psa_verify_message(). Since there is no prehashing, it cannot be used
+ * with psa_sign_hash() or psa_verify_hash().
+ *
+ * The signature format is the concatenation of R and S as defined by
+ * RFC 8032 §5.1.6 and §5.2.6 (a 64-byte string for Ed25519, a 114-byte
+ * string for Ed448).
+ */
+#define PSA_ALG_PURE_EDDSA ((psa_algorithm_t)0x06000800)
+
+#define PSA_ALG_HASH_EDDSA_BASE ((psa_algorithm_t)0x06000900)
+#define PSA_ALG_IS_HASH_EDDSA(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HASH_EDDSA_BASE)
+
+/** Edwards-curve digital signature algorithm with prehashing (HashEdDSA),
+ * using SHA-512 and the Edwards25519 curve.
+ *
+ * See #PSA_ALG_PURE_EDDSA regarding context support and the signature format.
+ *
+ * This algorithm is Ed25519 as specified in RFC 8032.
+ * The curve is Edwards25519.
+ * The prehash is SHA-512.
+ * The hash function used internally is SHA-512.
+ *
+ * This is a hash-and-sign algorithm: to calculate a signature,
+ * you can either:
+ * - call psa_sign_message() on the message;
+ * - or calculate the SHA-512 hash of the message
+ * with psa_hash_compute()
+ * or with a multi-part hash operation started with psa_hash_setup(),
+ * using the hash algorithm #PSA_ALG_SHA_512,
+ * then sign the calculated hash with psa_sign_hash().
+ * Verifying a signature is similar, using psa_verify_message() or
+ * psa_verify_hash() instead of the signature function.
+ */
+#define PSA_ALG_ED25519PH \
+ (PSA_ALG_HASH_EDDSA_BASE | (PSA_ALG_SHA_512 & PSA_ALG_HASH_MASK))
+
+/** Edwards-curve digital signature algorithm with prehashing (HashEdDSA),
+ * using SHAKE256 and the Edwards448 curve.
+ *
+ * See #PSA_ALG_PURE_EDDSA regarding context support and the signature format.
+ *
+ * This algorithm is Ed448 as specified in RFC 8032.
+ * The curve is Edwards448.
+ * The prehash is the first 64 bytes of the SHAKE256 output.
+ * The hash function used internally is the first 114 bytes of the
+ * SHAKE256 output.
+ *
+ * This is a hash-and-sign algorithm: to calculate a signature,
+ * you can either:
+ * - call psa_sign_message() on the message;
+ * - or calculate the first 64 bytes of the SHAKE256 output of the message
+ * with psa_hash_compute()
+ * or with a multi-part hash operation started with psa_hash_setup(),
+ * using the hash algorithm #PSA_ALG_SHAKE256_512,
+ * then sign the calculated hash with psa_sign_hash().
+ * Verifying a signature is similar, using psa_verify_message() or
+ * psa_verify_hash() instead of the signature function.
+ */
+#define PSA_ALG_ED448PH \
+ (PSA_ALG_HASH_EDDSA_BASE | (PSA_ALG_SHAKE256_512 & PSA_ALG_HASH_MASK))
+
+/* Default definition, to be overridden if the library is extended with
+ * more hash-and-sign algorithms that we want to keep out of this header
+ * file. */
+#define PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg) 0
+
/** Whether the specified algorithm is a hash-and-sign algorithm.
*
* Hash-and-sign algorithms are asymmetric (public-key) signature algorithms
@@ -1352,7 +1527,22 @@
*/
#define PSA_ALG_IS_HASH_AND_SIGN(alg) \
(PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
- PSA_ALG_IS_ECDSA(alg))
+ PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg) || \
+ PSA_ALG_IS_VENDOR_HASH_AND_SIGN(alg))
+
+/** Whether the specified algorithm is a signature algorithm that can be used
+ * with psa_sign_message() and psa_verify_message().
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if alg is a signature algorithm that can be used to sign a
+ * message. 0 if \p alg is a signature algorithm that can only be used
+ * to sign an already-calculated hash. 0 if \p alg is not a signature
+ * algorithm. This macro can return either 0 or 1 if \p alg is not a
+ * supported algorithm identifier.
+ */
+#define PSA_ALG_IS_SIGN_MESSAGE(alg) \
+ (PSA_ALG_IS_HASH_AND_SIGN(alg) || (alg) == PSA_ALG_PURE_EDDSA )
/** Get the hash used by a hash-and-sign signature algorithm.
*
@@ -1534,6 +1724,67 @@
#define PSA_ALG_TLS12_PSK_TO_MS_GET_HASH(hkdf_alg) \
(PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK))
+/* This flag indicates whether the key derivation algorithm is suitable for
+ * use on low-entropy secrets such as password - these algorithms are also
+ * known as key stretching or password hashing schemes. These are also the
+ * algorithms that accepts inputs of type #PSA_KEY_DERIVATION_INPUT_PASSWORD.
+ *
+ * Those algorithms cannot be combined with a key agreement algorithm.
+ */
+#define PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG ((psa_algorithm_t)0x00800000)
+
+#define PSA_ALG_PBKDF2_HMAC_BASE ((psa_algorithm_t)0x08800100)
+/** Macro to build a PBKDF2-HMAC password hashing / key stretching algorithm.
+ *
+ * PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2).
+ * This macro specifies the PBKDF2 algorithm constructed using a PRF based on
+ * HMAC with the specified hash.
+ * For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA256)` specifies PBKDF2
+ * using the PRF HMAC-SHA-256.
+ *
+ * This key derivation algorithm uses the following inputs, which must be
+ * provided in the following order:
+ * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count.
+ * This input step must be used exactly once.
+ * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt.
+ * This input step must be used one or more times; if used several times, the
+ * inputs will be concatenated. This can be used to build the final salt
+ * from multiple sources, both public and secret (also known as pepper).
+ * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed.
+ * This input step must be used exactly once.
+ *
+ * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
+ * #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *
+ * \return The corresponding PBKDF2-HMAC-XXX algorithm.
+ * \return Unspecified if \p hash_alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_PBKDF2_HMAC(hash_alg) \
+ (PSA_ALG_PBKDF2_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+
+/** Whether the specified algorithm is a PBKDF2-HMAC algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \c alg is a PBKDF2-HMAC algorithm, 0 otherwise.
+ * This macro may return either 0 or 1 if \c alg is not a supported
+ * key derivation algorithm identifier.
+ */
+#define PSA_ALG_IS_PBKDF2_HMAC(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_PBKDF2_HMAC_BASE)
+
+/** The PBKDF2-AES-CMAC-PRF-128 password hashing / key stretching algorithm.
+ *
+ * PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2).
+ * This macro specifies the PBKDF2 algorithm constructed using the
+ * AES-CMAC-PRF-128 PRF specified by RFC 4615.
+ *
+ * This key derivation algorithm uses the same inputs as
+ * #PSA_ALG_PBKDF2_HMAC() with the same constraints.
+ */
+#define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200)
+
#define PSA_ALG_KEY_DERIVATION_MASK ((psa_algorithm_t)0xfe00ffff)
#define PSA_ALG_KEY_AGREEMENT_MASK ((psa_algorithm_t)0xffff0000)
@@ -1671,6 +1922,18 @@
(alg & PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG) != 0 : \
(alg) == PSA_ALG_ANY_HASH)
+/** Get the hash used by a composite algorithm.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return The underlying hash algorithm if alg is a composite algorithm that
+ * uses a hash algorithm.
+ *
+ * \return \c 0 if alg is not a composite algorithm that uses a hash.
+ */
+#define PSA_ALG_GET_HASH(alg) \
+ (((alg) & 0x000000ff) == 0 ? ((psa_algorithm_t)0) : 0x02000000 | ((alg) & 0x000000ff))
+
/**@}*/
/** \defgroup key_lifetimes Key lifetimes
@@ -1748,6 +2011,27 @@
(PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \
PSA_KEY_PERSISTENCE_VOLATILE)
+/** Whether a key lifetime indicates that the key is read-only.
+ *
+ * Read-only keys cannot be created or destroyed through the PSA Crypto API.
+ * They must be created through platform-specific means that bypass the API.
+ *
+ * Some platforms may offer ways to destroy read-only keys. For example,
+ * consider a platform with multiple levels of privilege, where a
+ * low-privilege application can use a key but is not allowed to destroy
+ * it, and the platform exposes the key to the application with a read-only
+ * lifetime. High-privilege code can destroy the key even though the
+ * application sees the key as read-only.
+ *
+ * \param lifetime The lifetime value to query (value of type
+ * ::psa_key_lifetime_t).
+ *
+ * \return \c 1 if the key is read-only, otherwise \c 0.
+ */
+#define PSA_KEY_LIFETIME_IS_READ_ONLY(lifetime) \
+ (PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == \
+ PSA_KEY_PERSISTENCE_READ_ONLY)
+
/** Construct a lifetime from a persistence level and a location.
*
* \param persistence The persistence level
@@ -1843,6 +2127,26 @@
/** Whether the key may be used to sign a message.
*
+ * This flag allows the key to be used for a MAC calculation operation or for
+ * an asymmetric message signature operation, if otherwise permitted by the
+ * key’s type and policy.
+ *
+ * For a key pair, this concerns the private key.
+ */
+#define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t)0x00000400)
+
+/** Whether the key may be used to verify a message.
+ *
+ * This flag allows the key to be used for a MAC verification operation or for
+ * an asymmetric message signature verification operation, if otherwise
+ * permitted by the key’s type and policy.
+ *
+ * For a key pair, this concerns the public key.
+ */
+#define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t)0x00000800)
+
+/** Whether the key may be used to sign a message.
+ *
* This flag allows the key to be used for a MAC calculation operation
* or for an asymmetric signature operation,
* if otherwise permitted by the key's type and policy.
@@ -1861,10 +2165,35 @@
*/
#define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t)0x00002000)
-/** Whether the key may be used to derive other keys.
+/** Whether the key may be used to derive other keys or produce a password
+ * hash.
+ *
+ * This flag allows the key to be used for a key derivation operation or for
+ * a key agreement operation, if otherwise permitted by by the key's type and
+ * policy.
+ *
+ * If this flag is present on all keys used in calls to
+ * psa_key_derivation_input_key() for a key derivation operation, then it
+ * permits calling psa_key_derivation_output_bytes() or
+ * psa_key_derivation_output_key() at the end of the operation.
*/
#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000)
+/** Whether the key may be used to verify the result of a key derivation,
+ * including password hashing.
+ *
+ * This flag allows the key to be used:
+ *
+ * This flag allows the key to be used in a key derivation operation, if
+ * otherwise permitted by by the key's type and policy.
+ *
+ * If this flag is present on all keys used in calls to
+ * psa_key_derivation_input_key() for a key derivation operation, then it
+ * permits calling psa_key_derivation_verify_bytes() or
+ * psa_key_derivation_verify_key() at the end of the operation.
+ */
+#define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t)0x00008000)
+
/**@}*/
/** \defgroup derivation Key derivation
@@ -1881,10 +2210,31 @@
* The secret can also be a direct input (passed to
* key_derivation_input_bytes()). In this case, the derivation operation
* may not be used to derive keys: the operation will only allow
- * psa_key_derivation_output_bytes(), not psa_key_derivation_output_key().
+ * psa_key_derivation_output_bytes(),
+ * psa_key_derivation_verify_bytes(), or
+ * psa_key_derivation_verify_key(), but not
+ * psa_key_derivation_output_key().
*/
#define PSA_KEY_DERIVATION_INPUT_SECRET ((psa_key_derivation_step_t)0x0101)
+/** A low-entropy secret input for password hashing / key stretching.
+ *
+ * This is usually a key of type #PSA_KEY_TYPE_PASSWORD (passed to
+ * psa_key_derivation_input_key()) or a direct input (passed to
+ * psa_key_derivation_input_bytes()) that is a password or passphrase. It can
+ * also be high-entropy secret such as a key of type #PSA_KEY_TYPE_DERIVE or
+ * the shared secret resulting from a key agreement.
+ *
+ * The secret can also be a direct input (passed to
+ * key_derivation_input_bytes()). In this case, the derivation operation
+ * may not be used to derive keys: the operation will only allow
+ * psa_key_derivation_output_bytes(),
+ * psa_key_derivation_verify_bytes(), or
+ * psa_key_derivation_verify_key(), but not
+ * psa_key_derivation_output_key().
+ */
+#define PSA_KEY_DERIVATION_INPUT_PASSWORD ((psa_key_derivation_step_t)0x0102)
+
/** A label for key derivation.
*
* This should be a direct input.
@@ -1895,7 +2245,8 @@
/** A salt for key derivation.
*
* This should be a direct input.
- * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA.
+ * It can also be a key of type #PSA_KEY_TYPE_RAW_DATA or
+ * #PSA_KEY_TYPE_PEPPER.
*/
#define PSA_KEY_DERIVATION_INPUT_SALT ((psa_key_derivation_step_t)0x0202)
@@ -1913,6 +2264,35 @@
*/
#define PSA_KEY_DERIVATION_INPUT_SEED ((psa_key_derivation_step_t)0x0204)
+/** A cost parameter for password hashing / key stretching.
+ *
+ * This must be a direct input, passed to psa_key_derivation_input_integer().
+ */
+#define PSA_KEY_DERIVATION_INPUT_COST ((psa_key_derivation_step_t)0x0205)
+
+/**@}*/
+
+/** \defgroup helper_macros Helper macros
+ * @{
+ */
+
+/* Helper macros */
+
+/** Check if two AEAD algorithm identifiers refer to the same AEAD algorithm
+ * regardless of the tag length they encode.
+ *
+ * \param aead_alg_1 An AEAD algorithm identifier.
+ * \param aead_alg_2 An AEAD algorithm identifier.
+ *
+ * \return 1 if both identifiers refer to the same AEAD algorithm,
+ * 0 otherwise.
+ * Unspecified if neither \p aead_alg_1 nor \p aead_alg_2 are
+ * a supported AEAD algorithm.
+ */
+#define MBEDTLS_PSA_ALG_AEAD_EQUAL(aead_alg_1, aead_alg_2) \
+ (!(((aead_alg_1) ^ (aead_alg_2)) & \
+ ~(PSA_ALG_AEAD_TAG_LENGTH_MASK | PSA_ALG_AEAD_AT_LEAST_THIS_LENGTH_FLAG)))
+
/**@}*/
#endif /* PSA_CRYPTO_VALUES_H */