From 37c81c4f05765e27ba2907fec178b6f66556dc00 Mon Sep 17 00:00:00 2001
From: Przemek Stekiel <przemyslaw.stekiel@mobica.com>
Date: Thu, 7 Apr 2022 13:38:53 +0200
Subject: [PATCH] Extend PSA_ALG_TLS12_PSK_TO_MS alg (add
 #PSA_KEY_DERIVATION_INPUT_OTHER_SECRET input)

Signed-off-by: Przemek Stekiel <przemyslaw.stekiel@mobica.com>
---
 include/psa/crypto_values.h | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 3e7afef02c..2f9a15a820 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -1817,13 +1817,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.
@@ -2454,6 +2478,16 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
  */
 #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.