Crypto: Update to mbed TLS 3.2.1
Signed-off-by: Antonio de Angelis <antonio.deangelis@arm.com>
Change-Id: I92274fc6496219a2fef35db4cf02a6fe66f3a276
diff --git a/interface/include/psa/crypto_values.h b/interface/include/psa/crypto_values.h
index 769bc7d..797c8c5 100644
--- a/interface/include/psa/crypto_values.h
+++ b/interface/include/psa/crypto_values.h
@@ -18,6 +18,11 @@
* designations of cryptographic algorithms, and error codes returned by
* the library.
*
+ * Note that many of the constants defined in this file are embedded in
+ * the persistent key store, as part of key metadata (including usage
+ * policies). As a consequence, they must not be changed (unless the storage
+ * format version changes).
+ *
* This header file only defines preprocessor macros.
*/
@@ -30,6 +35,18 @@
/* PSA error codes */
+/* Error codes are standardized across PSA domains (framework, crypto, storage,
+ * etc.). Do not change the values in this section or even the expansions
+ * of each macro: it must be possible to `#include` both this header
+ * and some other PSA component's headers in the same C source,
+ * which will lead to duplicate definitions of the `PSA_SUCCESS` and
+ * `PSA_ERROR_xxx` macros, which is ok if and only if the macros expand
+ * to the same sequence of tokens.
+ *
+ * If you must add a new
+ * value, check with the Arm PSA framework group to pick one that other
+ * domains aren't already using. */
+
/** The action was completed successfully. */
#ifndef PSA_SUCCESS
#define PSA_SUCCESS ((psa_status_t)0)
@@ -308,6 +325,12 @@
* @{
*/
+/* Note that key type values, including ECC family and DH group values, are
+ * embedded in the persistent key store, as part of key metadata. As a
+ * consequence, they must not be changed (unless the storage format version
+ * changes).
+ */
+
/** An invalid key type value.
*
* Zero is not the encoding of any key type.
@@ -458,8 +481,7 @@
#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x2400)
/** Key for a cipher, AEAD or MAC algorithm based on the
- * ARIA block cipher.
- */
+ * ARIA block cipher. */
#define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406)
/** Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
@@ -474,16 +496,19 @@
#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x2301)
/** Key for a cipher, AEAD or MAC algorithm based on the
- * Camellia block cipher.
- */
+ * Camellia block cipher. */
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403)
/** Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.
*
* ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539.
*
- * Implementations must support 12-byte nonces, may support 8-byte nonces,
- * and should reject other sizes.
+ * \note For ChaCha20 and ChaCha20_Poly1305, Mbed TLS only supports
+ * 12-byte nonces.
+ *
+ * \note For ChaCha20, the initial counter value is 0. To encrypt or decrypt
+ * with the initial counter value 1, you can process and discard a
+ * 64-byte block before the real data.
*/
#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004)
@@ -546,6 +571,9 @@
((type) & PSA_KEY_TYPE_ECC_CURVE_MASK) : \
0))
+/** Check if the curve of given family is Weierstrass elliptic curve. */
+#define PSA_ECC_FAMILY_IS_WEIERSTRASS(family) ((family & 0xc0) == 0)
+
/** SEC Koblitz curves over prime fields.
*
* This family comprises the following curves:
@@ -705,6 +733,11 @@
1u << PSA_GET_KEY_TYPE_BLOCK_SIZE_EXPONENT(type) : \
0u)
+/* Note that algorithm values are embedded in the persistent key store,
+ * as part of key metadata. As a consequence, they must not be changed
+ * (unless the storage format version changes).
+ */
+
/** Vendor-defined algorithm flag.
*
* Algorithms defined by this standard will never have the #PSA_ALG_VENDOR_FLAG
@@ -1446,7 +1479,7 @@
* with a random per-message secret number (*k*).
*
* The representation of the signature as a byte string consists of
- * the concatentation of the signature values *r* and *s*. Each of
+ * the concatenation of the signature values *r* and *s*. Each of
* *r* and *s* is encoded as an *N*-octet string, where *N* is the length
* of the base point of the curve in octets. Each value is represented
* in big-endian order (most significant octet first).
@@ -1727,6 +1760,12 @@
* You may pass #PSA_KEY_DERIVATION_INPUT_INFO at any time after steup and before
* starting to generate output.
*
+ * \warning HKDF processes the salt as follows: first hash it with hash_alg
+ * if the salt is longer than the block size of the hash algorithm; then
+ * pad with null bytes up to the block size. As a result, it is possible
+ * for distinct salt inputs to result in the same outputs. To ensure
+ * unique outputs, it is recommended to use a fixed length for salt values.
+ *
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
*
@@ -1752,6 +1791,112 @@
#define PSA_ALG_HKDF_GET_HASH(hkdf_alg) \
(PSA_ALG_CATEGORY_HASH | ((hkdf_alg) & PSA_ALG_HASH_MASK))
+#define PSA_ALG_HKDF_EXTRACT_BASE ((psa_algorithm_t)0x08000400)
+/** Macro to build an HKDF-Extract algorithm.
+ *
+ * For example, `PSA_ALG_HKDF_EXTRACT(PSA_ALG_SHA256)` is
+ * HKDF-Extract using HMAC-SHA-256.
+ *
+ * This key derivation algorithm uses the following inputs:
+ * - PSA_KEY_DERIVATION_INPUT_SALT is the salt.
+ * - PSA_KEY_DERIVATION_INPUT_SECRET is the input keying material used in the
+ * "extract" step.
+ * The inputs are mandatory and must be passed in the order above.
+ * Each input may only be passed once.
+ *
+ * \warning HKDF-Extract is not meant to be used on its own. PSA_ALG_HKDF
+ * should be used instead if possible. PSA_ALG_HKDF_EXTRACT is provided
+ * as a separate algorithm for the sake of protocols that use it as a
+ * building block. It may also be a slight performance optimization
+ * in applications that use HKDF with the same salt and key but many
+ * different info strings.
+ *
+ * \warning HKDF processes the salt as follows: first hash it with hash_alg
+ * if the salt is longer than the block size of the hash algorithm; then
+ * pad with null bytes up to the block size. As a result, it is possible
+ * for distinct salt inputs to result in the same outputs. To ensure
+ * unique outputs, it is recommended to use a fixed length for salt values.
+ *
+ * \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 HKDF-Extract algorithm.
+ * \return Unspecified if \p hash_alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_HKDF_EXTRACT(hash_alg) \
+ (PSA_ALG_HKDF_EXTRACT_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+/** Whether the specified algorithm is an HKDF-Extract algorithm.
+ *
+ * HKDF-Extract is a family of key derivation algorithms that are based
+ * on a hash function and the HMAC construction.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \c alg is an HKDF-Extract 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_HKDF_EXTRACT(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE)
+
+#define PSA_ALG_HKDF_EXPAND_BASE ((psa_algorithm_t)0x08000500)
+/** Macro to build an HKDF-Expand algorithm.
+ *
+ * For example, `PSA_ALG_HKDF_EXPAND(PSA_ALG_SHA256)` is
+ * HKDF-Expand using HMAC-SHA-256.
+ *
+ * This key derivation algorithm uses the following inputs:
+ * - PSA_KEY_DERIVATION_INPUT_SECRET is the pseudorandom key (PRK).
+ * - PSA_KEY_DERIVATION_INPUT_INFO is the info string.
+ *
+ * The inputs are mandatory and must be passed in the order above.
+ * Each input may only be passed once.
+ *
+ * \warning HKDF-Expand is not meant to be used on its own. `PSA_ALG_HKDF`
+ * should be used instead if possible. `PSA_ALG_HKDF_EXPAND` is provided as
+ * a separate algorithm for the sake of protocols that use it as a building
+ * block. It may also be a slight performance optimization in applications
+ * that use HKDF with the same salt and key but many different info strings.
+ *
+ * \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 HKDF-Expand algorithm.
+ * \return Unspecified if \p hash_alg is not a supported
+ * hash algorithm.
+ */
+#define PSA_ALG_HKDF_EXPAND(hash_alg) \
+ (PSA_ALG_HKDF_EXPAND_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
+/** Whether the specified algorithm is an HKDF-Expand algorithm.
+ *
+ * HKDF-Expand is a family of key derivation algorithms that are based
+ * on a hash function and the HMAC construction.
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \c alg is an HKDF-Expand 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_HKDF_EXPAND(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE)
+
+/** Whether the specified algorithm is an HKDF or HKDF-Extract or
+ * HKDF-Expand algorithm.
+ *
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \c alg is any HKDF type 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_ANY_HKDF(alg) \
+ (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_BASE || \
+ ((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXTRACT_BASE || \
+ ((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_HKDF_EXPAND_BASE)
+
#define PSA_ALG_TLS12_PRF_BASE ((psa_algorithm_t)0x08000200)
/** Macro to build a TLS-1.2 PRF algorithm.
*
@@ -1807,13 +1952,37 @@
* This key derivation algorithm uses the following inputs, which must be
* passed in the order given here:
* - #PSA_KEY_DERIVATION_INPUT_SEED is the seed.
+ * - #PSA_KEY_DERIVATION_INPUT_OTHER_SECRET is the other secret for the
+ * computation of the premaster secret. This input is optional;
+ * if omitted, it defaults to a string of null bytes with the same length
+ * as the secret (PSK) input.
* - #PSA_KEY_DERIVATION_INPUT_SECRET is the secret key.
* - #PSA_KEY_DERIVATION_INPUT_LABEL is the label.
*
* For the application to TLS-1.2, the seed (which is
* forwarded to the TLS-1.2 PRF) is the concatenation of the
* ClientHello.Random + ServerHello.Random,
- * and the label is "master secret" or "extended master secret".
+ * the label is "master secret" or "extended master secret" and
+ * the other secret depends on the key exchange specified in the cipher suite:
+ * - for a plain PSK cipher suite (RFC 4279, Section 2), omit
+ * PSA_KEY_DERIVATION_INPUT_OTHER_SECRET
+ * - for a DHE-PSK (RFC 4279, Section 3) or ECDHE-PSK cipher suite
+ * (RFC 5489, Section 2), the other secret should be the output of the
+ * PSA_ALG_FFDH or PSA_ALG_ECDH key agreement performed with the peer.
+ * The recommended way to pass this input is to use a key derivation
+ * algorithm constructed as
+ * PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg))
+ * and to call psa_key_derivation_key_agreement(). Alternatively,
+ * this input may be an output of `psa_raw_key_agreement()` passed with
+ * psa_key_derivation_input_bytes(), or an equivalent input passed with
+ * psa_key_derivation_input_bytes() or psa_key_derivation_input_key().
+ * - for a RSA-PSK cipher suite (RFC 4279, Section 4), the other secret
+ * should be the 48-byte client challenge (the PreMasterSecret of
+ * (RFC 5246, Section 7.4.7.1)) concatenation of the TLS version and
+ * a 46-byte random string chosen by the client. On the server, this is
+ * typically an output of psa_asymmetric_decrypt() using
+ * PSA_ALG_RSA_PKCS1V15_CRYPT, passed to the key derivation operation
+ * with `psa_key_derivation_input_bytes()`.
*
* For example, `PSA_ALG_TLS12_PSK_TO_MS(PSA_ALG_SHA256)` represents the
* TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.
@@ -2057,6 +2226,11 @@
* @{
*/
+/* Note that location and persistence level values are embedded in the
+ * persistent key store, as part of key metadata. As a consequence, they
+ * must not be changed (unless the storage format version changes).
+ */
+
/** The default lifetime for volatile keys.
*
* A volatile key only exists as long as the identifier to it is not destroyed.
@@ -2172,6 +2346,11 @@
#define PSA_KEY_LOCATION_VENDOR_FLAG ((psa_key_location_t)0x800000)
+/* Note that key identifier values are embedded in the
+ * persistent key store, as part of key metadata. As a consequence, they
+ * must not be changed (unless the storage format version changes).
+ */
+
/** The null key identifier.
*/
#define PSA_KEY_ID_NULL ((psa_key_id_t)0)
@@ -2194,6 +2373,11 @@
* @{
*/
+/* Note that key usage flags are embedded in the
+ * persistent key store, as part of key metadata. As a consequence, they
+ * must not be changed (unless the storage format version changes).
+ */
+
/** Whether the key may be exported.
*
* A public key or the public part of a key pair may always be exported
@@ -2320,6 +2504,9 @@
* @{
*/
+/* Key input steps are not embedded in the persistent storage, so you can
+ * change them if needed: it's only an ABI change. */
+
/** A secret input for key derivation.
*
* This should be a key of type #PSA_KEY_TYPE_DERIVE
@@ -2355,6 +2542,16 @@
*/
#define PSA_KEY_DERIVATION_INPUT_PASSWORD ((psa_key_derivation_step_t)0x0102)
+/** A high-entropy additional secret input for key derivation.
+ *
+ * This is typically the shared secret resulting from a key agreement obtained
+ * via `psa_key_derivation_key_agreement()`. It may alternatively be a key of
+ * type `PSA_KEY_TYPE_DERIVE` passed to `psa_key_derivation_input_key()`, or
+ * a direct input passed to `psa_key_derivation_input_bytes()`.
+ */
+#define PSA_KEY_DERIVATION_INPUT_OTHER_SECRET \
+ ((psa_key_derivation_step_t)0x0103)
+
/** A label for key derivation.
*
* This should be a direct input.