diff --git a/library/psa_crypto_pake.h b/library/psa_crypto_pake.h index 4768cee119..608d76aed7 100644 --- a/library/psa_crypto_pake.h +++ b/library/psa_crypto_pake.h @@ -25,73 +25,24 @@ /** Set the session information for a password-authenticated key exchange. * - * The sequence of operations to set up a password-authenticated key exchange - * is as follows: - * -# Allocate an operation object which will be passed to all the functions - * listed here. - * -# 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 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. - * - * 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) - * for more information. - * - * A typical sequence of calls to perform a password-authenticated key - * exchange: - * -# Call psa_pake_output(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to get the - * key share that needs to be sent to the peer. - * -# Call psa_pake_input(operation, #PSA_PAKE_STEP_KEY_SHARE, ...) to provide - * the key share that was received from the peer. - * -# Depending on the algorithm additional calls to psa_pake_output() and - * psa_pake_input() might be necessary. - * -# Call psa_pake_get_implicit_key() for accessing 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) - * for more information. - * - * If an error occurs at any step after a call to psa_pake_setup(), - * the operation will need to be reset by a call to psa_pake_abort(). The - * application may call psa_pake_abort() at any time after the operation - * has been initialized. - * - * After a successful call to psa_pake_setup(), the application must - * eventually terminate the operation. The following events terminate an - * operation: - * - A call to psa_pake_abort(). - * - A successful call to psa_pake_get_implicit_key(). + * \note The signature of this function is that of a PSA driver + * pake_setup entry point. This function behaves as a pake_setup + * entry point as defined in the PSA driver interface specification for + * transparent drivers. * * \param[in,out] operation The operation object to set up. It must have * been initialized but not set up yet. - * \param[in] cipher_suite The cipher suite to use. (A cipher suite fully - * characterizes a PAKE algorithm and determines - * the algorithm as well.) + * \param[in] inputs Inputs required for PAKE operation (role, password, + * key lifetime, cipher suite) * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * The algorithm in \p cipher_suite is not a PAKE algorithm, or the - * PAKE primitive in \p cipher_suite is not compatible with the - * PAKE algorithm, or the hash algorithm in \p cipher_suite is invalid - * or not compatible with the PAKE algorithm and primitive. * \retval #PSA_ERROR_NOT_SUPPORTED * The algorithm in \p cipher_suite is not a supported PAKE algorithm, * or the PAKE primitive in \p cipher_suite is not supported or not * compatible with the PAKE algorithm, or the hash algorithm in * \p cipher_suite is not supported or not compatible with the PAKE * algorithm and primitive. - * \retval #PSA_ERROR_COMMUNICATION_FAILURE - * \retval #PSA_ERROR_CORRUPTION_DETECTED - * \retval #PSA_ERROR_BAD_STATE - * The operation state is not valid, or - * the library has not been previously initialized by psa_crypto_init(). - * It is implementation-dependent whether a failure to initialize - * results in this error code. */ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, const psa_crypto_driver_pake_inputs_t *inputs); @@ -99,17 +50,10 @@ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, /** 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. - * - * The exact sequence of calls to perform a password-authenticated key - * exchange depends on the algorithm in use. 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) for more - * information. - * - * If this function returns an error status, the operation enters an error - * state and must be aborted by calling psa_pake_abort(). + * \note The signature of this function is that of a PSA driver + * pake_output entry point. This function behaves as a pake_output + * entry point as defined in the PSA driver interface specification for + * transparent drivers. * * \param[in,out] operation Active PAKE operation. * \param step The step of the algorithm for which the output is @@ -147,8 +91,7 @@ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, and fully set * up, and this call must conform to the algorithm's requirements - * for ordering of input and output steps), or - * the library has not been previously initialized by psa_crypto_init(). + * for ordering of input and output steps). * It is implementation-dependent whether a failure to initialize * results in this error code. */ @@ -160,17 +103,10 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, /** 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. - * - * The exact sequence of calls to perform a password-authenticated key - * exchange depends on the algorithm in use. 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) for more - * information. - * - * If this function returns an error status, the operation enters an error - * state and must be aborted by calling psa_pake_abort(). + * \note The signature of this function is that of a PSA driver + * key_agreement entry point. This function behaves as a key_agreement + * entry point as defined in the PSA driver interface specification for + * transparent drivers. * * \param[in,out] operation Active PAKE operation. * \param step The step for which the input is provided. @@ -186,7 +122,7 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, * \retval #PSA_ERROR_INVALID_SIGNATURE * The verification fails for a #PSA_PAKE_STEP_ZK_PROOF input step. * \retval #PSA_ERROR_INVALID_ARGUMENT - * \p is not compatible with the \p operation’s algorithm, or the + * \p step is not compatible with the \p operation’s algorithm, or the * \p input is not valid for the \p operation's algorithm, cipher suite * or \p step. * \retval #PSA_ERROR_NOT_SUPPORTED @@ -202,8 +138,7 @@ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, * \retval #PSA_ERROR_BAD_STATE * The operation state is not valid (it must be active, and fully set * up, and this call must conform to the algorithm's requirements - * for ordering of input and output steps), or - * the library has not been previously initialized by psa_crypto_init(). + * for ordering of input and output steps). * It is implementation-dependent whether a failure to initialize * results in this error code. */ @@ -214,42 +149,17 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, /** Get implicitly confirmed shared secret from a PAKE. * - * At this point there is a cryptographic guarantee that only the authenticated - * party who used the same password is able to compute the key. But there is no - * guarantee that the peer is the party it claims to be and was able to do so. - * - * That is, the authentication is only implicit. Since the peer is not - * authenticated yet, no action should be taken yet that assumes that the peer - * is who it claims to be. For example, do not access restricted files on the - * peer's behalf until an explicit authentication has succeeded. - * - * This function can be called after the key exchange phase of the operation - * has completed. It imports the shared secret output of the PAKE into the - * provided derivation operation. The input step - * #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key - * material in the key derivation operation. - * - * The exact sequence of calls to perform a password-authenticated key - * exchange depends on the algorithm in use. 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) for more - * information. - * - * When this function returns successfully, \p operation becomes inactive. - * If this function returns an error status, both \p operation - * and \p key_derivation operations enter an error state and must be aborted by - * calling psa_pake_abort() and psa_key_derivation_abort() respectively. + * \note The signature of this function is that of a PSA driver + * pake_get_implicit_key entry point. This function behaves as a + * pake_get_implicit_key entry point as defined in the PSA driver + * interface specification for transparent drivers. * * \param[in,out] operation Active PAKE operation. - * \param[out] output A key derivation operation that is ready - * for an input step of type - * #PSA_KEY_DERIVATION_INPUT_SECRET. + * \param[out] output Output buffer for implicit key + * \param[out] output_size Size of the returned implicit key * * \retval #PSA_SUCCESS * Success. - * \retval #PSA_ERROR_INVALID_ARGUMENT - * #PSA_KEY_DERIVATION_INPUT_SECRET is not compatible with the - * algorithm in the \p output key derivation operation. * \retval #PSA_ERROR_NOT_SUPPORTED * Input from a PAKE is not supported by the algorithm in the \p output * key derivation operation. @@ -261,8 +171,7 @@ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, * \retval #PSA_ERROR_DATA_INVALID * \retval #PSA_ERROR_BAD_STATE * The PAKE operation state is not valid (it must be active, but beyond - * that validity is specific to the algorithm), or - * the library has not been previously initialized by psa_crypto_init(), + * that validity is specific to the algorithm), * or the state of \p output is not valid for * the #PSA_KEY_DERIVATION_INPUT_SECRET step. This can happen if the * step is out of order or the application has done this step already @@ -276,16 +185,10 @@ psa_status_t mbedtls_psa_pake_get_implicit_key( /** Abort a PAKE operation. * - * Aborting an operation frees all associated resources except for the \c - * operation structure itself. Once aborted, the operation object can be reused - * for another operation by calling psa_pake_setup() again. - * - * This function may be called at any time after the operation - * object has been initialized as described in #psa_pake_operation_t. - * - * In particular, calling psa_pake_abort() after the operation has been - * terminated by a call to psa_pake_abort() or psa_pake_get_implicit_key() - * is safe and has no effect. + * \note The signature of this function is that of a PSA driver + * pake_abort entry point. This function behaves as a pake_abort + * entry point as defined in the PSA driver interface specification for + * transparent drivers. * * \param[in,out] operation The operation to abort. * @@ -294,7 +197,6 @@ psa_status_t mbedtls_psa_pake_get_implicit_key( * \retval #PSA_ERROR_COMMUNICATION_FAILURE * \retval #PSA_ERROR_CORRUPTION_DETECTED * \retval #PSA_ERROR_BAD_STATE - * The library has not been previously initialized by psa_crypto_init(). * It is implementation-dependent whether a failure to initialize * results in this error code. */