Parametrize Diffie-Hellman keys by a group identifier
Parametrize finite-field Diffie-Hellman key types with a DH group
identifier, in the same way elliptic curve keys are parametrized with
an EC curve identifier.
Define the DH groups from the TLS registry (these are the groups from
RFC 7919).
Replicate the macro definitions and the metadata tests from elliptic
curve identifiers to DH group identifiers.
Define PSA_DH_GROUP_CUSTOM as an implementation-specific extension for
which domain parameters are used to specify the group.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 487fce8..08bdb84 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -656,7 +656,8 @@
* and `PSA_ECC_CURVE_BRAINPOOL_PXXX`).
* This is the content of the `privateKey` field of the `ECPrivateKey`
* format defined by RFC 5915.
- * - For Diffie-Hellman key exchange key pairs (#PSA_KEY_TYPE_DH_KEYPAIR), the
+ * - For Diffie-Hellman key exchange key pairs (key types for which
+ * #PSA_KEY_TYPE_IS_DH_KEYPAIR is true), the
* format is the representation of the private key `x` as a big-endian byte
* string. The length of the byte string is the private key size in bytes
* (leading zeroes are not stripped).
@@ -729,7 +730,8 @@
* representation of the public key `y = g^x mod p` as a big-endian byte
* string. The length of the byte string is the length of the base prime `p`
* in bytes.
- * - For Diffie-Hellman key exchange public keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY),
+ * - For Diffie-Hellman key exchange public keys (key types for which
+ * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true),
* the format is the representation of the public key `y = g^x mod p` as a
* big-endian byte string. The length of the byte string is the length of the
* base prime `p` in bytes.
@@ -3253,7 +3255,8 @@
* discard the first 8 bytes, use the next 8 bytes as the first key,
* and continue reading output from the operation to derive the other
* two keys).
- * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR),
+ * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR(\c group)
+ * where \c group designates any Diffie-Hellman group),
* DSA keys (#PSA_KEY_TYPE_DSA_KEYPAIR), and
* ECC keys on a Weierstrass elliptic curve
* (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h
index 5016ba8..37d9b40 100644
--- a/include/psa/crypto_extra.h
+++ b/include/psa/crypto_extra.h
@@ -449,6 +449,16 @@
* @{
*/
+/** Custom Diffie-Hellman group.
+ *
+ * For keys of type #PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
+ * #PSA_KEY_TYPE_DH_KEYPAIR(#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)
+
+
/**
* \brief Set domain parameters for a key.
*
@@ -475,8 +485,9 @@
* g INTEGER
* }
* ```
- * - For Diffie-Hellman key exchange keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY or
- * #PSA_KEY_TYPE_DH_KEYPAIR), the
+ * - For Diffie-Hellman key exchange keys
+ * (#PSA_KEY_TYPE_DH_PUBLIC_KEY(#PSA_DH_GROUP_CUSTOM) or
+ * #PSA_KEY_TYPE_DH_KEYPAIR(#PSA_DH_GROUP_CUSTOM)), the
* `DomainParameters` format as defined by RFC 3279 §2.3.3.
* ```
* DomainParameters ::= SEQUENCE {
diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index ced42de..02c2678 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -68,6 +68,9 @@
/** The type of PSA elliptic curve identifiers. */
typedef uint16_t psa_ecc_curve_t;
+/** The type of PSA Diffie-Hellman group identifiers. */
+typedef uint16_t psa_dh_group_t;
+
/** \brief Encoding of a cryptographic algorithm.
*
* For algorithms that can be applied to multiple key types, this type
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index c54fc9a..6cd22c8 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -492,14 +492,45 @@
#define PSA_ECC_CURVE_CURVE25519 ((psa_ecc_curve_t) 0x001d)
#define PSA_ECC_CURVE_CURVE448 ((psa_ecc_curve_t) 0x001e)
-/** Diffie-Hellman key exchange public key. */
-#define PSA_KEY_TYPE_DH_PUBLIC_KEY ((psa_key_type_t)0x60040000)
-/** Diffie-Hellman key exchange key pair (private and public key). */
-#define PSA_KEY_TYPE_DH_KEYPAIR ((psa_key_type_t)0x70040000)
-/** Whether a key type is a Diffie-Hellman key exchange key (pair or
- * public-only). */
-#define PSA_KEY_TYPE_IS_DH(type) \
- (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) == PSA_KEY_TYPE_DH_PUBLIC_KEY)
+#define PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE ((psa_key_type_t)0x60040000)
+#define PSA_KEY_TYPE_DH_KEYPAIR_BASE ((psa_key_type_t)0x70040000)
+#define PSA_KEY_TYPE_DH_GROUP_MASK ((psa_key_type_t)0x0000ffff)
+/** Diffie-Hellman key pair. */
+#define PSA_KEY_TYPE_DH_KEYPAIR(group) \
+ (PSA_KEY_TYPE_DH_KEYPAIR_BASE | (group))
+/** Diffie-Hellman public key. */
+#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \
+ (PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE | (group))
+
+/** Whether a key type is a Diffie-Hellman key (pair or public-only). */
+#define PSA_KEY_TYPE_IS_DH(type) \
+ ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) & \
+ ~PSA_KEY_TYPE_DH_GROUP_MASK) == PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE)
+/** Whether a key type is a Diffie-Hellman key pair. */
+#define PSA_KEY_TYPE_IS_DH_KEYPAIR(type) \
+ (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \
+ PSA_KEY_TYPE_DH_KEYPAIR_BASE)
+/** Whether a key type is a Diffie-Hellman public key. */
+#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \
+ (((type) & ~PSA_KEY_TYPE_DH_GROUP_MASK) == \
+ PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE)
+
+/** Extract the group from a Diffie-Hellman key type. */
+#define PSA_KEY_TYPE_GET_GROUP(type) \
+ ((psa_dh_group_t) (PSA_KEY_TYPE_IS_DH(type) ? \
+ ((type) & PSA_KEY_TYPE_DH_GROUP_MASK) : \
+ 0))
+
+/* The encoding of group identifiers is currently 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. */
+#define PSA_DH_GROUP_FFDHE2048 ((psa_dh_group_t) 0x0100)
+#define PSA_DH_GROUP_FFDHE3072 ((psa_dh_group_t) 0x0101)
+#define PSA_DH_GROUP_FFDHE4096 ((psa_dh_group_t) 0x0102)
+#define PSA_DH_GROUP_FFDHE6144 ((psa_dh_group_t) 0x0103)
+#define PSA_DH_GROUP_FFDHE8192 ((psa_dh_group_t) 0x0104)
/** The block size of a block cipher.
*