mirror/mbedtls
1
0
Fork 0
mirror of https://github.com/Mbed-TLS/mbedtls.git synced 2025-02-25 18:39:54 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

PSA PAKE: improve and fix documentation

Browse Source 
Signed-off-by: Janos Follath <janos.follath@arm.com>
This commit is contained in:
Janos Follath 2021-05-20 16:21:01 +01:00
parent 7b8910322c
commit 9a04aeaff5
4 changed files with 29 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
include/psa/crypto.h
View File

@ -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 * -# Initialize the operation object with one of the methods described in the
* documentation for #psa_pake_operation_t, e.g. * documentation for #psa_pake_operation_t, e.g.
* #PSA_PAKE_OPERATION_INIT. * #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 * -# 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 * setup. The exact sequence of \c psa_pake_set_xxx() functions that needs
* to be called depends on the algorithm in use. * 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); psa_pake_cipher_suite_t cipher_suite);
/** Set the password for a password-authenticated key exchange from key ID. /** 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 * \param[in,out] operation The operation object to set the password for. It
* must have been set up by psa_pake_setup() and * 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 * memory-hard function). It must remain valid
* until the operation terminates. It must be of * until the operation terminates. It must be of
* type #PSA_KEY_TYPE_PASSWORD or * type #PSA_KEY_TYPE_PASSWORD or
* #PSA_KEY_TYPE_DERIVE. It has to allow the usage * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow
* #PSA_KEY_USAGE_DERIVE. * the usage #PSA_KEY_USAGE_DERIVE.
* *
* \retval #PSA_SUCCESS * \retval #PSA_SUCCESS
* 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. /** 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 * session. Such algorithms must call this function (psa_pake_set_user()) to
* set the identifier for the PAKE context. * 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. /** 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 * session. Such algorithms must call psa_pake_set_user() to set the
* identifier for the PAKE context. * 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_status_t psa_pake_set_side(psa_pake_operation_t *operation,
psa_pake_side_t side); 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 * 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. * 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(). * state and must be aborted by calling psa_pake_abort().
* *
* \param[in,out] operation Active PAKE operation. * \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[out] output Buffer where the output is to be written.
* \param output_size Size of the \p output buffer in bytes. This must * \param output_size Size of the \p output buffer in bytes. This must
* be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c * 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. * results in this error code.
*/ */
psa_status_t psa_pake_output(psa_pake_operation_t *operation, psa_status_t psa_pake_output(psa_pake_operation_t *operation,
psa_pake_step_t type, psa_pake_step_t step,
uint8_t *output, uint8_t *output,
size_t output_size, size_t output_size,
size_t *output_length); 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 * 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. * 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(). * state and must be aborted by calling psa_pake_abort().
* *
* \param[in,out] operation Active PAKE operation. * \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 Buffer containing the input.
* \param[out] input_length Size of the \p input buffer in bytes. * \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. * results in this error code.
*/ */
psa_status_t psa_pake_input(psa_pake_operation_t *operation, psa_status_t psa_pake_input(psa_pake_operation_t *operation,
psa_pake_step_t type, psa_pake_step_t step,
uint8_t *input, uint8_t *input,
size_t input_length); size_t input_length);

3
include/psa/crypto_sizes.h
View File

@ -1143,7 +1143,8 @@
* *
* \param alg A PAKE algorithm (PSA_ALG_XXX value such that * \param alg A PAKE algorithm (PSA_ALG_XXX value such that
* #PSA_ALG_IS_PAKE(\p alg) is true). * #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 * \param output_step A value of type ::psa_pake_step_t that is valid for the
* algorithm \p alg. * algorithm \p alg.
* \return A sufficient output buffer size for the specified * \return A sufficient output buffer size for the specified

6
include/psa/crypto_types.h
View File

@ -387,7 +387,7 @@ typedef uint16_t psa_key_derivation_step_t;
/** \brief Encoding of the side of PAKE /** \brief Encoding of the side of PAKE
* *
* Encodes which side of the algorithm is being executed. For more information * 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; 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. * Vendors who define additional types must use an encoding in this range.
* *
* For more information see the documentation of individual * 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; typedef uint8_t psa_pake_primitive_type_t;
/** \brief Encoding of the family of the primitive associated with the PAKE. /** \brief Encoding of the family of the primitive associated with the PAKE.
* *
* For more information see the documentation of individual * 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; typedef uint8_t psa_pake_family_t;

12
include/psa/crypto_values.h
View File

@ -1975,7 +1975,7 @@
* cipher suite the field or curve must be fully specified by calling * 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 * psa_pake_cs_set_family() and psa_pake_cs_set_bits() as well. For more
* information refer to the documentation of the individual * 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 * J-PAKE can be used with any secure cryptographic hash function. The choice
* of hash must be supplied to the cipher suite by calling * 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 * 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 * 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. * Another consequence is that psa_pake_set_side() is optional and is ignored.
* *
* The key exchange flow for JPAKE is as follows: * The key exchange flow for JPAKE is as follows:
@ -2038,7 +2038,7 @@
* psa_pake_get_implicit_key() * psa_pake_get_implicit_key()
* *
* For more information consult the documentation of the individual * 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. * 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 * Although balanced PAKE algorithms are symmetric, some of them needs an
* ordering of peers for the transcript calculations. If the algorithm does not * 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. * accepted.
*/ */
#define PSA_PAKE_SIDE_FIRST ((psa_pake_side_t)0x01) #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) #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 * \param pake_type The type of the primitive
* (value of type ::psa_pake_primitive_type_t). * (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 * on \p type, for more information consult the
* documentation of individual ::psa_pake_primitive_type_t * documentation of individual ::psa_pake_primitive_type_t
* constants). * 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 * (Value of type \c size_t. The interpretation
* of this parameter depends on \p family, for more * of this parameter depends on \p family, for more
* information consult the documentation of individual * information consult the documentation of individual