| /* |
| * PSA PAKE layer on top of Mbed TLS software crypto |
| */ |
| /* |
| * Copyright The Mbed TLS Contributors |
| * SPDX-License-Identifier: Apache-2.0 |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may |
| * not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| #ifndef PSA_CRYPTO_PAKE_H |
| #define PSA_CRYPTO_PAKE_H |
| |
| #include <psa/crypto.h> |
| |
| /** 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 |
| * \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(psa_pake_operation_t *operation, |
| const psa_pake_cipher_suite_t *cipher_suite); |
| |
| /** 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. |
| * |
| * \param[in,out] operation The operation object to set the password for. It |
| * must have been set up by psa_pake_setup() and |
| * not yet in use (neither psa_pake_output() nor |
| * psa_pake_input() has been called yet). It must |
| * be on operation for which the password hasn't |
| * been set yet (psa_pake_set_password_key() |
| * hasn't been called yet). |
| * \param password Identifier of the key holding the password or a |
| * value derived from the password (eg. by a |
| * memory-hard function). It must remain valid |
| * until the operation terminates. It must be of |
| * type #PSA_KEY_TYPE_PASSWORD or |
| * #PSA_KEY_TYPE_PASSWORD_HASH. It has to allow |
| * the usage #PSA_KEY_USAGE_DERIVE. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \retval #PSA_ERROR_INVALID_HANDLE |
| * \p password is not a valid key identifier. |
| * \retval #PSA_ERROR_NOT_PERMITTED |
| * The key does not have the #PSA_KEY_USAGE_DERIVE flag, or it does not |
| * permit the \p operation's algorithm. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * The key type for \p password is not #PSA_KEY_TYPE_PASSWORD or |
| * #PSA_KEY_TYPE_PASSWORD_HASH, or \p password is not compatible with |
| * the \p operation's cipher suite. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * The key type or key size of \p password is not supported with the |
| * \p operation's cipher suite. |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_STORAGE_FAILURE |
| * \retval #PSA_ERROR_DATA_CORRUPT |
| * \retval #PSA_ERROR_DATA_INVALID |
| * \retval #PSA_ERROR_BAD_STATE |
| * The operation state is not valid (it must have been set up.), 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_set_password_key( |
| psa_pake_operation_t *operation, |
| mbedtls_svc_key_id_t password); |
| |
| /** 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. |
| * |
| * \param[in,out] operation The operation object to set the user ID for. It |
| * must have been set up by psa_pake_setup() and |
| * not yet in use (neither psa_pake_output() nor |
| * psa_pake_input() has been called yet). It must |
| * be on operation for which the user ID hasn't |
| * been set (psa_pake_set_user() hasn't been |
| * called yet). |
| * \param[in] user_id The user ID to authenticate with. |
| * \param user_id_len Size of the \p user_id buffer in bytes. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \p user_id is not valid for the \p operation's algorithm and cipher |
| * suite. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * The value of \p user_id is not supported by the implementation. |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \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_set_user(psa_pake_operation_t *operation, |
| const uint8_t *user_id, |
| size_t user_id_len); |
| |
| /** 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. |
| * |
| * \param[in,out] operation The operation object to set the peer ID for. It |
| * must have been set up by psa_pake_setup() and |
| * not yet in use (neither psa_pake_output() nor |
| * psa_pake_input() has been called yet). It must |
| * be on operation for which the peer ID hasn't |
| * been set (psa_pake_set_peer() hasn't been |
| * called yet). |
| * \param[in] peer_id The peer's ID to authenticate. |
| * \param peer_id_len Size of the \p peer_id buffer in bytes. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \p user_id is not valid for the \p operation's algorithm and cipher |
| * suite. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * The algorithm doesn't associate a second identity with the session. |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_BAD_STATE |
| * Calling psa_pake_set_peer() is invalid with the \p operation's |
| * algorithm, 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_set_peer(psa_pake_operation_t *operation, |
| const uint8_t *peer_id, |
| size_t peer_id_len); |
| |
| /** 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. |
| * |
| * \param[in,out] operation The operation object to specify the |
| * application's role for. It must have been set up |
| * by psa_pake_setup() and not yet in use (neither |
| * psa_pake_output() nor psa_pake_input() has been |
| * called yet). It must be on operation for which |
| * the application's role hasn't been specified |
| * (psa_pake_set_role() hasn't been called yet). |
| * \param role A value of type ::psa_pake_role_t indicating the |
| * application's role in the PAKE the algorithm |
| * that is being set up. For more information see |
| * the documentation of \c PSA_PAKE_ROLE_XXX |
| * constants. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * The \p role is not a valid PAKE role in the \p operation’s algorithm. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * The \p role for this algorithm is not supported or is not valid. |
| * \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_set_role(psa_pake_operation_t *operation, |
| psa_pake_role_t role); |
| |
| /** 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(). |
| * |
| * \param[in,out] operation Active PAKE operation. |
| * \param step The step of the algorithm for which the output is |
| * requested. |
| * \param[out] output Buffer where the output is to be written in the |
| * format appropriate for this \p step. Refer to |
| * the documentation of the individual |
| * \c PSA_PAKE_STEP_XXX constants for more |
| * information. |
| * \param output_size Size of the \p output buffer in bytes. This must |
| * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p |
| * primitive, \p step) where \p alg and |
| * \p primitive are the PAKE algorithm and primitive |
| * in the operation's cipher suite, and \p step is |
| * the output step. |
| * |
| * \param[out] output_length On success, the number of bytes of the returned |
| * output. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \retval #PSA_ERROR_BUFFER_TOO_SMALL |
| * The size of the \p output buffer is too small. |
| * \retval #PSA_ERROR_INVALID_ARGUMENT |
| * \p step is not compatible with the operation's algorithm. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \p step is not supported with the operation's algorithm. |
| * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_STORAGE_FAILURE |
| * \retval #PSA_ERROR_DATA_CORRUPT |
| * \retval #PSA_ERROR_DATA_INVALID |
| * \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(). |
| * It is implementation-dependent whether a failure to initialize |
| * results in this error code. |
| */ |
| psa_status_t mbedtls_psa_pake_output(psa_pake_operation_t *operation, |
| psa_pake_step_t step, |
| uint8_t *output, |
| size_t output_size, |
| size_t *output_length); |
| |
| /** 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(). |
| * |
| * \param[in,out] operation Active PAKE operation. |
| * \param step The step for which the input is provided. |
| * \param[in] input Buffer containing the input in the format |
| * appropriate for this \p step. Refer to the |
| * documentation of the individual |
| * \c PSA_PAKE_STEP_XXX constants for more |
| * information. |
| * \param input_length Size of the \p input buffer in bytes. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \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 input is not valid for the \p operation's algorithm, cipher suite |
| * or \p step. |
| * \retval #PSA_ERROR_NOT_SUPPORTED |
| * \p step p is not supported with the \p operation's algorithm, or the |
| * \p input is not supported for the \p operation's algorithm, cipher |
| * suite or \p step. |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_STORAGE_FAILURE |
| * \retval #PSA_ERROR_DATA_CORRUPT |
| * \retval #PSA_ERROR_DATA_INVALID |
| * \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(). |
| * It is implementation-dependent whether a failure to initialize |
| * results in this error code. |
| */ |
| psa_status_t mbedtls_psa_pake_input(psa_pake_operation_t *operation, |
| psa_pake_step_t step, |
| const uint8_t *input, |
| size_t input_length); |
| |
| /** 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. |
| * |
| * \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. |
| * |
| * \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. |
| * \retval #PSA_ERROR_INSUFFICIENT_MEMORY |
| * \retval #PSA_ERROR_COMMUNICATION_FAILURE |
| * \retval #PSA_ERROR_CORRUPTION_DETECTED |
| * \retval #PSA_ERROR_STORAGE_FAILURE |
| * \retval #PSA_ERROR_DATA_CORRUPT |
| * \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(), |
| * 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 |
| * and it may not be repeated. |
| * It is implementation-dependent whether a failure to initialize |
| * results in this error code. |
| */ |
| psa_status_t mbedtls_psa_pake_get_implicit_key( |
| psa_pake_operation_t *operation, |
| psa_key_derivation_operation_t *output); |
| |
| /** 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. |
| * |
| * \param[in,out] operation The operation to abort. |
| * |
| * \retval #PSA_SUCCESS |
| * Success. |
| * \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. |
| */ |
| psa_status_t mbedtls_psa_pake_abort(psa_pake_operation_t *operation); |
| |
| #endif /* PSA_CRYPTO_PAKE_H */ |