Add TLS-1.2 EC J-PAKE-to-PMS KDF algorithm

Author: athoelke

doc/crypto/api.db/psa/crypto.h

@@ -142,6 +142,7 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0200000d)
 #define PSA_ALG_SM3 ((psa_algorithm_t)0x02000014)
 #define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800100)
+#define PSA_ALG_TLS12_ECJPAKE_TO_PMS ((psa_algorithm_t)0x08000609)
 #define PSA_ALG_TLS12_PRF(hash_alg) /* specification-defined value */
 #define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) /* specification-defined value */
 #define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
@@ -300,6 +301,7 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #define PSA_SIGNATURE_MAX_SIZE /* implementation-defined value */
 #define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
     /* implementation-defined value */
+#define PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE 32
 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */
 psa_status_t psa_aead_abort(psa_aead_operation_t * operation);
 psa_status_t psa_aead_decrypt(psa_key_id_t key,

doc/crypto/api/ops/kdf.rst

@@ -226,6 +226,28 @@ Key derivation algorithms
         | `PSA_KEY_TYPE_DERIVE` (for the PSK)
         | `PSA_KEY_TYPE_RAW_DATA` (for the other inputs)
 
+.. macro:: PSA_ALG_TLS12_ECJPAKE_TO_PMS
+    :definition: ((psa_algorithm_t)0x08000609)
+
+    .. summary::
+        The TLS 1.2 ECJPAKE-to-PMS key-derivation algorithm.
+
+    This KDF is defined in :cite-title:`TLS-ECJPAKE` §8.7. This specifies the use of a KDF to derive the TLS 1.2 session secrets from the output of EC J-PAKE over the secp256r1 Elliptic curve (the 256-bit curve in `PSA_ECC_FAMILY_SECP_R1`). EC J-PAKE operations can be performed using the extension to the |API| defined in :cite-title:`PSA-PAKE`.
+
+    This KDF takes the shared secret *K* (an uncompressed EC point in case of EC J-PAKE) and calculates SHA256(*K.X*).
+
+    This function takes a single input:
+
+    *   `PSA_KEY_DERIVATION_INPUT_SECRET` is the shared secret K from EC J-PAKE. For secp256r1, the input is exactly 65 bytes.
+
+        The input can be supplied to the key derivation operation by calling :code:`psa_pake_get_implicit_key()`, part of the PAKE extension API defined in :cite:`PSA-PAKE`.
+
+    The 32-byte output has to be read in a single call to either `psa_key_derivation_output_bytes()` or `psa_key_derivation_output_key()`. The size of the output is defined as `PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE`.
+
+    .. subsection:: Compatible key types
+
+        None --- the secret input is extracted from a PAKE operation by calling :code:`psa_pake_get_implicit_key()`.
+
 .. macro:: PSA_ALG_PBKDF2_HMAC
     :definition: /* specification-defined value */
 
@@ -1139,3 +1161,11 @@ Support macros
         TLS implementations supporting these cipher suites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.
 
     Therefore, it is recommended that implementations define `PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE` with a value greater than or equal to ``64``.
+
+.. macro:: PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE
+    :definition: 32
+
+    .. summary::
+        The size of the output from the TLS 1.2 ECJPAKE-to-PMS key-derivation algorithm, in bytes.
+
+    This value can be used when extracting the result of a key-derivation operation that was set up with the `PSA_ALG_TLS12_ECJPAKE_TO_PMS` algorithm.

doc/crypto/appendix/encodings.rst

@@ -268,6 +268,7 @@ The permitted values of HASH-TYPE (see :numref:`table-hash-type`) depend on the
     HKDF, 0, ``0x01``, :code:`PSA_ALG_HKDF(hash_alg)`, ``0x080001hh`` :sup:`a`
     TLS-1.2 PRF, 0, ``0x02``, :code:`PSA_ALG_TLS12_PRF(hash_alg)`, ``0x080002hh`` :sup:`a`
     TLS-1.2 PSK-to-MasterSecret, 0, ``0x03``, :code:`PSA_ALG_TLS12_PSK_TO_MS(hash_alg)`, ``0x080003hh`` :sup:`a`
+    TLS 1.2 ECJPAKE-to-PMS, 0, ``0x06``, :code:`PSA_ALG_TLS12_ECJPAKE_TO_PMS`, ``0x08000609``
     HKDF-Extract, 0, ``0x04``, :code:`PSA_ALG_HKDF_EXTRACT(hash_alg)`, ``0x080004hh`` :sup:`a`
     HKDF-Expand, 0, ``0x05``, :code:`PSA_ALG_HKDF_EXPAND(hash_alg)`, ``0x080005hh`` :sup:`a`
     PBKDF2-HMAC, 1, ``0x01``, :code:`PSA_ALG_PBKDF2_HMAC(hash_alg)`, ``0x088001hh`` :sup:`a`

doc/crypto/appendix/history.rst

@@ -17,6 +17,8 @@ Changes between *1.1.2* and *1.2.0*
 Changes to the API
 ~~~~~~~~~~~~~~~~~~
 
+*   Added support for TLS 1.2 ECJPAKE-to-PMS key-derivation. See `PSA_ALG_TLS12_ECJPAKE_TO_PMS`.
+
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/crypto/references

@@ -335,3 +335,9 @@
     :title: On the Security of PKCS #11
     :url: link.springer.com/chapter/10.1007/978-3-540-45238-6_32
     :publication: 2003
+
+.. reference:: TLS-ECJPAKE
+    :title: Elliptic Curve J-PAKE Cipher Suites for Transport Layer Security (TLS)
+    :author: Cragie, Hao
+    :publication: June 2016
+    :url: datatracker.ietf.org/doc/html/draft-cragie-tls-ecjpake-01