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