Improve or expand several descriptions.
No change of behaviour, encoding or naming intended in this commit: just
describe the same behaviour, but in a way that's hopefully clearer and
more complete.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index deb5e0c..f9e051e 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -3293,10 +3293,13 @@
/** Provide a numeric input for key derivation or key agreement.
*
* Which inputs are required and in what order depends on the algorithm.
+ * However, when an algorithm requires a particular order, numeric inputs
+ * usually come first as they tend to be configuration parameters.
* Refer to the documentation of each key derivation or key agreement
* algorithm for information.
*
- * This function is used for inputs which are small non-negative integers.
+ * This function is used for inputs which are fixed-size non-negative
+ * integers.
*
* If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_key_derivation_abort().
@@ -3306,8 +3309,7 @@
* psa_key_derivation_setup() and must not
* have produced any output yet.
* \param step Which step the input data is for.
- * \param[in] data Input data to use.
- * \param data_length Size of the \p data buffer in bytes.
+ * \param[in] value The value of the numeric input.
*
* \retval #PSA_SUCCESS
* Success.
@@ -3646,15 +3648,25 @@
/** Compare output data from a key derivation operation to an expected value.
*
* This function calculates output bytes from a key derivation algorithm and
- * compares those bytes to an expected value.
+ * compares those bytes to an expected value in constant time.
* If you view the key derivation's output as a stream of bytes, this
* function destructively reads the requested number of bytes from the
* stream before comparing them.
* The operation's capacity decreases by the number of bytes read.
*
+ * This is functionally equivalent to the following code:
+ * \code
+ * psa_key_derivation_output_bytes(operation, tmp, output_length);
+ * if (memcmp(output, tmp, output_length) != 0)
+ * return PSA_ERROR_INVALID_SIGNATURE;
+ * \endcode
+ * except (1) it works even if the key's policy does not allow outputting the
+ * bytes, and (2) the comparison will be done in constant time.
+ *
* If this function returns an error status other than
- * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error
- * state and must be aborted by calling psa_key_derivation_abort().
+ * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
+ * the operation enters an error state and must be aborted by calling
+ * psa_key_derivation_abort().
*
* \param[in,out] operation The key derivation operation object to read from.
* \param[in] expected_output Buffer where the output will be written.
@@ -3686,32 +3698,44 @@
*/
psa_status_t psa_key_derivation_verify_output_bytes(
psa_key_derivation_operation_t *operation,
- const uint8_t *output,
+ const uint8_t *expected_output,
size_t output_length);
-/** Compare output data from a key derivation operation to an expected value.
+/** Compare output data from a key derivation operation to an expected value
+ * stored in a key object.
*
* This function calculates output bytes from a key derivation algorithm and
* compares those bytes to an expected value, provided as key of type
- * #PSA_KEY_TYPE_RAW_DATA.
+ * #PSA_KEY_TYPE_RAW_DATA, in constant time.
* If you view the key derivation's output as a stream of bytes, this
* function destructively reads the number of bytes corresponding the the
* length of the expected value from the stream before comparing them.
* The operation's capacity decreases by the number of bytes read.
*
+ * This is functionally equivalent to exporting the key and calling
+ * psa_key_derivation_verify_output_bytes() on the result, except that it
+ * works even if the key cannot be exported.
+ *
* If this function returns an error status other than
- * #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error
- * state and must be aborted by calling psa_key_derivation_abort().
+ * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
+ * the operation enters an error state and must be aborted by calling
+ * psa_key_derivation_abort().
*
* \param[in,out] operation The key derivation operation object to read from.
* \param[in] expected A key of type #PSA_KEY_TYPE_RAW_DATA containing
* the expected output. Its policy must include the
* #PSA_KEY_USAGE_PASSWORD_HASH_VERIFIER flag.
+ * The value of this key was likely computed by a
+ * previous call to psa_key_derivation_output_key().
*
* \retval #PSA_SUCCESS
* \retval #PSA_ERROR_INVALID_SIGNATURE
* The output was read successfully, but if differs from the expected
* output.
+ * \retval #PSA_ERROR_INVALID_HANDLE
+ * The key passed as the expected value does not exist.
+ * \retval #PSA_ERROR_INVALID_ARGUMENT
+ * The key passed as the expected value has an invalid type.
* \retval #PSA_ERROR_NOT_PERMITTED
* The key passed as the expected value does not allow this usage.
* \retval #PSA_ERROR_INSUFFICIENT_DATA
diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h
index 8036a17..a3256f6 100644
--- a/include/psa/crypto_values.h
+++ b/include/psa/crypto_values.h
@@ -409,6 +409,12 @@
/** A secret for key derivation.
*
+ * This key type is for high-entropy secrets only. For low-entropy secrets,
+ * #PSA_KEY_TYPE_PASSWORD should be used instead.
+ *
+ * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_SECRET or
+ * #PSA_KEY_DERIVATION_INPUT_PASSWORD input of key derivation algorithms.
+ *
* The key policy determines which key derivation algorithm the key
* can be used for.
*/
@@ -416,15 +422,31 @@
/** A low-entropy secret for password hashing or key derivation.
*
- * The key policy determines which key derivation algorithm the key
- * can be used for.
+ * This key type is suitable for passwords and passphrases which are typically
+ * intended to be memorizable by humans, and have a low entropy relative to
+ * their size. It can be used for randomly generated or derived keys with
+ * maximum or near-maximum entropy, but PSA_KEY_TYPE_DERIVE is more suitable
+ * for such keys. It is not suitable for passwords with extremely low entropy,
+ * such as numerical PINs.
+ *
+ * These keys can be used as the #PSA_KEY_DERIVATION_INPUT_PASSWORD input of
+ * key derivation algorithms. Algorithms that accept such an input were
+ * designed to accept low-entropy secret and are known as password hashing or
+ * key stretching algorithms.
+ *
+ * These keys cannot be used as the #PSA_KEY_DERIVATION_INPUT_SECRET input of
+ * key derivation algorithms, as the algorithms that take such an input expect
+ * it to be high-entropy.
+ *
+ * The key policy determines which key derivation algorithm the key can be
+ * used for, among the permissible subset defined above.
*/
#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1300)
-/** A secret value that can be mixed in when doing password hashing.
+/** A secret value that can be used in when computing a password hash.
*
* The key policy determines which key derivation algorithm the key
- * can be used for.
+ * can be used for, among the subset of algorithms that can use pepper.
*/
#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1400)
@@ -804,9 +826,9 @@
* algorithm.
*
* A key stretching / password hashing algorithm is a key derivation algorithm
- * that is suitable for use with low-entropy secret such as passwords.
- * Equivalently, it's a key derivation algorithm that accepts an input of type
- * #PSA_KEY_DERIVATION_INPUT_PASSWORD.
+ * that is suitable for use with a low-entropy secret such as a password.
+ * Equivalently, it's a key derivation algorithm that uses a
+ * #PSA_KEY_DERIVATION_INPUT_PASSWORD input step.
*
* \param alg An algorithm identifier (value of type #psa_algorithm_t).
*
@@ -1707,24 +1729,23 @@
#define PSA_ALG_KEY_DERIVATION_STRETCHING_FLAG ((psa_algorithm_t)0x00008000)
#define PSA_ALG_PBKDF2_HMAC_BASE ((psa_algorithm_t)0x08008100)
-/** Macro to build a PBKDF2-HMAC algorithm.
+/** Macro to build a PBKDF2-HMAC password hashing / key stretching algorithm.
*
* PBKDF2 is defined by PKCS#5, republished as RFC 8018 (section 5.2).
- * It can use on of several PRFs internally; this macro is used when that PRF
- * is based on HMAC with a given hash.
- *
- * For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA256)` represents PBKDF2
- * using HMAC-SHA-256 as the internal PRF.
+ * This macro specifies the PBKDF2 algorithm constructed using a PRF based on
+ * HMAC with the specified hash.
+ * For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA256)` specifies PBKDF2
+ * using the PRF HMAC-SHA-256.
*
* This key derivation algorithm uses the following inputs:
- * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed
- * - #PSA_KEY_DERIVATION_INPUT_SALT is (part of) the salt (see note below)
- * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count
- *
- * Note: if multiple salt inputs are passed, they will be concatenated by the
- * implementation in order to produce the salt that will be passed to the
- * algorithm. This allows building the salt from multiple inputs, both public
- * and secret (also known as pepper).
+ * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed.
+ * This input step must be used exactly once.
+ * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt.
+ * This input step must be used one or more times; if used several times, the
+ * inputs will be concatenated. This can be used to build the final salt
+ * from multiple sources, both public and secret (also known as pepper).
+ * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count.
+ * This input step must be used exactly once.
*
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true).
@@ -2213,19 +2234,21 @@
* The secret can also be a direct input (passed to
* key_derivation_input_bytes()). In this case, the derivation operation
* may not be used to derive keys: the operation will only allow
- * psa_key_derivation_output_bytes(), not psa_key_derivation_output_key().
+ * psa_key_derivation_output_bytes() or
+ * psa_key_derivation_verify_output_xxx() but not
+ * psa_key_derivation_output_key().
*/
#define PSA_KEY_DERIVATION_INPUT_SECRET ((psa_key_derivation_step_t)0x0101)
/** A low-entropy secret input for password hashing / key stretching.
*
- * This should be a key of type #PSA_KEY_TYPE_PASSWORD or #PSA_KEY_TYPE_DERIVE
- * (passed to psa_key_derivation_input_key())
- * or the shared secret resulting from a key agreement
- * (obtained via psa_key_derivation_key_agreement()).
+ * This is usually a key of type #PSA_KEY_TYPE_PASSWORD (passed to
+ * psa_key_derivation_input_key()) or a direct input (passed to
+ * psa_key_derivation_input_bytes()) that is a password or passphrase. It can
+ * also be high-entropy secret such as a key of type #PSA_KEY_TYPE_DERIVE or
+ * the shared secret resulting from a key agreement.
*
- * The secret can also be a direct input (passed to
- * key_derivation_input_bytes()). In this case, the derivation operation
+ * If the secret is a direct input, the derivation operation
* may not be used to derive keys: the operation will only allow
* psa_key_derivation_output_bytes(), not psa_key_derivation_output_key().
*/