Merge pull request #47 from gilles-peskine-arm/psa-api-1.0-beta-beta1_minor_fixes

Minor API specification fixes after 1.0beta1

Author: gilles-peskine-arm

include/psa/crypto.h

@@ -754,7 +754,7 @@ psa_status_t psa_export_public_key(psa_key_handle_t handle,
  * to another. The target key retains its lifetime and location.
  *
  * In an implementation where slots have different ownerships,
- * this functin may be used to share a key with a different party,
+ * this function may be used to share a key with a different party,
  * subject to implementation-defined restrictions on key sharing.
  * In this case \p constraint would typically prevent the recipient
  * from exporting the key.
@@ -830,8 +830,7 @@ psa_status_t psa_copy_key(psa_key_handle_t source_handle,
  * \param hash_size         Size of the \p hash buffer in bytes.
  * \param[out] hash_length  On success, the number of bytes
  *                          that make up the hash value. This is always
- *                          #PSA_HASH_SIZE(\c alg) where \c alg is the
- *                          hash algorithm that is calculated.
+ *                          #PSA_HASH_SIZE(\p alg).
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -1139,15 +1138,13 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
  *
  * \param handle            Handle to the key to use for the operation.
  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
- *                          such that #PSA_ALG_IS_MAC(alg) is true).
+ *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
  * \param[in] input         Buffer containing the input message.
  * \param input_length      Size of the \p input buffer in bytes.
  * \param[out] mac          Buffer where the MAC value is to be written.
  * \param mac_size          Size of the \p mac buffer in bytes.
  * \param[out] mac_length   On success, the number of bytes
- *                          that make up the mac value. This is always
- *                          #PSA_HASH_SIZE(\c alg) where \c alg is the
- *                          hash algorithm that is calculated.
+ *                          that make up the MAC value.
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -1179,7 +1176,7 @@ psa_status_t psa_mac_compute(psa_key_handle_t handle,
  *
  * \param handle            Handle to the key to use for the operation.
  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
- *                          such that #PSA_ALG_IS_MAC(alg) is true).
+ *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
  * \param[in] input         Buffer containing the input message.
  * \param input_length      Size of the \p input buffer in bytes.
  * \param[out] mac          Buffer containing the expected MAC value.
@@ -1289,7 +1286,7 @@ static psa_mac_operation_t psa_mac_operation_init(void);
  *                          It must remain valid until the operation
  *                          terminates.
  * \param alg               The MAC algorithm to compute (\c PSA_ALG_XXX value
- *                          such that #PSA_ALG_IS_MAC(alg) is true).
+ *                          such that #PSA_ALG_IS_MAC(\p alg) is true).
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -1962,7 +1959,7 @@ psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
  *                                #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
  *                                \p plaintext_length).
  * \param[out] ciphertext_length  On success, the size of the output
- *                                in the \b ciphertext buffer.
+ *                                in the \p ciphertext buffer.
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -2018,7 +2015,7 @@ psa_status_t psa_aead_encrypt(psa_key_handle_t handle,
  *                                #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
  *                                \p ciphertext_length).
  * \param[out] plaintext_length   On success, the size of the output
- *                                in the \b plaintext buffer.
+ *                                in the \p plaintext buffer.
  *
  * \retval #PSA_SUCCESS
  *         Success.
@@ -3129,9 +3126,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 +3172,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()

include/psa/crypto_sizes.h

@@ -228,7 +228,7 @@
  * \param key_type      The type of the MAC key.
  * \param key_bits      The size of the MAC key in bits.
  * \param alg           A MAC algorithm (\c PSA_ALG_XXX value such that
- *                      #PSA_ALG_IS_MAC(alg) is true).
+ *                      #PSA_ALG_IS_MAC(\p alg) is true).
  *
  * \return              The MAC size for the specified algorithm with
  *                      the specified key parameters.
@@ -253,7 +253,7 @@
  *
  * \param alg                 An AEAD algorithm
  *                            (\c PSA_ALG_XXX value such that
- *                            #PSA_ALG_IS_AEAD(alg) is true).
+ *                            #PSA_ALG_IS_AEAD(\p alg) is true).
  * \param plaintext_length    Size of the plaintext in bytes.
  *
  * \return                    The AEAD ciphertext size for the specified
@@ -277,7 +277,7 @@
  *
  * \param alg                 An AEAD algorithm
  *                            (\c PSA_ALG_XXX value such that
- *                            #PSA_ALG_IS_AEAD(alg) is true).
+ *                            #PSA_ALG_IS_AEAD(\p alg) is true).
  *
  * \return                    The maximum trailing ciphertext size for the
  *                            specified algorithm.
@@ -286,7 +286,7 @@
  *                            correct size for an AEAD algorithm that it
  *                            recognizes, but does not support.
  */
-#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg, plaintext_length)      \
+#define PSA_AEAD_FINISH_OUTPUT_SIZE(alg)      \
     ((size_t)0)
 
 /** The maximum size of the output of psa_aead_decrypt(), in bytes.
@@ -298,7 +298,7 @@
  *
  * \param alg                 An AEAD algorithm
  *                            (\c PSA_ALG_XXX value such that
- *                            #PSA_ALG_IS_AEAD(alg) is true).
+ *                            #PSA_ALG_IS_AEAD(\p alg) is true).
  * \param ciphertext_length   Size of the plaintext in bytes.
  *
  * \return                    The AEAD ciphertext size for the specified

include/psa/crypto_values.h

@@ -187,7 +187,7 @@
  * the global integrity of the keystore. Depending on the global
  * integrity guarantees offered by the implementation, access to other
  * data may or may not fail even if the data is still readable but
- * its integrity canont be guaranteed.
+ * its integrity cannot be guaranteed.
  *
  * Implementations should only use this error code to report a
  * permanent storage corruption. However application writers should
@@ -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)
@@ -898,7 +885,12 @@
  */
 #define PSA_ALG_CBC_PKCS7                       ((psa_algorithm_t)0x04600101)
 
+/** The CCM authenticated encryption algorithm.
+ */
 #define PSA_ALG_CCM                             ((psa_algorithm_t)0x06001001)
+
+/** The GCM authenticated encryption algorithm.
+ */
 #define PSA_ALG_GCM                             ((psa_algorithm_t)0x06001002)
 
 /* In the encoding of a AEAD algorithm, the bits corresponding to
@@ -1020,6 +1012,20 @@
     (PSA_ALG_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
 #define PSA_ALG_DETERMINISTIC_DSA_BASE          ((psa_algorithm_t)0x10050000)
 #define PSA_ALG_DSA_DETERMINISTIC_FLAG          ((psa_algorithm_t)0x00010000)
+/** Deterministic DSA signature with hashing.
+ *
+ * This is the deterministic variant defined by RFC 6979 of
+ * the signature scheme defined by FIPS 186-4.
+ *
+ * \param hash_alg      A hash algorithm (\c PSA_ALG_XXX value such that
+ *                      #PSA_ALG_IS_HASH(\p hash_alg) is true).
+ *                      This includes #PSA_ALG_ANY_HASH
+ *                      when specifying the algorithm in a usage policy.
+ *
+ * \return              The corresponding DSA signature algorithm.
+ * \return              Unspecified if \p alg is not a supported
+ *                      hash algorithm.
+ */
 #define PSA_ALG_DETERMINISTIC_DSA(hash_alg)                             \
     (PSA_ALG_DETERMINISTIC_DSA_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
 #define PSA_ALG_IS_DSA(alg)                                             \
@@ -1313,8 +1319,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)))
@@ -1404,24 +1425,6 @@
      PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH :   \
      (alg) == PSA_ALG_ANY_HASH)
 
-/** Whether the specified algorithm encoding is a wildcard.
- *
- * Wildcard values may only be used to set the usage algorithm field in
- * a policy, not to perform an operation.
- *
- * \param alg An algorithm identifier (value of type #psa_algorithm_t).
- *
- * \return 1 if \c alg is a wildcard algorithm encoding.
- * \return 0 if \c alg is a non-wildcard algorithm encoding (suitable for
- *         an operation).
- * \return This macro may return either 0 or 1 if \c alg is not a supported
- *         algorithm identifier.
- */
-#define PSA_ALG_IS_WILDCARD(alg)                        \
-    (PSA_ALG_IS_HASH_AND_SIGN(alg) ?                    \
-     PSA_ALG_SIGN_GET_HASH(alg) == PSA_ALG_ANY_HASH :   \
-     (alg) == PSA_ALG_ANY_HASH)
-
 /**@}*/
 
 /** \defgroup key_lifetimes Key lifetimes