From 214064ea85a92980b22eb32fefbef3e138db83ce Mon Sep 17 00:00:00 2001
From: Andrew Thoelke <andrew.thoelke@arm.com>
Date: Wed, 25 Sep 2019 22:16:21 +0100
Subject: [PATCH] Xref documentation for ECC curves and DH groups.

Connect the types to the key type construction macros by x-refs.
---
 include/psa/crypto_types.h  |  8 ++++++++
 include/psa/crypto_values.h | 24 ++++++++++++++++++++----
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h
index 521a765a0..fbbb737ae 100644
--- a/include/psa/crypto_types.h
+++ b/include/psa/crypto_types.h
@@ -66,6 +66,10 @@ typedef int32_t psa_status_t;
 typedef uint32_t psa_key_type_t;
 
 /** 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
@@ -89,6 +93,10 @@ typedef uint32_t psa_key_type_t;
 typedef uint16_t psa_ecc_curve_t;
 
 /** 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
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 58276c90b..ca04c4a7a 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -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))
 
@@ -511,10 +519,18 @@
 #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))