PSA PAKE: improve documentation

Minor documentation improvement and fixes.

Signed-off-by: Janos Follath <janos.follath@arm.com>

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
+ *                              the primitive type. For more information
- *                              documentation of individual
+ *                              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,
+ * -# Call psa_pake_setup() to specify the algorithm, the password, cipher
- *    identities and additional session information.
+ *    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
+ * - 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
+ *   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
+ *   times to exchange any further data that is needed to derive the shared
- *    secret.
+ *   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
+ * \param[out] output          A key derivation operation that is ready
- *                             initialized and set up.
+ *                             for an input step of type
+ *                             #PSA_KEY_DERIVATION_INPUT_SECRET.
  *
  * \retval #PSA_SUCCESS
  *         Success.

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.

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
+ * The values of the \c family and \c bits fields of the cipher suite identify a
- * specific curve in the family the cipher suite (see
+ * specific elliptic curve, using the same mapping that is used for ECC
- * ::psa_pake_cipher_suite_t) bits are interpreted in the exact same way
+ * (::psa_ecc_family_t) keys.
- * as key bits are.
+ *
+ * (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
+ * The values of the \c family and \c bits fields of the cipher suite identify
- * specific group in the family the cipher suite (see
+ * a specific Diffie-Hellman group, using the same mapping that is used for
- * ::psa_pake_cipher_suite_t) bits are interpreted in the exact same way
+ * Diffie-Hellman (::psa_dh_family_t) keys.
- * as key bits are.
+ *
+ * (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: