v2 / thirdparty / mbedtls / library / psa_crypto_pake.h
159 lines · 150 sloc · 7.09 KB · 1274cdc3447be8e83616e8512872455e8720c2fd
Raw 


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 */


37psa_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 */


74psa_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 */


112psa_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 */


139psa_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 */


157psa_status_t mbedtls_psa_pake_abort(mbedtls_psa_pake_operation_t *operation);


158


159#endif /* PSA_CRYPTO_PAKE_H */


160