diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 5f4896cbd..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. @@ -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() diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index d4182f525..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. @@ -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 diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index e6909af67..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 @@ -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