From 9a04aeaff5e01abde65a972030e23ce9cf700c99 Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Thu, 20 May 2021 16:21:01 +0100 Subject: [PATCH] PSA PAKE: improve and fix documentation Signed-off-by: Janos Follath --- include/psa/crypto.h | 30 ++++++++++++++++++------------ include/psa/crypto_sizes.h | 3 ++- include/psa/crypto_types.h | 6 +++--- include/psa/crypto_values.h | 12 ++++++------ 4 files changed, 29 insertions(+), 22 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 6706ef8ea5..fa4102278e 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -4092,7 +4092,7 @@ psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, /**@}*/ -/** \defgroup Password-authenticated key agreement +/** \defgroup pake Password-authenticated key exchange (PAKE) * @{ */ @@ -4255,7 +4255,7 @@ static psa_pake_operation_t psa_pake_operation_init(void); * -# Initialize the operation object with one of the methods described in the * documentation for #psa_pake_operation_t, e.g. * #PSA_PAKE_OPERATION_INIT. - * -# Call psa_pake_setup() to specify cipher suite. + * -# Call psa_pake_setup() to specify the cipher suite. * -# Call \c psa_pake_set_xxx() functions on the operation to complete the * setup. The exact sequence of \c psa_pake_set_xxx() functions that needs * to be called depends on the algorithm in use. @@ -4323,6 +4323,11 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation, psa_pake_cipher_suite_t cipher_suite); /** Set the password for a password-authenticated key exchange from key ID. + * + * Call this function when the password, or a value derived from the password, + * is already present in the key store. To calculate the password-derived value + * from a password input, use the key derivation interface and + * psa_pake_set_password_stretch() instead. * * \param[in,out] operation The operation object to set the password for. It * must have been set up by psa_pake_setup() and @@ -4332,8 +4337,8 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation, * memory-hard function). It must remain valid * until the operation terminates. It must be of * type #PSA_KEY_TYPE_PASSWORD or - * #PSA_KEY_TYPE_DERIVE. It has to allow the usage - * #PSA_KEY_USAGE_DERIVE. + * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow + * the usage #PSA_KEY_USAGE_DERIVE. * * \retval #PSA_SUCCESS * Success. @@ -4409,7 +4414,7 @@ psa_status_t psa_pake_set_password_mhf(psa_pake_operation_t *operation, /** Set the user ID for a password-authenticated key exchange. * - * Some PAKE algorithms assiciate only a single user identifier with the + * Some PAKE algorithms associate only a single user identifier with the * session. Such algorithms must call this function (psa_pake_set_user()) to * set the identifier for the PAKE context. * @@ -4444,7 +4449,7 @@ psa_status_t psa_pake_set_user(psa_pake_operation_t *operation, /** Set the peer ID for a password-authenticated key exchange. * - * Some PAKE algorithms assiciate only a single user identifier with the + * Some PAKE algorithms associate only a single user identifier with the * session. Such algorithms must call psa_pake_set_user() to set the * identifier for the PAKE context. * @@ -4514,7 +4519,7 @@ psa_status_t psa_pake_set_peer(psa_pake_operation_t *operation, psa_status_t psa_pake_set_side(psa_pake_operation_t *operation, psa_pake_side_t side); -/** Get additional key share from a password-authenticated key exchange. +/** Get output for a step of a password-authenticated key exchange. * * Depending on the algorithm being executed, you might need to call this * function several times or you might not need to call this at all. @@ -4529,7 +4534,8 @@ psa_status_t psa_pake_set_side(psa_pake_operation_t *operation, * state and must be aborted by calling psa_pake_abort(). * * \param[in,out] operation Active PAKE operation. - * \param type The type of the data that is requested. + * \param step The step of the algorithm for which the output is + * requested. * \param[out] output Buffer where the output is to be written. * \param output_size Size of the \p output buffer in bytes. This must * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c @@ -4556,12 +4562,12 @@ psa_status_t psa_pake_set_side(psa_pake_operation_t *operation, * results in this error code. */ psa_status_t psa_pake_output(psa_pake_operation_t *operation, - psa_pake_step_t type, + psa_pake_step_t step, uint8_t *output, size_t output_size, size_t *output_length); -/** Provide additional peer key share for a password-authenticated key exchange. +/** Provide input for a step of a password-authenticated key exchange. * * Depending on the algorithm being executed, you might need to call this * function several times or you might not need to call this at all. @@ -4576,7 +4582,7 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation, * state and must be aborted by calling psa_pake_abort(). * * \param[in,out] operation Active PAKE operation. - * \param type The type of the data provided. + * \param step The step for which the input is provided. * \param[out] input Buffer containing the input. * \param[out] input_length Size of the \p input buffer in bytes. * @@ -4596,7 +4602,7 @@ psa_status_t psa_pake_output(psa_pake_operation_t *operation, * results in this error code. */ psa_status_t psa_pake_input(psa_pake_operation_t *operation, - psa_pake_step_t type, + psa_pake_step_t step, uint8_t *input, size_t input_length); diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index d8fc9979bd..a603c9d298 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -1143,7 +1143,8 @@ * * \param alg A PAKE algorithm (PSA_ALG_XXX value such that * #PSA_ALG_IS_PAKE(\p alg) is true). - * \param primitive A primitive that is compatible with algorithm \p alg. + * \param primitive A primitive of type ::psa_pake_primitive_t that is + * compatible with algorithm \p alg. * \param output_step A value of type ::psa_pake_step_t that is valid for the * algorithm \p alg. * \return A sufficient output buffer size for the specified diff --git a/include/psa/crypto_types.h b/include/psa/crypto_types.h index 5418bd76ea..5a66a8709e 100644 --- a/include/psa/crypto_types.h +++ b/include/psa/crypto_types.h @@ -387,7 +387,7 @@ typedef uint16_t psa_key_derivation_step_t; /** \brief Encoding of the side of PAKE * * Encodes which side of the algorithm is being executed. For more information - * see the documentation of individual PSA_PAKE_SIDE_XXX constants. + * see the documentation of individual \c PSA_PAKE_SIDE_XXX constants. */ typedef uint8_t psa_pake_side_t; @@ -405,14 +405,14 @@ typedef uint8_t psa_pake_step_t; * Vendors who define additional types must use an encoding in this range. * * For more information see the documentation of individual - * PSA_PAKE_PRIMITIVE_TYPE_XXX constants. + * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants. */ typedef uint8_t psa_pake_primitive_type_t; /** \brief Encoding of the family of the primitive associated with the PAKE. * * For more information see the documentation of individual - * PSA_PAKE_PRIMITIVE_TYPE_XXX constants. + * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants. */ typedef uint8_t psa_pake_family_t; diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index d1924db67b..c8a074caef 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -1975,7 +1975,7 @@ * cipher suite the field or curve must be fully specified by calling * psa_pake_cs_set_family() and psa_pake_cs_set_bits() as well. For more * information refer to the documentation of the individual - * `PSA_PAKE_PRIMITIVE_TYPE_XXX` constants.) + * \c PSA_PAKE_PRIMITIVE_TYPE_XXX constants.) * * J-PAKE can be used with any secure cryptographic hash function. The choice * of hash must be supplied to the cipher suite by calling @@ -1987,7 +1987,7 @@ * * J-PAKE doesn't differentiate between sides and has a distinct identifier * associated with each entity. This means that both psa_pake_set_user() and - * psa_pake_set_peer() needs to be called before commencing the operation. + * psa_pake_set_peer() need to be called before commencing the operation. * Another consequence is that psa_pake_set_side() is optional and is ignored. * * The key exchange flow for JPAKE is as follows: @@ -2038,7 +2038,7 @@ * psa_pake_get_implicit_key() * * For more information consult the documentation of the individual - * PSA_PAKE_STEP_XXX constants. + * \c PSA_PAKE_STEP_XXX constants. * * J-PAKE is standardised for example in RFC 8236. */ @@ -2480,7 +2480,7 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) * * Although balanced PAKE algorithms are symmetric, some of them needs an * ordering of peers for the transcript calculations. If the algorithm does not - * need this, either #PSA_PAKE_SIDE_FIRST or #PSA_PAKE_SIDE_SECOND are + * need this, both #PSA_PAKE_SIDE_FIRST and #PSA_PAKE_SIDE_SECOND are * accepted. */ #define PSA_PAKE_SIDE_FIRST ((psa_pake_side_t)0x01) @@ -2546,7 +2546,7 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) */ #define PSA_PAKE_PRIMITIVE_TYPE_DH ((psa_pake_primitive_type_t)0x02) -/** Construct a PAKE primitive from type, family and bitsize. +/** Construct a PAKE primitive from type, family and bit-size. * * \param pake_type The type of the primitive * (value of type ::psa_pake_primitive_type_t). @@ -2555,7 +2555,7 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) * on \p type, for more information consult the * documentation of individual ::psa_pake_primitive_type_t * constants). - * \param pake_bits The bitsize of the primitive + * \param pake_bits The bit-size of the primitive * (Value of type \c size_t. The interpretation * of this parameter depends on \p family, for more * information consult the documentation of individual