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.

Author: Patater

include/psa/crypto.h

@@ -381,6 +381,21 @@ psa_status_t psa_get_key_information(psa_key_handle_t handle,
  *      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
+ *   }
+ *   ```
  * Must call before import key. If you want, you can call before generate key
  * or use extra to pass the domain parameters.
  *
@@ -446,6 +461,9 @@ psa_status_t psa_get_key_domain_parameters(uint8_t *data,
  *   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 a representation of the private key `x` as a big-endian byte
+ *   string.
  * - 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().
  *
@@ -519,6 +537,9 @@ psa_status_t psa_export_key(psa_key_handle_t handle,
  *      -- where `m` is the bit size associated with the curve,
  *      --       i.e. the bit size of `q` for a curve over `F_q`.
  *   ```
+ * - For Diffie-Hellman key exchange public keys (#PSA_KEY_TYPE_DH_PUBLIC_KEY),
+ *   the format is a representation of the public key `y` (`g^x mod p`) as a
+ *   big-endian byte string.
  *
  * \param handle            Handle to the key to export.
  * \param[out] data         Buffer where the key data is to be written.
@@ -2256,6 +2277,12 @@ typedef struct {
  *                            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.

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).