psa: Add DH key exchange keys
Add the ability to specify Diffie-Hellman key exchange keys. Specify the
import/export format as well, even though importing and exporting isn't
implemented yet.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 57edf7c..7f9daa9 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -387,6 +387,21 @@
* g INTEGER
* }
* ```
+ * - For Diffie-Hellman key exchange keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY), the
+ * `DomainParameters` format as defined by RFC 3279 §2.3.3.
+ * ```
+ * DomainParameters ::= SEQUENCE {
+ * p INTEGER, -- odd prime, p=jq +1
+ * g INTEGER, -- generator, g
+ * q INTEGER, -- factor of p-1
+ * j INTEGER OPTIONAL, -- subgroup factor
+ * validationParms ValidationParms OPTIONAL
+ * }
+ * ValidationParms ::= SEQUENCE {
+ * seed BIT STRING,
+ * pgenCounter INTEGER
+ * }
+ * ```
*
* \param handle Handle to the key to set domain parameters for.
* \param[in] data Buffer containing the key domain parameters. The content
@@ -494,6 +509,10 @@
* 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
+ * 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).
* - For public keys (key types for which #PSA_KEY_TYPE_IS_PUBLIC_KEY is
* true), the format is the same as for psa_export_public_key().
*
@@ -560,6 +579,10 @@
* 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),
+ * 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.
*
* \param handle Handle to the key to export.
* \param[out] data Buffer where the key data is to be written.
@@ -2304,6 +2327,12 @@
* parameters. The key domain parameters can also be
* provided by psa_set_key_domain_parameters(),
* which documents the format of the structure.
+ * - For a DH key (\p type is
+ * #PSA_KEY_TYPE_DH_KEYPAIR), the \p extra is an
+ * optional structure specifying the key domain
+ * parameters. The key domain parameters can also be
+ * provided by psa_set_key_domain_parameters(),
+ * which documents the format of the structure.
* \param extra_size Size of the buffer that \p extra
* points to, in bytes. Note that if \p extra is
* \c NULL then \p extra_size must be zero.
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 4d25835..2e24b7c 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -497,6 +497,15 @@
#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)
+
/** The block size of a block cipher.
*
* \param type A cipher key type (value of type #psa_key_type_t).