Symbols ![]()
loading...
Files ![]()
loading...
psa_pake_setup() function
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().
Syntax
psa_status_t psa_pake_setup(psa_pake_operation_t *operation,
const psa_pake_cipher_suite_t *cipher_suite);
Return value
#PSA_SUCCESS Success. #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. #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. #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription #PSA_ERROR_CORRUPTION_DETECTED \emptydescription #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.
Related Functions
Found 16 other functions taking a ![]()
psa_pake_operation_s
argument:
Function
Description
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.
Set the password for a password-authenticated key exchange from key ID. Call this function when the password, or a value derived from the password, is already present in the key store.
Set the user ID for a password-authenticated key exchange. Call this function to set the user ID. For PAKE algorithms that associate a user identifier with each side of the session you need to call psa_pake_set_peer() as well. For PAKE algorithms that associate a single user identifier with the session, call psa_pake_set_user() only. 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.
Set the peer ID for a password-authenticated key exchange. Call this function in addition to psa_pake_set_user() for PAKE algorithms that associate a user identifier with each side of the session. For PAKE algorithms that associate a single user identifier with the session, call psa_pake_set_user() only. 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.
Set the application role for a password-authenticated key exchange. Not all PAKE algorithms need to differentiate the communicating entities. It is optional to call this function for PAKEs that don't require a role to be specified. For such PAKEs the application role parameter is ignored, or #PSA_PAKE_ROLE_NONE can be passed as \c role. 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.
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().
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().
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 \c key_derivation operations enter an error state and must be aborted by calling psa_pake_abort() and psa_key_derivation_abort() respectively.