psa_crypto_ffdh.h (5376B)
1 /* 2 * PSA FFDH layer on top of Mbed TLS 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_FFDH_H 10 #define PSA_CRYPTO_FFDH_H 11 12 #include <psa/crypto.h> 13 14 /** Perform a key agreement and return the FFDH shared secret. 15 * 16 * \param[in] attributes The attributes of the key to use for the 17 * operation. 18 * \param[in] peer_key The buffer containing the key context 19 * of the peer's public key. 20 * \param[in] peer_key_length Size of the \p peer_key buffer in 21 * bytes. 22 * \param[in] key_buffer The buffer containing the private key 23 * context. 24 * \param[in] key_buffer_size Size of the \p key_buffer buffer in 25 * bytes. 26 * \param[out] shared_secret The buffer to which the shared secret 27 * is to be written. 28 * \param[in] shared_secret_size Size of the \p shared_secret buffer in 29 * bytes. 30 * \param[out] shared_secret_length On success, the number of bytes that make 31 * up the returned shared secret. 32 * \retval #PSA_SUCCESS 33 * Success. Shared secret successfully calculated. 34 * \retval #PSA_ERROR_INVALID_ARGUMENT 35 * \p key_buffer_size, \p peer_key_length, \p shared_secret_size 36 * do not match 37 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 38 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 39 */ 40 psa_status_t mbedtls_psa_ffdh_key_agreement( 41 const psa_key_attributes_t *attributes, 42 const uint8_t *peer_key, 43 size_t peer_key_length, 44 const uint8_t *key_buffer, 45 size_t key_buffer_size, 46 uint8_t *shared_secret, 47 size_t shared_secret_size, 48 size_t *shared_secret_length); 49 50 /** Export a public key or the public part of a DH key pair in binary format. 51 * 52 * \param[in] attributes The attributes for the key to export. 53 * \param[in] key_buffer Material or context of the key to export. 54 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. 55 * \param[out] data Buffer where the key data is to be written. 56 * \param[in] data_size Size of the \p data buffer in bytes. 57 * \param[out] data_length On success, the number of bytes written in 58 * \p data 59 * 60 * \retval #PSA_SUCCESS The public key was exported successfully. 61 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 62 * The size of \p key_buffer is too small. 63 * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription 64 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 65 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 66 */ 67 psa_status_t mbedtls_psa_ffdh_export_public_key( 68 const psa_key_attributes_t *attributes, 69 const uint8_t *key_buffer, 70 size_t key_buffer_size, 71 uint8_t *data, 72 size_t data_size, 73 size_t *data_length); 74 75 /** 76 * \brief Generate DH key. 77 * 78 * \note The signature of the function is that of a PSA driver generate_key 79 * entry point. 80 * 81 * \param[in] attributes The attributes for the key to generate. 82 * \param[out] key_buffer Buffer where the key data is to be written. 83 * \param[in] key_buffer_size Size of \p key_buffer in bytes. 84 * \param[out] key_buffer_length On success, the number of bytes written in 85 * \p key_buffer. 86 * 87 * \retval #PSA_SUCCESS 88 * The key was generated successfully. 89 * \retval #PSA_ERROR_NOT_SUPPORTED 90 * Key size in bits is invalid. 91 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 92 * The size of \p key_buffer is too small. 93 * \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription 94 * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription 95 */ 96 psa_status_t mbedtls_psa_ffdh_generate_key( 97 const psa_key_attributes_t *attributes, 98 uint8_t *key_buffer, 99 size_t key_buffer_size, 100 size_t *key_buffer_length); 101 102 /** 103 * \brief Import DH key. 104 * 105 * \note The signature of the function is that of a PSA driver import_key 106 * entry point. 107 * 108 * \param[in] attributes The attributes for the key to import. 109 * \param[in] data The buffer containing the key data in import 110 * format. 111 * \param[in] data_length Size of the \p data buffer in bytes. 112 * \param[out] key_buffer The buffer containing the key data in output 113 * format. 114 * \param[in] key_buffer_size Size of the \p key_buffer buffer in bytes. This 115 * size is greater or equal to \p data_length. 116 * \param[out] key_buffer_length The length of the data written in \p 117 * key_buffer in bytes. 118 * \param[out] bits The key size in number of bits. 119 * 120 * \retval #PSA_SUCCESS 121 * The key was generated successfully. 122 * \retval #PSA_ERROR_BUFFER_TOO_SMALL 123 * The size of \p key_buffer is too small. 124 */ 125 psa_status_t mbedtls_psa_ffdh_import_key( 126 const psa_key_attributes_t *attributes, 127 const uint8_t *data, size_t data_length, 128 uint8_t *key_buffer, size_t key_buffer_size, 129 size_t *key_buffer_length, size_t *bits); 130 131 #endif /* PSA_CRYPTO_FFDH_H */