From 8851c40d8597917d56d7abae33aeac8a1ec44a5b Mon Sep 17 00:00:00 2001
From: Jaeden Amero <jaeden.amero@arm.com>
Date: Fri, 11 Jan 2019 14:20:03 +0000
Subject: [PATCH] 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.
---
 include/psa/crypto.h        | 29 +++++++++++++++++++++++++++++
 include/psa/crypto_values.h |  9 +++++++++
 2 files changed, 38 insertions(+)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 57edf7c89..7f9daa904 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -387,6 +387,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 &sect;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 @@ psa_status_t psa_get_key_domain_parameters(psa_key_handle_t handle,
  *   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 @@ psa_status_t psa_export_key(psa_key_handle_t handle,
  *   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 @@ 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.
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 4d25835be..2e24b7c3b 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).