From c6f03ef6d4808e11a9e262e620085deace95f7e5 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 24 Sep 2019 13:19:49 +0100 Subject: [PATCH 1/7] Include IANA reference in the definition of ECC curves and DH groups Fixes ARMmbed/psa-crypto#262 --- include/psa/crypto_types.h | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index b6b61984b..f9811bdfe 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -65,10 +65,24 @@ typedef int32_t psa_status_t; */ typedef uint32_t psa_key_type_t; -/** The type of PSA elliptic curve identifiers. */ +/** The type of PSA elliptic curve identifiers. + * + * The encoding of curve identifiers is aligned with the + * TLS Supported Groups Registry (formerly known as the + * TLS EC Named Curve Registry) + * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 + * The values are defined by RFC 8422 and RFC 7027. + */ typedef uint16_t psa_ecc_curve_t; -/** The type of PSA Diffie-Hellman group identifiers. */ +/** The type of PSA Diffie-Hellman group identifiers. + * + * The encoding of group identifiers is aligned with the + * TLS Supported Groups Registry (formerly known as the + * TLS EC Named Curve Registry) + * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 + * The values are defined by RFC 7919. + */ typedef uint16_t psa_dh_group_t; /** \brief Encoding of a cryptographic algorithm. From c625045da6d7f55d830dd3fe90505abe1bfc2072 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 25 Sep 2019 22:11:36 +0100 Subject: [PATCH 2/7] Tighten up language regarding direct use of the IANA registry values --- include/psa/crypto_types.h | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index f9811bdfe..03fe9bc42 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -67,21 +67,29 @@ typedef uint32_t psa_key_type_t; /** The type of PSA elliptic curve identifiers. * - * The encoding of curve identifiers is aligned with the + * The encoding of curve identifiers is taken from the * TLS Supported Groups Registry (formerly known as the * TLS EC Named Curve Registry) * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 * The values are defined by RFC 8422 and RFC 7027. + * + * This specification defines identifiers for some of the curves in the IANA + * registry. Implementations that support other curves that are in the IANA + * registry should use the IANA value and a implementation-specific identifier. */ typedef uint16_t psa_ecc_curve_t; /** The type of PSA Diffie-Hellman group identifiers. * - * The encoding of group identifiers is aligned with the + * The encoding of group identifiers is taken from the * TLS Supported Groups Registry (formerly known as the * TLS EC Named Curve Registry) * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 * The values are defined by RFC 7919. + * + * This specification defines identifiers for some of the groups in the IANA + * registry. Implementations that support other groups that are in the IANA + * registry should use the IANA value and a implementation-specific identifier. */ typedef uint16_t psa_dh_group_t; From fd368e50d5ffd93e52235db0b6480d746ffdffda Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 25 Sep 2019 22:14:29 +0100 Subject: [PATCH 3/7] Support for vendor-defined ECC curves and DH groups Define a vendor-range within the the private use ranges in the IANA registry. Provide recommendations for how to support vendor-defined curves and groups. --- include/psa/crypto_types.h | 18 ++++++++++++++++++ include/psa/crypto_values.h | 26 ++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index 03fe9bc42..521a765a0 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -76,6 +76,15 @@ typedef uint32_t psa_key_type_t; * This specification defines identifiers for some of the curves in the IANA * registry. Implementations that support other curves that are in the IANA * registry should use the IANA value and a implementation-specific identifier. + * Implemenations that support non-IANA curves should use one of the following + * approaches for allocating a key type: + * + * 1. Select a ::psa_ecc_curve_t value in the range #PSA_ECC_CURVE_VENDOR_MIN to + * #PSA_ECC_CURVE_VENDOR_MAX, which is a subset of the IANA private use + * range. + * 2. Use a ::psa_key_type_t value that is vendor-defined. + * + * The first option is recommended. */ typedef uint16_t psa_ecc_curve_t; @@ -90,6 +99,15 @@ typedef uint16_t psa_ecc_curve_t; * This specification defines identifiers for some of the groups in the IANA * registry. Implementations that support other groups that are in the IANA * registry should use the IANA value and a implementation-specific identifier. + * Implemenations that support non-IANA groups should use one of the following + * approaches for allocating a key type: + * + * 1. Select a ::psa_dh_group_t value in the range #PSA_DH_GROUP_VENDOR_MIN to + * #PSA_DH_GROUP_VENDOR_MAX, which is a subset of the IANA private use + * range. + * 2. Use a ::psa_key_type_t value that is vendor-defined. + * + * The first option is recommended. */ typedef uint16_t psa_dh_group_t; diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index fc0f9637f..58276c90b 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -495,6 +495,19 @@ */ #define PSA_ECC_CURVE_CURVE448 ((psa_ecc_curve_t) 0x001e) +/** Minimum value for a vendor-defined ECC curve identifier + * + * The range for vendor-defined curve identifiers is a subset of the IANA + * registry private use range, `0xfe00` - `0xfeff`. + */ +#define PSA_ECC_CURVE_VENDOR_MIN ((psa_ecc_curve_t) 0xfe00) +/** Maximum value for a vendor-defined ECC curve identifier + * + * The range for vendor-defined curve identifiers is a subset of the IANA + * registry private use range, `0xfe00` - `0xfeff`. + */ +#define PSA_ECC_CURVE_VENDOR_MAX ((psa_ecc_curve_t) 0xfe7f) + #define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t)0x60040000) #define PSA_KEY_TYPE_DH_KEY_PAIR_BASE ((psa_key_type_t)0x70040000) #define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t)0x0000ffff) @@ -535,6 +548,19 @@ #define PSA_DH_GROUP_FFDHE6144 ((psa_dh_group_t) 0x0103) #define PSA_DH_GROUP_FFDHE8192 ((psa_dh_group_t) 0x0104) +/** Minimum value for a vendor-defined Diffie Hellman group identifier + * + * The range for vendor-defined group identifiers is a subset of the IANA + * registry private use range, `0x01fc` - `0x01ff`. + */ +#define PSA_DH_GROUP_VENDOR_MIN ((psa_dh_group_t) 0x01fc) +/** Maximum value for a vendor-defined Diffie Hellman group identifier + * + * The range for vendor-defined group identifiers is a subset of the IANA + * registry private use range, `0x01fc` - `0x01ff`. + */ +#define PSA_DH_GROUP_VENDOR_MAX ((psa_dh_group_t) 0x01fd) + /** The block size of a block cipher. * * \param type A cipher key type (value of type #psa_key_type_t). From 214064ea85a92980b22eb32fefbef3e138db83ce Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 25 Sep 2019 22:16:21 +0100 Subject: [PATCH 4/7] Xref documentation for ECC curves and DH groups. Connect the types to the key type construction macros by x-refs. --- include/psa/crypto_types.h | 8 ++++++++ include/psa/crypto_values.h | 24 ++++++++++++++++++++---- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index 521a765a0..fbbb737ae 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -66,6 +66,10 @@ typedef int32_t psa_status_t; typedef uint32_t psa_key_type_t; /** The type of PSA elliptic curve identifiers. + * + * The curve identifier is required to create an ECC key using the + * PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() + * macros. * * The encoding of curve identifiers is taken from the * TLS Supported Groups Registry (formerly known as the @@ -89,6 +93,10 @@ typedef uint32_t psa_key_type_t; typedef uint16_t psa_ecc_curve_t; /** The type of PSA Diffie-Hellman group identifiers. + * + * The group identifier is required to create an Diffie-Hellman key using the + * PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() + * macros. * * The encoding of group identifiers is taken from the * TLS Supported Groups Registry (formerly known as the diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 58276c90b..ca04c4a7a 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -421,10 +421,18 @@ #define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x60030000) #define PSA_KEY_TYPE_ECC_KEY_PAIR_BASE ((psa_key_type_t)0x70030000) #define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff) -/** Elliptic curve key pair. */ +/** Elliptic curve key pair. + * + * \param curve A value of type ::psa_ecc_curve_t that identifies the + * ECC curve to be used. + */ #define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \ (PSA_KEY_TYPE_ECC_KEY_PAIR_BASE | (curve)) -/** Elliptic curve public key. */ +/** Elliptic curve public key. + * + * \param curve A value of type ::psa_ecc_curve_t that identifies the + * ECC curve to be used. + */ #define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \ (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve)) @@ -511,10 +519,18 @@ #define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t)0x60040000) #define PSA_KEY_TYPE_DH_KEY_PAIR_BASE ((psa_key_type_t)0x70040000) #define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t)0x0000ffff) -/** Diffie-Hellman key pair. */ +/** Diffie-Hellman key pair. + * + * \param group A value of type ::psa_dh_group_t that identifies the + * Diffie-Hellman group to be used. + */ #define PSA_KEY_TYPE_DH_KEY_PAIR(group) \ (PSA_KEY_TYPE_DH_KEY_PAIR_BASE | (group)) -/** Diffie-Hellman public key. */ +/** Diffie-Hellman public key. + * + * \param group A value of type ::psa_dh_group_t that identifies the + * Diffie-Hellman group to be used. + */ #define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \ (PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE | (group)) From 691ec526947fe9f696ee83d1d23561a5a5b5dfd4 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 7 Oct 2019 15:28:36 +0100 Subject: [PATCH 5/7] Remove over-specific RFC references Rely on general reference to IANA documentation --- include/psa/crypto_types.h | 2 -- 1 file changed, 2 deletions(-) diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index fbbb737ae..dfc17a95f 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -75,7 +75,6 @@ typedef uint32_t psa_key_type_t; * TLS Supported Groups Registry (formerly known as the * TLS EC Named Curve Registry) * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 - * The values are defined by RFC 8422 and RFC 7027. * * This specification defines identifiers for some of the curves in the IANA * registry. Implementations that support other curves that are in the IANA @@ -102,7 +101,6 @@ typedef uint16_t psa_ecc_curve_t; * TLS Supported Groups Registry (formerly known as the * TLS EC Named Curve Registry) * https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8 - * The values are defined by RFC 7919. * * This specification defines identifiers for some of the groups in the IANA * registry. Implementations that support other groups that are in the IANA From 6e59505bb297e5a3ea7ad90734c75111122e72b7 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Mon, 7 Oct 2019 22:27:17 +0100 Subject: [PATCH 6/7] Recommend use of GREASE values for vendor defined DH groups --- include/psa/crypto_types.h | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index dfc17a95f..c4f9acd46 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -111,9 +111,35 @@ typedef uint16_t psa_ecc_curve_t; * 1. Select a ::psa_dh_group_t value in the range #PSA_DH_GROUP_VENDOR_MIN to * #PSA_DH_GROUP_VENDOR_MAX, which is a subset of the IANA private use * range. - * 2. Use a ::psa_key_type_t value that is vendor-defined. + * 2. Select a ::psa_dh_group_t value from the named groups allocated for + * GREASE in the IETF draft specification. The GREASE specification and + * values are listed below. + * 3. Use a ::psa_key_type_t value that is vendor-defined. * - * The first option is recommended. + * Option 1 or 2 are recommended. + * + * The current draft of the GREASE specification is + * https://datatracker.ietf.org/doc/draft-ietf-tls-grease + * + * The following GREASE values are allocated for named groups: + * \code + * 0x0A0A + * 0x1A1A + * 0x2A2A + * 0x3A3A + * 0x4A4A + * 0x5A5A + * 0x6A6A + * 0x7A7A + * 0x8A8A + * 0x9A9A + * 0xAAAA + * 0xBABA + * 0xCACA + * 0xDADA + * 0xEAEA + * 0xFAFA + * \endcode */ typedef uint16_t psa_dh_group_t; From 43326f0d1eec9cc95ea411e6d48681b30ad7c246 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 9 Oct 2019 16:43:39 +0200 Subject: [PATCH 7/7] Change PSA_DH_GROUP_CUSTOM to not be in the vendor-defined range --- include/psa/crypto_extra.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index f0e47821c..4329bf828 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -428,8 +428,9 @@ psa_status_t mbedtls_psa_inject_entropy(const uint8_t *seed, * #PSA_KEY_TYPE_DH_KEY_PAIR(#PSA_DH_GROUP_CUSTOM), the group data comes * from domain parameters set by psa_set_key_domain_parameters(). */ -/* This value is reserved for private use in the TLS named group registry. */ -#define PSA_DH_GROUP_CUSTOM ((psa_dh_group_t) 0x01fc) +/* This value is a deprecated value meaning an explicit curve in the IANA + * registry. */ +#define PSA_DH_GROUP_CUSTOM ((psa_dh_group_t) 0xff01) /**