From dc6f8244f4da7cb11a6d6de58c707d13e6819f55 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 8 Aug 2023 18:33:53 +0100 Subject: [PATCH] Add TLS-1.2 EC J-PAKE-to-PMS KDF algorithm --- doc/crypto/api.db/psa/crypto.h | 2 ++ doc/crypto/api/ops/kdf.rst | 30 ++++++++++++++++++++++++++++++ doc/crypto/appendix/encodings.rst | 1 + doc/crypto/appendix/history.rst | 2 ++ doc/crypto/references | 6 ++++++ 5 files changed, 41 insertions(+) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index db80b884..58de38d9 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/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, diff --git a/doc/crypto/api/ops/kdf.rst b/doc/crypto/api/ops/kdf.rst index 857f45f7..90ce44db 100644 --- a/doc/crypto/api/ops/kdf.rst +++ b/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. diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 14197dc6..692673ce 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/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` diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index dd735e85..e4efca63 100644 --- a/doc/crypto/appendix/history.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/crypto/references b/doc/crypto/references index 8920a6a0..c8dba282 100644 --- a/doc/crypto/references +++ b/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