cuberite/polarssl
1
0
Fork 0
mirror of https://github.com/cuberite/polarssl.git synced 2025-11-03 20:22:59 -05:00
Code Issues Packages Projects Releases Wiki Activity

Improve or expand several descriptions.

Browse Source 
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>
This commit is contained in:
Manuel Pégourié-Gonnard 2021-04-30 11:37:57 +02:00
parent dc1b4e42e9
commit ffc86ce8d6
2 changed files with 86 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
include/psa/crypto.h
View File

@ -3293,10 +3293,13 @@ psa_status_t psa_key_derivation_input_bytes(
/** Provide a numeric input for key derivation or key agreement. /** Provide a numeric input for key derivation or key agreement.
* *
* Which inputs are required and in what order depends on the algorithm. * 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 * Refer to the documentation of each key derivation or key agreement
* algorithm for information. * 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 * If this function returns an error status, the operation enters an error
* state and must be aborted by calling psa_key_derivation_abort(). * state and must be aborted by calling psa_key_derivation_abort().
@ -3306,8 +3309,7 @@ psa_status_t psa_key_derivation_input_bytes(
* psa_key_derivation_setup() and must not * psa_key_derivation_setup() and must not
* have produced any output yet. * have produced any output yet.
* \param step Which step the input data is for. * \param step Which step the input data is for.
* \param[in] data Input data to use. * \param[in] value The value of the numeric input.
* \param data_length Size of the \p data buffer in bytes.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* Success. * Success.
@ -3646,15 +3648,25 @@ psa_status_t psa_key_derivation_output_key(
/** Compare output data from a key derivation operation to an expected value. /** Compare output data from a key derivation operation to an expected value.
* *
* This function calculates output bytes from a key derivation algorithm and * 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 * If you view the key derivation's output as a stream of bytes, this
* function destructively reads the requested number of bytes from the * function destructively reads the requested number of bytes from the
* stream before comparing them. * stream before comparing them.
* The operation's capacity decreases by the number of bytes read. * 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 * If this function returns an error status other than
* #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
* state and must be aborted by calling psa_key_derivation_abort(). * 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,out] operation The key derivation operation object to read from.
* \param[in] expected_output Buffer where the output will be written. * \param[in] expected_output Buffer where the output will be written.
@ -3686,32 +3698,44 @@ psa_status_t psa_key_derivation_output_key(
*/ */
psa_status_t psa_key_derivation_verify_output_bytes( psa_status_t psa_key_derivation_verify_output_bytes(
psa_key_derivation_operation_t *operation, psa_key_derivation_operation_t *operation,
const uint8_t *output, const uint8_t *expected_output,
size_t output_length); 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 * This function calculates output bytes from a key derivation algorithm and
* compares those bytes to an expected value, provided as key of type * 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 * If you view the key derivation's output as a stream of bytes, this
* function destructively reads the number of bytes corresponding the the * function destructively reads the number of bytes corresponding the the
* length of the expected value from the stream before comparing them. * length of the expected value from the stream before comparing them.
* The operation's capacity decreases by the number of bytes read. * 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 * If this function returns an error status other than
* #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error * #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE,
* state and must be aborted by calling psa_key_derivation_abort(). * 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,out] operation The key derivation operation object to read from.
* \param[in] expected A key of type #PSA_KEY_TYPE_RAW_DATA containing * \param[in] expected A key of type #PSA_KEY_TYPE_RAW_DATA containing
* the expected output. Its policy must include the * the expected output. Its policy must include the
* #PSA_KEY_USAGE_PASSWORD_HASH_VERIFIER flag. * #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_SUCCESS
* \retval #PSA_ERROR_INVALID_SIGNATURE * \retval #PSA_ERROR_INVALID_SIGNATURE
* The output was read successfully, but if differs from the expected * The output was read successfully, but if differs from the expected
* output. * 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 * \retval #PSA_ERROR_NOT_PERMITTED
* The key passed as the expected value does not allow this usage. * The key passed as the expected value does not allow this usage.
* \retval #PSA_ERROR_INSUFFICIENT_DATA * \retval #PSA_ERROR_INSUFFICIENT_DATA

79
include/psa/crypto_values.h
View File

@ -408,6 +408,12 @@
#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100) #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100)
/** A secret for key derivation. /** 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 * The key policy determines which key derivation algorithm the key
* can be used for. * can be used for.
@ -416,15 +422,31 @@
/** A low-entropy secret for password hashing or key derivation. /** A low-entropy secret for password hashing or key derivation.
* *
* The key policy determines which key derivation algorithm the key * This key type is suitable for passwords and passphrases which are typically
* can be used for. * 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) #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 * 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) #define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1400)
@ -804,9 +826,9 @@
* algorithm. * algorithm.
* *
* A key stretching / password hashing algorithm is a key derivation algorithm * A key stretching / password hashing algorithm is a key derivation algorithm
* that is suitable for use with low-entropy secret such as passwords. * that is suitable for use with a low-entropy secret such as a password.
* Equivalently, it's a key derivation algorithm that accepts an input of type * Equivalently, it's a key derivation algorithm that uses a
* #PSA_KEY_DERIVATION_INPUT_PASSWORD. * #PSA_KEY_DERIVATION_INPUT_PASSWORD input step.
* *
* \param alg An algorithm identifier (value of type #psa_algorithm_t). * \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_KEY_DERIVATION_STRETCHING_FLAG ((psa_algorithm_t)0x00008000)
#define PSA_ALG_PBKDF2_HMAC_BASE ((psa_algorithm_t)0x08008100) #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). * 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 * This macro specifies the PBKDF2 algorithm constructed using a PRF based on
* is based on HMAC with a given hash. * HMAC with the specified hash.
* * For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA256)` specifies PBKDF2
* For example, `PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA256)` represents PBKDF2 * using the PRF HMAC-SHA-256.
* using HMAC-SHA-256 as the internal PRF.
* *
* This key derivation algorithm uses the following inputs: * This key derivation algorithm uses the following inputs:
* - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed * - #PSA_KEY_DERIVATION_INPUT_PASSWORD is the password to be hashed.
* - #PSA_KEY_DERIVATION_INPUT_SALT is (part of) the salt (see note below) * This input step must be used exactly once.
* - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count * - #PSA_KEY_DERIVATION_INPUT_SALT is the salt.
* * This input step must be used one or more times; if used several times, the
* Note: if multiple salt inputs are passed, they will be concatenated by the * inputs will be concatenated. This can be used to build the final salt
* implementation in order to produce the salt that will be passed to the * from multiple sources, both public and secret (also known as pepper).
* algorithm. This allows building the salt from multiple inputs, both public * - #PSA_KEY_DERIVATION_INPUT_COST is the iteration count.
* and secret (also known as pepper). * This input step must be used exactly once.
* *
* \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that * \param hash_alg A hash algorithm (\c PSA_ALG_XXX value such that
* #PSA_ALG_IS_HASH(\p hash_alg) is true). * #PSA_ALG_IS_HASH(\p hash_alg) is true).
@ -2213,19 +2234,21 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key )
* The secret can also be a direct input (passed to * The secret can also be a direct input (passed to
* key_derivation_input_bytes()). In this case, the derivation operation * key_derivation_input_bytes()). In this case, the derivation operation
* may not be used to derive keys: the operation will only allow * 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) #define PSA_KEY_DERIVATION_INPUT_SECRET ((psa_key_derivation_step_t)0x0101)
/** A low-entropy secret input for password hashing / key stretching. /** 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 * This is usually a key of type #PSA_KEY_TYPE_PASSWORD (passed to
* (passed to psa_key_derivation_input_key()) * psa_key_derivation_input_key()) or a direct input (passed to
* or the shared secret resulting from a key agreement * psa_key_derivation_input_bytes()) that is a password or passphrase. It can
* (obtained via psa_key_derivation_key_agreement()). * 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 * If the secret is a direct input, the derivation operation
* key_derivation_input_bytes()). In this case, the derivation operation
* may not be used to derive keys: the operation will only allow * 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(), not psa_key_derivation_output_key().
*/ */