Function esp_idf_svc::sys::psa_pake_setup

pub unsafe extern "C" fn psa_pake_setup(
    operation: *mut psa_pake_operation_s,
    cipher_suite: *const psa_pake_cipher_suite_s,
) -> i32

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().

\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.)

\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 \emptydescription \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription \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.