1*b0563631STom Van Eyck /* 2*b0563631STom Van Eyck * PSA PAKE layer on top of Mbed TLS software crypto 3*b0563631STom Van Eyck */ 4*b0563631STom Van Eyck /* 5*b0563631STom Van Eyck * Copyright The Mbed TLS Contributors 6*b0563631STom Van Eyck * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 7*b0563631STom Van Eyck */ 8*b0563631STom Van Eyck 9*b0563631STom Van Eyck #ifndef PSA_CRYPTO_PAKE_H 10*b0563631STom Van Eyck #define PSA_CRYPTO_PAKE_H 11*b0563631STom Van Eyck 12*b0563631STom Van Eyck #include <psa/crypto.h> 13*b0563631STom Van Eyck 14*b0563631STom Van Eyck /** Set the session information for a password-authenticated key exchange. 15*b0563631STom Van Eyck * 16*b0563631STom Van Eyck * \note The signature of this function is that of a PSA driver 17*b0563631STom Van Eyck * pake_setup entry point. This function behaves as a pake_setup 18*b0563631STom Van Eyck * entry point as defined in the PSA driver interface specification for 19*b0563631STom Van Eyck * transparent drivers. 20*b0563631STom Van Eyck * 21*b0563631STom Van Eyck * \param[in,out] operation The operation object to set up. It must have 22*b0563631STom Van Eyck * been initialized but not set up yet. 23*b0563631STom Van Eyck * \param[in] inputs Inputs required for PAKE operation (role, password, 24*b0563631STom Van Eyck * key lifetime, cipher suite) 25*b0563631STom Van Eyck * 26*b0563631STom Van Eyck * \retval #PSA_SUCCESS 27*b0563631STom Van Eyck * Success. 28*b0563631STom Van Eyck * \retval #PSA_ERROR_NOT_SUPPORTED 29*b0563631STom Van Eyck * The algorithm in \p cipher_suite is not a supported PAKE algorithm, 30*b0563631STom Van Eyck * or the PAKE primitive in \p cipher_suite is not supported or not 31*b0563631STom Van Eyck * compatible with the PAKE algorithm, or the hash algorithm in 32*b0563631STom Van Eyck * \p cipher_suite is not supported or not compatible with the PAKE 33*b0563631STom Van Eyck * algorithm and primitive. 34*b0563631STom Van Eyck * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 35*b0563631STom Van Eyck * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 36*b0563631STom Van Eyck */ 37*b0563631STom Van Eyck psa_status_t mbedtls_psa_pake_setup(mbedtls_psa_pake_operation_t *operation, 38*b0563631STom Van Eyck const psa_crypto_driver_pake_inputs_t *inputs); 39*b0563631STom Van Eyck 40*b0563631STom Van Eyck 41*b0563631STom Van Eyck /** Get output for a step of a password-authenticated key exchange. 42*b0563631STom Van Eyck * 43*b0563631STom Van Eyck * \note The signature of this function is that of a PSA driver 44*b0563631STom Van Eyck * pake_output entry point. This function behaves as a pake_output 45*b0563631STom Van Eyck * entry point as defined in the PSA driver interface specification for 46*b0563631STom Van Eyck * transparent drivers. 47*b0563631STom Van Eyck * 48*b0563631STom Van Eyck * \param[in,out] operation Active PAKE operation. 49*b0563631STom Van Eyck * \param step The step of the algorithm for which the output is 50*b0563631STom Van Eyck * requested. 51*b0563631STom Van Eyck * \param[out] output Buffer where the output is to be written in the 52*b0563631STom Van Eyck * format appropriate for this driver \p step. Refer to 53*b0563631STom Van Eyck * the documentation of psa_crypto_driver_pake_step_t for 54*b0563631STom Van Eyck * more information. 55*b0563631STom Van Eyck * \param output_size Size of the \p output buffer in bytes. This must 56*b0563631STom Van Eyck * be at least #PSA_PAKE_OUTPUT_SIZE(\p alg, \p 57*b0563631STom Van Eyck * primitive, \p step) where \p alg and 58*b0563631STom Van Eyck * \p primitive are the PAKE algorithm and primitive 59*b0563631STom Van Eyck * in the operation's cipher suite, and \p step is 60*b0563631STom Van Eyck * the output step. 61*b0563631STom Van Eyck * 62*b0563631STom Van Eyck * \param[out] output_length On success, the number of bytes of the returned 63*b0563631STom Van Eyck * output. 64*b0563631STom Van Eyck * 65*b0563631STom Van Eyck * \retval #PSA_SUCCESS 66*b0563631STom Van Eyck * Success. 67*b0563631STom Van Eyck * \retval #PSA_ERROR_BUFFER_TOO_SMALL 68*b0563631STom Van Eyck * The size of the \p output buffer is too small. 69*b0563631STom Van Eyck * \retval #PSA_ERROR_INSUFFICIENT_ENTROPY \emptydescription 70*b0563631STom Van Eyck * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 71*b0563631STom Van Eyck * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 72*b0563631STom Van Eyck * \retval #PSA_ERROR_DATA_INVALID \emptydescription 73*b0563631STom Van Eyck */ 74*b0563631STom Van Eyck psa_status_t mbedtls_psa_pake_output(mbedtls_psa_pake_operation_t *operation, 75*b0563631STom Van Eyck psa_crypto_driver_pake_step_t step, 76*b0563631STom Van Eyck uint8_t *output, 77*b0563631STom Van Eyck size_t output_size, 78*b0563631STom Van Eyck size_t *output_length); 79*b0563631STom Van Eyck 80*b0563631STom Van Eyck /** Provide input for a step of a password-authenticated key exchange. 81*b0563631STom Van Eyck * 82*b0563631STom Van Eyck * \note The signature of this function is that of a PSA driver 83*b0563631STom Van Eyck * pake_input entry point. This function behaves as a pake_input 84*b0563631STom Van Eyck * entry point as defined in the PSA driver interface specification for 85*b0563631STom Van Eyck * transparent drivers. 86*b0563631STom Van Eyck * 87*b0563631STom Van Eyck * \note The core checks that input_length is smaller than PSA_PAKE_INPUT_MAX_SIZE. 88*b0563631STom Van Eyck * 89*b0563631STom Van Eyck * \param[in,out] operation Active PAKE operation. 90*b0563631STom Van Eyck * \param step The driver step for which the input is provided. 91*b0563631STom Van Eyck * \param[in] input Buffer containing the input in the format 92*b0563631STom Van Eyck * appropriate for this \p step. Refer to the 93*b0563631STom Van Eyck * documentation of psa_crypto_driver_pake_step_t 94*b0563631STom Van Eyck * for more information. 95*b0563631STom Van Eyck * \param input_length Size of the \p input buffer in bytes. 96*b0563631STom Van Eyck * 97*b0563631STom Van Eyck * \retval #PSA_SUCCESS 98*b0563631STom Van Eyck * Success. 99*b0563631STom Van Eyck * \retval #PSA_ERROR_INVALID_SIGNATURE 100*b0563631STom Van Eyck * The verification fails for a zero-knowledge input step. 101*b0563631STom Van Eyck * \retval #PSA_ERROR_INVALID_ARGUMENT 102*b0563631STom Van Eyck * the \p input is not valid for the \p operation's algorithm, cipher suite 103*b0563631STom Van Eyck * or \p step. 104*b0563631STom Van Eyck * \retval #PSA_ERROR_NOT_SUPPORTED 105*b0563631STom Van Eyck * the \p input is not supported for the \p operation's algorithm, cipher 106*b0563631STom Van Eyck * suite or \p step. 107*b0563631STom Van Eyck * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 108*b0563631STom Van Eyck * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 109*b0563631STom Van Eyck * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 110*b0563631STom Van Eyck * \retval #PSA_ERROR_DATA_INVALID \emptydescription 111*b0563631STom Van Eyck */ 112*b0563631STom Van Eyck psa_status_t mbedtls_psa_pake_input(mbedtls_psa_pake_operation_t *operation, 113*b0563631STom Van Eyck psa_crypto_driver_pake_step_t step, 114*b0563631STom Van Eyck const uint8_t *input, 115*b0563631STom Van Eyck size_t input_length); 116*b0563631STom Van Eyck 117*b0563631STom Van Eyck /** Get implicitly confirmed shared secret from a PAKE. 118*b0563631STom Van Eyck * 119*b0563631STom Van Eyck * \note The signature of this function is that of a PSA driver 120*b0563631STom Van Eyck * pake_get_implicit_key entry point. This function behaves as a 121*b0563631STom Van Eyck * pake_get_implicit_key entry point as defined in the PSA driver 122*b0563631STom Van Eyck * interface specification for transparent drivers. 123*b0563631STom Van Eyck * 124*b0563631STom Van Eyck * \param[in,out] operation Active PAKE operation. 125*b0563631STom Van Eyck * \param[out] output Output buffer for implicit key. 126*b0563631STom Van Eyck * \param output_size Size of the output buffer in bytes. 127*b0563631STom Van Eyck * \param[out] output_length On success, the number of bytes of the implicit key. 128*b0563631STom Van Eyck * 129*b0563631STom Van Eyck * \retval #PSA_SUCCESS 130*b0563631STom Van Eyck * Success. 131*b0563631STom Van Eyck * \retval #PSA_ERROR_NOT_SUPPORTED 132*b0563631STom Van Eyck * Input from a PAKE is not supported by the algorithm in the \p output 133*b0563631STom Van Eyck * key derivation operation. 134*b0563631STom Van Eyck * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 135*b0563631STom Van Eyck * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 136*b0563631STom Van Eyck * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription 137*b0563631STom Van Eyck * \retval #PSA_ERROR_DATA_INVALID \emptydescription 138*b0563631STom Van Eyck */ 139*b0563631STom Van Eyck psa_status_t mbedtls_psa_pake_get_implicit_key( 140*b0563631STom Van Eyck mbedtls_psa_pake_operation_t *operation, 141*b0563631STom Van Eyck uint8_t *output, size_t output_size, 142*b0563631STom Van Eyck size_t *output_length); 143*b0563631STom Van Eyck 144*b0563631STom Van Eyck /** Abort a PAKE operation. 145*b0563631STom Van Eyck * 146*b0563631STom Van Eyck * \note The signature of this function is that of a PSA driver 147*b0563631STom Van Eyck * pake_abort entry point. This function behaves as a pake_abort 148*b0563631STom Van Eyck * entry point as defined in the PSA driver interface specification for 149*b0563631STom Van Eyck * transparent drivers. 150*b0563631STom Van Eyck * 151*b0563631STom Van Eyck * \param[in,out] operation The operation to abort. 152*b0563631STom Van Eyck * 153*b0563631STom Van Eyck * \retval #PSA_SUCCESS 154*b0563631STom Van Eyck * Success. 155*b0563631STom Van Eyck * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 156*b0563631STom Van Eyck */ 157*b0563631STom Van Eyck psa_status_t mbedtls_psa_pake_abort(mbedtls_psa_pake_operation_t *operation); 158*b0563631STom Van Eyck 159*b0563631STom Van Eyck #endif /* PSA_CRYPTO_PAKE_H */ 160