/* * PSA PAKE layer on top of Mbed TLS software crypto */ /* * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later */ #ifndef PSA_CRYPTO_PAKE_H #define PSA_CRYPTO_PAKE_H #include /** Set the session information for a password-authenticated key exchange. * * \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] inputs Inputs required for PAKE operation (role, password, * key lifetime, cipher suite) * * \retval #PSA_SUCCESS * Success. * \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_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, const psa_crypto_driver_pake_inputs_t *inputs); /** Get output for a step of a password-authenticated key exchange. * * \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 * requested. * \param[out] output Buffer where the output is to be written in the * format appropriate for this driver \p step. Refer to * the documentation of psa_crypto_driver_pake_step_t 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_INSUFFICIENT_ENTROPY \emptydescription * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription * \retval #PSA_ERROR_DATA_INVALID \emptydescription */ psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, psa_crypto_driver_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. * * \note The signature of this function is that of a PSA driver * pake_input entry point. This function behaves as a pake_input * entry point as defined in the PSA driver interface specification for * transparent drivers. * * \note The core checks that input_length is smaller than PSA_PAKE_INPUT_MAX_SIZE. * * \param[in,out] operation Active PAKE operation. * \param step The driver 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 psa_crypto_driver_pake_step_t * 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 zero-knowledge input step. * \retval #PSA_ERROR_INVALID_ARGUMENT * the \p input is not valid for the \p operation's algorithm, cipher suite * or \p step. * \retval #PSA_ERROR_NOT_SUPPORTED * the \p input is not supported for the \p operation's algorithm, cipher * suite or \p step. * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription * \retval #PSA_ERROR_DATA_INVALID \emptydescription */ psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, psa_crypto_driver_pake_step_t step, const uint8_t *input, size_t input_length); /** Get implicitly confirmed shared secret from a PAKE. * * \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 Output buffer for implicit key. * \param output_size Size of the output buffer in bytes. * \param[out] output_length On success, the number of bytes of the implicit key. * * \retval #PSA_SUCCESS * Success. * \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 \emptydescription * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription * \retval #PSA_ERROR_DATA_INVALID \emptydescription */ psa_status_t mbedtls_psa_pake_get_implicit_key( mbedtls_psa_pake_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length); /** Abort a PAKE operation. * * \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. * * \retval #PSA_SUCCESS * Success. * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription */ psa_status_t mbedtls_psa_pake_abort(mbedtls_psa_pake_operation_t *operation); #endif /* PSA_CRYPTO_PAKE_H */