From 1459aa5656935a07737ab1769403ff7f4eae8a3a Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Tue, 11 May 2021 08:24:56 +0100 Subject: [PATCH] PSA PAKE: improve documentation Minor documentation improvement and fixes. Signed-off-by: Janos Follath --- include/psa/crypto.h | 36 +++++++++++++++++++++++------------- include/psa/crypto_sizes.h | 5 +++-- include/psa/crypto_values.h | 24 ++++++++++++++---------- 3 files changed, 40 insertions(+), 25 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 17316795d..df8d4d4e9 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -4240,8 +4240,8 @@ static uint8_t psa_pake_cs_get_family( * If this is 0, the primitive family in * \p cipher_suite becomes unspecified. The * interpretation of this parameter depends on - * the primitive type, for more information consult the - * documentation of individual + * the primitive type. For more information + * consult the documentation of individual * ::psa_pake_primitive_type_t constants). */ static void psa_pake_cs_set_family( @@ -4249,7 +4249,7 @@ static void psa_pake_cs_set_family( uint8_t family ); -/** Retrieve the primitive bits from a PAKE cipher suite. +/** Retrieve the size associated with the primitive from a PAKE cipher suite. * * This function may be declared as `static` (i.e. without external * linkage). This function may be provided as a function-like macro, @@ -4292,7 +4292,9 @@ static void psa_pake_cs_set_bits( * * \param[in] cipher_suite The cipher suite structure to query. * - * \return The hash algorithm stored in the cipher suite structure. + * \return The hash algorithm stored in the cipher suite structure. The return + * value is 0 if the PAKE is not parametrised by a hash algorithm or if + * the hash algorithm is not set. */ static psa_algorithm_t psa_pake_cs_get_hash( const psa_pake_cipher_suite_t* cipher_suite @@ -4378,8 +4380,8 @@ 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 the algorithm, the key, cipher suite, - * identities and additional session information. + * -# Call psa_pake_setup() to specify the algorithm, the password, cipher + * suite, identities and additional session information. * * A typical sequence of calls to perform a password-authenticated key * exchange: @@ -4388,13 +4390,17 @@ static psa_pake_operation_t psa_pake_operation_init(void); * -# Call psa_pake_input(operation, #PSA_PAKE_DATA_KEY_SHARE, ...) to provide * the key share that was received from the peer. * -# Call psa_pake_get_implicit_key() for accessing the shared secret. + * -# Make a sequence of function calls to execute the password-authenticated + * key exchange as described below. + * -# Terminate the operation by a call to psa_pake_get_implicit_key() or + * psa_pake_abort(). * * The exact sequence of calls to perform a password-authenticated key exchange * depends on the algorithm in use: - * -# Some algorithms exchange more data than just a single key share. When using - * such a algorithm, call psa_pake_output() and psa_pake_input() one or more - * times to exchange any further data that is needed to derive the shared - * secret. + * - Some algorithms exchange more data than just a single key share. When using + * such a algorithm, call psa_pake_output() and psa_pake_input() one or more + * times to exchange any further data that is needed to derive the shared + * secret. * * Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` * values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) @@ -4489,7 +4495,10 @@ psa_status_t psa_pake_setup(psa_pake_operation_t *operation, * \param[in,out] operation Active PAKE operation. * \param type The type of the data that is requested. * \param[out] output Buffer where the output is to be written. - * \param output_size Size of the \p output buffer in bytes. + * \param output_size Size of the \p output buffer in bytes. This must + * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \c + * cipher_suite, \p type). + * * \param[out] output_length On success, the number of bytes of the returned * output. * @@ -4574,8 +4583,9 @@ psa_status_t psa_pake_input(psa_pake_operation_t *operation, * state and must be aborted by calling psa_pake_abort(). * * \param[in,out] operation Active PAKE operation. - * \param[out] output A key derivation operation that has been - * initialized and set up. + * \param[out] output A key derivation operation that is ready + * for an input step of type + * #PSA_KEY_DERIVATION_INPUT_SECRET. * * \retval #PSA_SUCCESS * Success. diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index bb01d5315..4428fc01f 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -1144,13 +1144,14 @@ * \param alg A PAKE algorithm (PSA_ALG_XXX value such that * #PSA_ALG_IS_PAKE(\p alg) is true). * \param cipher_suite A cipher suite that is compatible with algorithm \p alg. - * \param output An output type used with algorithm \p alg. + * \param output_step A value of type ::psa_pake_data_t that is valid for the + * algorithm \p alg. * \return A sufficient output buffer size for the specified * output, cipher suite and algorithm. If the cipher suite, * the output type or PAKE algorithm is not recognized, or * the parameters are incompatible, return 0. */ -#define PSA_PAKE_OUTPUT_SIZE(alg, cipher_suite, output) +#define PSA_PAKE_OUTPUT_SIZE(alg, cipher_suite, output_step) /** Output buffer size for psa_pake_output() for any of the supported cipher * suites and PAKE algorithms. diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index a24337081..ab064dbdd 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -2501,12 +2501,14 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) */ #define PSA_PAKE_SIDE_SERVER ((psa_pake_side_t)0x12) -/** The PAKE uses elliptic curves. +/** The PAKE primitive type indicating the use of elliptic curves. * - * The corresponding family type is ::psa_ecc_family_t. In determining a - * specific curve in the family the cipher suite (see - * ::psa_pake_cipher_suite_t) bits are interpreted in the exact same way - * as key bits are. + * The values of the \c family and \c bits fields of the cipher suite identify a + * specific elliptic curve, using the same mapping that is used for ECC + * (::psa_ecc_family_t) keys. + * + * (Here \c familiy means the value returned by psa_pake_cs_get_family() and + * \c bits means the value returned by psa_pake_cs_get_bits().) * * Input and output during the operation can involve group elements and scalar * values: @@ -2519,12 +2521,14 @@ static inline int mbedtls_svc_key_id_is_null( mbedtls_svc_key_id_t key ) */ #define PSA_PAKE_PRIMITIVE_TYPE_ECC ((psa_pake_primitive_type_t)0x01) -/** The PAKE uses finite fields based Diffie-Hellman groups. +/** The PAKE primitive type indicating the use of Diffie-Hellman groups. * - * The corresponding family type is ::psa_dh_family_t. In determining a - * specific group in the family the cipher suite (see - * ::psa_pake_cipher_suite_t) bits are interpreted in the exact same way - * as key bits are. + * The values of the \c family and \c bits fields of the cipher suite identify + * a specific Diffie-Hellman group, using the same mapping that is used for + * Diffie-Hellman (::psa_dh_family_t) keys. + * + * (Here \c familiy means the value returned by psa_pake_cs_get_family() and + * \c bits means the value returned by psa_pake_cs_get_bits().) * * Input and output during the operation can involve group elements and scalar * values: