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