Skip to content

Include IANA reference in the definition of ECC curves and DH groups #279

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Oct 11, 2019
+123 −8
Merged

Include IANA reference in the definition of ECC curves and DH groups #279

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c6f03ef
Include IANA reference in the definition of ECC curves and DH groups
athoelke Sep 24, 2019
c625045
Tighten up language regarding direct use of the IANA registry values
athoelke Sep 25, 2019
fd368e5
Support for vendor-defined ECC curves and DH groups
athoelke Sep 25, 2019
214064e
Xref documentation for ECC curves and DH groups.
athoelke Sep 25, 2019
691ec52
Remove over-specific RFC references
athoelke Oct 7, 2019
6e59505
Recommend use of GREASE values for vendor defined DH groups
athoelke Oct 7, 2019
43326f0
Change PSA_DH_GROUP_CUSTOM to not be in the vendor-defined range
gilles-peskine-arm Oct 9, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions include/psa/crypto_extra.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)


/**
Expand Down
76 changes: 74 additions & 2 deletions include/psa/crypto_types.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,82 @@ 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 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
* TLS EC Named Curve Registry)
* https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
*
* 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;

/** The type of PSA Diffie-Hellman group identifiers. */
/** 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
* TLS EC Named Curve Registry)
* https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8
*
* 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. 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.
*
* 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;

/** \brief Encoding of a cryptographic algorithm.
Expand Down
50 changes: 46 additions & 4 deletions include/psa/crypto_values.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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))

Expand Down Expand Up @@ -495,13 +503,34 @@
*/
#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)
/** 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))

Expand Down Expand Up @@ -535,6 +564,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`.
Copy link
Collaborator

@gilles-peskine-arm gilles-peskine-arm Oct 3, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, this is a ridiculously small range whereas an implementation may well wish to define many custom groups, since many groups have been common in the wild and specific systems or protocols may define their own groups.

The TLS registry puts EC and FF groups in the same 16-bit range, but we don't have to. I propose to use some values in the IANA EC range for vendor FF groups. We can in particular use the GREASE values, which TLS uses for the purpose of not having a corresponding cryptographic algorithm.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a quick glance, the proposed GREASE values that can be used in this way are:

0x0A0A, 0x1A1A, 0x2A2A, 0x3A3A, 0x4A4A, 0x5A5A, 0x6A6A, 0x7A7A,
0x8A8A, 0x9A9A, 0xAAAA, 0xBABA, 0xCACA, 0xDADA, 0xEAEA, 0xFAFA

This is still draft and subject to change. This might not affect this API element, but should modify the documentation of psa_dh_group_t.

  1. Is the suggestion to directly list the values, as being permitted for vendor-defined additional DH groups, or indirectly by referencing the specification draft?
  2. Do we want to slice up the GREASE identifiers, and reserve a set for PSA Crypto future use?
  3. Is the [arbitrary] 50/50 split of the TLS support group private use range appropriate (for this and ECC)?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal was to define the GREASE values (stated by value, with the GREASE spec given as an informative rationale) as reserved for vendors in psa_dh_group_t.

Though given that there are only 16 of them, that's not much. We can punt PSA crypto future use until later, but I do think we need more vendor FFDH values. I guess the only solution (short of moving to a bigger type) is to take values that are already assigned to elliptic curves and declare them as vendor-specific FFDH values.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added a commit the extends the recommendations for vendor defined DH groups.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@athoelke To confirm, this range is still accurate, but the GREASE values are also available so the practical use of this range is limited.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that is correct. An minor improvement might be to refer to the psa_dh_group_t definition and its description of other ways to allocate a vendor-defined group number.

However, I'd like this merged sooner so I can render the reST and separate the specification from the doxygen source code, which is a pre-requistite to completing the remaing API changes before publishing 1.0.0 of the spec. I can clarify/improve the text after the split if desirable.

*/
#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).
Expand Down