AuroraMiddleware/mbedtls
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

PSA PAKE: improve documentation

Browse Source 
Minor documentation improvement and fixes.

Signed-off-by: Janos Follath <janos.follath@arm.com>
This commit is contained in:
Janos Follath 2021-05-11 08:24:56 +01:00
parent f75be64ef5
commit 1459aa5656
3 changed files with 40 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
include/psa/crypto.h
View File

@ -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.

5
include/psa/crypto_sizes.h
View File

@ -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.

24
include/psa/crypto_values.h
View File

@ -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: