From 47e79fb5ab354b9f2214e85cae86e2c865cd1aff Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Fri, 8 Feb 2019 11:24:59 +0100
Subject: [PATCH] Fix minor errors in key derivation and key agreement
 documentation

---
 include/psa/crypto.h        | 10 +++++++---
 include/psa/crypto_values.h | 32 +++++++++++++++++---------------
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 3ed5f0f51..b2f3eb28f 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3129,9 +3129,9 @@ psa_status_t psa_key_derivation_input_key(psa_crypto_generator_t *generator,
  *                          public key type corresponding to the type of
  *                          private_key. That is, this function performs the
  *                          equivalent of
- *                          `psa_import_key(internal_public_key_handle,
- *                          PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(private_key_type),
- *                          peer_key, peer_key_length)` where
+ *                          #psa_import_key(`internal_public_key_handle`,
+ *                          #PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(`private_key_type`),
+ *                          `peer_key`, `peer_key_length`) where
  *                          `private_key_type` is the type of `private_key`.
  *                          For example, for EC keys, this means that peer_key
  *                          is interpreted as a point on the curve that the
@@ -3175,6 +3175,10 @@ psa_status_t psa_key_agreement(psa_crypto_generator_t *generator,
  * a key derivation, use psa_key_agreement() and other functions from
  * the key derivation and generator interface.
  *
+ * \param alg                     The key agreement algorithm to compute
+ *                                (\c PSA_ALG_XXX value such that
+ *                                #PSA_ALG_IS_RAW_KEY_AGREEMENT(\p alg)
+ *                                is true).
  * \param private_key             Handle to the private key to use.
  * \param[in] peer_key            Public key of the peer. It must be
  *                                in the same format that psa_import_key()
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 76c5f38a1..29a64c27a 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -613,7 +613,6 @@
 #define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg)                           \
     (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)
 
-#define PSA_ALG_KEY_SELECTION_FLAG              ((psa_algorithm_t)0x01000000)
 /** Whether the specified algorithm is a key agreement algorithm.
  *
  * \param alg An algorithm identifier (value of type #psa_algorithm_t).
@@ -623,8 +622,7 @@
  *         algorithm identifier.
  */
 #define PSA_ALG_IS_KEY_AGREEMENT(alg)                                   \
-    (((alg) & PSA_ALG_CATEGORY_MASK & ~PSA_ALG_KEY_SELECTION_FLAG) ==   \
-     PSA_ALG_CATEGORY_KEY_AGREEMENT)
+    (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)
 
 /** Whether the specified algorithm is a key derivation algorithm.
  *
@@ -637,17 +635,6 @@
 #define PSA_ALG_IS_KEY_DERIVATION(alg)                                  \
     (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
 
-/** Whether the specified algorithm is a key selection algorithm.
- *
- * \param alg An algorithm identifier (value of type #psa_algorithm_t).
- *
- * \return 1 if \p alg is a key selection algorithm, 0 otherwise.
- *         This macro may return either 0 or 1 if \p alg is not a supported
- *         algorithm identifier.
- */
-#define PSA_ALG_IS_KEY_SELECTION(alg)                                   \
-    (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_SELECTION)
-
 #define PSA_ALG_HASH_MASK                       ((psa_algorithm_t)0x000000ff)
 
 #define PSA_ALG_MD2                             ((psa_algorithm_t)0x01000001)
@@ -1313,8 +1300,23 @@
 #define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg)                             \
     (((alg) & PSA_ALG_KEY_AGREEMENT_MASK) | PSA_ALG_CATEGORY_KEY_AGREEMENT)
 
+/** Whether the specified algorithm is a raw key agreement algorithm.
+ *
+ * A raw key agreement algorithm is one that does not specify
+ * a key derivation function.
+ * Usually, raw key agreement algorithms are constructed directly with
+ * a \c PSA_ALG_xxx macro while non-raw key agreement algorithms are
+ * constructed with PSA_ALG_KEY_AGREEMENT().
+ *
+ * \param alg An algorithm identifier (value of type #psa_algorithm_t).
+ *
+ * \return 1 if \p alg is a raw key agreement algorithm, 0 otherwise.
+ *         This macro may return either 0 or 1 if \p alg is not a supported
+ *         algorithm identifier.
+ */
 #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg)                               \
-    (PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION)
+    (PSA_ALG_IS_KEY_AGREEMENT(alg) &&                                   \
+     PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) == PSA_ALG_CATEGORY_KEY_DERIVATION)
 
 #define PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT(alg)     \
     ((PSA_ALG_IS_KEY_DERIVATION(alg) || PSA_ALG_IS_KEY_AGREEMENT(alg)))