From 4c6fdbbe8d2ef0e7ee8f509d4ad1171602ca972f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 8 Feb 2019 11:22:39 +0100 Subject: [PATCH 1/8] Fix typos in doxygen formatting commands --- include/psa/crypto.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 5f4896cbd..3ed5f0f51 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -1962,7 +1962,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 +2018,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. From 6bce7f7ebbf7e8a979c61815a9373fe731bc974b Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 8 Feb 2019 11:24:03 +0100 Subject: [PATCH 2/8] Fix copypasta in multipart AEAD macro --- include/psa/crypto_sizes.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index d4182f525..8e7fa7ae4 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -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. From 12b58abad6cc1c5ae7cf5a04f1b4e56d4a671eab Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 8 Feb 2019 11:24:24 +0100 Subject: [PATCH 3/8] Remove duplicate definition of PSA_ALG_IS_WILDCARD This was due to a bad merge. --- include/psa/crypto_values.h | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index e6909af67..76c5f38a1 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -1404,24 +1404,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 From 47e79fb5ab354b9f2214e85cae86e2c865cd1aff Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 8 Feb 2019 11:24:59 +0100 Subject: [PATCH 4/8] 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))) From 63f79300038fb89d54942e692ec8679bb06857ea Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 15 Feb 2019 13:01:17 +0100 Subject: [PATCH 5/8] Doxygen: fix missing markup indicator that was causing broken links --- include/psa/crypto.h | 6 +++--- include/psa/crypto_sizes.h | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index b2f3eb28f..6f74ba758 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -1139,7 +1139,7 @@ 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. @@ -1179,7 +1179,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 +1289,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. diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index 8e7fa7ae4..e1ac63051 100644 --- a/include/psa/crypto_sizes.h +++ b/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. @@ -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 From d338b9117490628efed5b092f1aa2c2232ae1375 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 15 Feb 2019 13:01:41 +0100 Subject: [PATCH 6/8] Fix some copypasta in one-shot hash and MAC function descriptions --- include/psa/crypto.h | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 6f74ba758..dd4599687 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -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. @@ -1145,9 +1144,7 @@ psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, * \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. From 9153ec0d041cfc9e213d460d6ec2dd5758f045e5 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 15 Feb 2019 13:02:02 +0100 Subject: [PATCH 7/8] Add documentation for some macros Document some macros which have cross-references. Without documentation for those macros, the cross-references were broken links. --- include/psa/crypto_values.h | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 29a64c27a..a47695c2e 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -885,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 @@ -1007,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) \ From bf7a98b791fe21f1ee5d553f4dfe1d1cbfe3ef8a Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 22 Feb 2019 16:42:11 +0100 Subject: [PATCH 8/8] Fix typos found in PSA Crypto API 1.0 beta2 before publication --- include/psa/crypto.h | 2 +- include/psa/crypto_values.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index dd4599687..e7d0ecda7 100644 --- a/include/psa/crypto.h +++ b/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. diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index a47695c2e..e0cc5446f 100644 --- a/include/psa/crypto_values.h +++ b/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