1 /* 2 * ECDH with curve-optimized implementation multiplexing 3 * 4 * Copyright 2016-2018 INRIA and Microsoft Corporation 5 * SPDX-License-Identifier: Apache-2.0 6 * 7 * Licensed under the Apache License, Version 2.0 (the "License"); you may 8 * not use this file except in compliance with the License. 9 * You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, software 14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 * See the License for the specific language governing permissions and 17 * limitations under the License. 18 * 19 * This file is part of mbed TLS (https://tls.mbed.org) 20 */ 21 22 #ifndef MBEDTLS_X25519_H 23 #define MBEDTLS_X25519_H 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 #define MBEDTLS_ECP_TLS_CURVE25519 0x1d 30 #define MBEDTLS_X25519_KEY_SIZE_BYTES 32 31 32 /** 33 * Defines the source of the imported EC key. 34 */ 35 typedef enum 36 { 37 MBEDTLS_X25519_ECDH_OURS, /**< Our key. */ 38 MBEDTLS_X25519_ECDH_THEIRS, /**< The key of the peer. */ 39 } mbedtls_x25519_ecdh_side; 40 41 /** 42 * \brief The x25519 context structure. 43 */ 44 typedef struct 45 { 46 unsigned char our_secret[MBEDTLS_X25519_KEY_SIZE_BYTES]; 47 unsigned char peer_point[MBEDTLS_X25519_KEY_SIZE_BYTES]; 48 } mbedtls_x25519_context; 49 50 /** 51 * \brief This function initializes an x25519 context. 52 * 53 * \param ctx The x25519 context to initialize. 54 */ 55 void mbedtls_x25519_init( mbedtls_x25519_context *ctx ); 56 57 /** 58 * \brief This function frees a context. 59 * 60 * \param ctx The context to free. 61 */ 62 void mbedtls_x25519_free( mbedtls_x25519_context *ctx ); 63 64 /** 65 * \brief This function generates a public key and a TLS 66 * ServerKeyExchange payload. 67 * 68 * This is the first function used by a TLS server for x25519. 69 * 70 * 71 * \param ctx The x25519 context. 72 * \param olen The number of characters written. 73 * \param buf The destination buffer. 74 * \param blen The length of the destination buffer. 75 * \param f_rng The RNG function. 76 * \param p_rng The RNG context. 77 * 78 * \return \c 0 on success. 79 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 80 */ 81 int mbedtls_x25519_make_params( mbedtls_x25519_context *ctx, size_t *olen, 82 unsigned char *buf, size_t blen, 83 int( *f_rng )(void *, unsigned char *, size_t), 84 void *p_rng ); 85 86 /** 87 * \brief This function parses and processes a TLS ServerKeyExchange 88 * payload. 89 * 90 * 91 * \param ctx The x25519 context. 92 * \param buf The pointer to the start of the input buffer. 93 * \param end The address for one Byte past the end of the buffer. 94 * 95 * \return \c 0 on success. 96 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 97 * 98 */ 99 int mbedtls_x25519_read_params( mbedtls_x25519_context *ctx, 100 const unsigned char **buf, const unsigned char *end ); 101 102 /** 103 * \brief This function sets up an x25519 context from an EC key. 104 * 105 * It is used by clients and servers in place of the 106 * ServerKeyEchange for static ECDH, and imports ECDH 107 * parameters from the EC key information of a certificate. 108 * 109 * \see ecp.h 110 * 111 * \param ctx The x25519 context to set up. 112 * \param key The EC key to use. 113 * \param side Defines the source of the key: 1: Our key, or 114 * 0: The key of the peer. 115 * 116 * \return \c 0 on success. 117 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 118 * 119 */ 120 int mbedtls_x25519_get_params( mbedtls_x25519_context *ctx, const mbedtls_ecp_keypair *key, 121 mbedtls_x25519_ecdh_side side ); 122 123 /** 124 * \brief This function derives and exports the shared secret. 125 * 126 * This is the last function used by both TLS client 127 * and servers. 128 * 129 * 130 * \param ctx The x25519 context. 131 * \param olen The number of Bytes written. 132 * \param buf The destination buffer. 133 * \param blen The length of the destination buffer. 134 * \param f_rng The RNG function. 135 * \param p_rng The RNG context. 136 * 137 * \return \c 0 on success. 138 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 139 */ 140 int mbedtls_x25519_calc_secret( mbedtls_x25519_context *ctx, size_t *olen, 141 unsigned char *buf, size_t blen, 142 int( *f_rng )(void *, unsigned char *, size_t), 143 void *p_rng ); 144 145 /** 146 * \brief This function generates a public key and a TLS 147 * ClientKeyExchange payload. 148 * 149 * This is the second function used by a TLS client for x25519. 150 * 151 * \see ecp.h 152 * 153 * \param ctx The x25519 context. 154 * \param olen The number of Bytes written. 155 * \param buf The destination buffer. 156 * \param blen The size of the destination buffer. 157 * \param f_rng The RNG function. 158 * \param p_rng The RNG context. 159 * 160 * \return \c 0 on success. 161 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 162 */ 163 int mbedtls_x25519_make_public( mbedtls_x25519_context *ctx, size_t *olen, 164 unsigned char *buf, size_t blen, 165 int( *f_rng )(void *, unsigned char *, size_t), 166 void *p_rng ); 167 168 /** 169 * \brief This function parses and processes a TLS ClientKeyExchange 170 * payload. 171 * 172 * This is the second function used by a TLS server for x25519. 173 * 174 * \see ecp.h 175 * 176 * \param ctx The x25519 context. 177 * \param buf The start of the input buffer. 178 * \param blen The length of the input buffer. 179 * 180 * \return \c 0 on success. 181 * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure. 182 */ 183 int mbedtls_x25519_read_public( mbedtls_x25519_context *ctx, 184 const unsigned char *buf, size_t blen ); 185 186 #ifdef __cplusplus 187 } 188 #endif 189 190 #endif /* x25519.h */ 191
