ecdh.h 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. /**
  2. * \file ecdh.h
  3. *
  4. * \brief The Elliptic Curve Diffie-Hellman (ECDH) protocol APIs.
  5. *
  6. * ECDH is an anonymous key agreement protocol allowing two parties to
  7. * establish a shared secret over an insecure channel. Each party must have an
  8. * elliptic-curve public–private key pair.
  9. *
  10. * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
  11. * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
  12. * Cryptography</em>.
  13. */
  14. /*
  15. * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  16. * SPDX-License-Identifier: Apache-2.0
  17. *
  18. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  19. * not use this file except in compliance with the License.
  20. * You may obtain a copy of the License at
  21. *
  22. * http://www.apache.org/licenses/LICENSE-2.0
  23. *
  24. * Unless required by applicable law or agreed to in writing, software
  25. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  26. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  27. * See the License for the specific language governing permissions and
  28. * limitations under the License.
  29. *
  30. * This file is part of Mbed TLS (https://tls.mbed.org)
  31. */
  32. #ifndef MBEDTLS_ECDH_H
  33. #define MBEDTLS_ECDH_H
  34. #include "ecp.h"
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38. /**
  39. * Defines the source of the imported EC key:
  40. * <ul><li>Our key.</li>
  41. * <li>The key of the peer.</li></ul>
  42. */
  43. typedef enum
  44. {
  45. MBEDTLS_ECDH_OURS,
  46. MBEDTLS_ECDH_THEIRS,
  47. } mbedtls_ecdh_side;
  48. /**
  49. * \brief The ECDH context structure.
  50. */
  51. typedef struct
  52. {
  53. mbedtls_ecp_group grp; /*!< The elliptic curve used. */
  54. mbedtls_mpi d; /*!< The private key. */
  55. mbedtls_ecp_point Q; /*!< The public key. */
  56. mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
  57. mbedtls_mpi z; /*!< The shared secret. */
  58. int point_format; /*!< The format of point export in TLS messages. */
  59. mbedtls_ecp_point Vi; /*!< The blinding value. */
  60. mbedtls_ecp_point Vf; /*!< The unblinding value. */
  61. mbedtls_mpi _d; /*!< The previous \p d. */
  62. }
  63. mbedtls_ecdh_context;
  64. /**
  65. * \brief This function generates an ECDH keypair on an elliptic
  66. * curve.
  67. *
  68. * This function performs the first of two core computations
  69. * implemented during the ECDH key exchange. The second core
  70. * computation is performed by mbedtls_ecdh_compute_shared().
  71. *
  72. * \param grp The ECP group.
  73. * \param d The destination MPI (private key).
  74. * \param Q The destination point (public key).
  75. * \param f_rng The RNG function.
  76. * \param p_rng The RNG parameter.
  77. *
  78. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
  79. * \c MBEDTLS_MPI_XXX error code on failure.
  80. *
  81. * \see ecp.h
  82. */
  83. int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
  84. int (*f_rng)(void *, unsigned char *, size_t),
  85. void *p_rng );
  86. /**
  87. * \brief This function computes the shared secret.
  88. *
  89. * This function performs the second of two core computations
  90. * implemented during the ECDH key exchange. The first core
  91. * computation is performed by mbedtls_ecdh_gen_public().
  92. *
  93. * \param grp The ECP group.
  94. * \param z The destination MPI (shared secret).
  95. * \param Q The public key from another party.
  96. * \param d Our secret exponent (private key).
  97. * \param f_rng The RNG function.
  98. * \param p_rng The RNG parameter.
  99. *
  100. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX or
  101. * \c MBEDTLS_MPI_XXX error code on failure.
  102. *
  103. * \see ecp.h
  104. *
  105. * \note If \p f_rng is not NULL, it is used to implement
  106. * countermeasures against potential elaborate timing
  107. * attacks. For more information, see mbedtls_ecp_mul().
  108. */
  109. int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
  110. const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
  111. int (*f_rng)(void *, unsigned char *, size_t),
  112. void *p_rng );
  113. /**
  114. * \brief This function initializes an ECDH context.
  115. *
  116. * \param ctx The ECDH context to initialize.
  117. */
  118. void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
  119. /**
  120. * \brief This function frees a context.
  121. *
  122. * \param ctx The context to free.
  123. */
  124. void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
  125. /**
  126. * \brief This function generates a public key and a TLS
  127. * ServerKeyExchange payload.
  128. *
  129. * This is the first function used by a TLS server for ECDHE
  130. * ciphersuites.
  131. *
  132. * \param ctx The ECDH context.
  133. * \param olen The number of characters written.
  134. * \param buf The destination buffer.
  135. * \param blen The length of the destination buffer.
  136. * \param f_rng The RNG function.
  137. * \param p_rng The RNG parameter.
  138. *
  139. * \note This function assumes that the ECP group (grp) of the
  140. * \p ctx context has already been properly set,
  141. * for example, using mbedtls_ecp_group_load().
  142. *
  143. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
  144. * on failure.
  145. *
  146. * \see ecp.h
  147. */
  148. int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
  149. unsigned char *buf, size_t blen,
  150. int (*f_rng)(void *, unsigned char *, size_t),
  151. void *p_rng );
  152. /**
  153. * \brief This function parses and processes a TLS ServerKeyExhange
  154. * payload.
  155. *
  156. * This is the first function used by a TLS client for ECDHE
  157. * ciphersuites.
  158. *
  159. * \param ctx The ECDH context.
  160. * \param buf The pointer to the start of the input buffer.
  161. * \param end The address for one Byte past the end of the buffer.
  162. *
  163. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
  164. * on failure.
  165. *
  166. * \see ecp.h
  167. */
  168. int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
  169. const unsigned char **buf, const unsigned char *end );
  170. /**
  171. * \brief This function sets up an ECDH context from an EC key.
  172. *
  173. * It is used by clients and servers in place of the
  174. * ServerKeyEchange for static ECDH, and imports ECDH
  175. * parameters from the EC key information of a certificate.
  176. *
  177. * \param ctx The ECDH context to set up.
  178. * \param key The EC key to use.
  179. * \param side Defines the source of the key:
  180. * <ul><li>1: Our key.</li>
  181. <li>0: The key of the peer.</li></ul>
  182. *
  183. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
  184. * on failure.
  185. *
  186. * \see ecp.h
  187. */
  188. int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
  189. mbedtls_ecdh_side side );
  190. /**
  191. * \brief This function generates a public key and a TLS
  192. * ClientKeyExchange payload.
  193. *
  194. * This is the second function used by a TLS client for ECDH(E)
  195. * ciphersuites.
  196. *
  197. * \param ctx The ECDH context.
  198. * \param olen The number of Bytes written.
  199. * \param buf The destination buffer.
  200. * \param blen The size of the destination buffer.
  201. * \param f_rng The RNG function.
  202. * \param p_rng The RNG parameter.
  203. *
  204. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
  205. * on failure.
  206. *
  207. * \see ecp.h
  208. */
  209. int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
  210. unsigned char *buf, size_t blen,
  211. int (*f_rng)(void *, unsigned char *, size_t),
  212. void *p_rng );
  213. /**
  214. * \brief This function parses and processes a TLS ClientKeyExchange
  215. * payload.
  216. *
  217. * This is the second function used by a TLS server for ECDH(E)
  218. * ciphersuites.
  219. *
  220. * \param ctx The ECDH context.
  221. * \param buf The start of the input buffer.
  222. * \param blen The length of the input buffer.
  223. *
  224. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
  225. * on failure.
  226. *
  227. * \see ecp.h
  228. */
  229. int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
  230. const unsigned char *buf, size_t blen );
  231. /**
  232. * \brief This function derives and exports the shared secret.
  233. *
  234. * This is the last function used by both TLS client
  235. * and servers.
  236. *
  237. * \param ctx The ECDH context.
  238. * \param olen The number of Bytes written.
  239. * \param buf The destination buffer.
  240. * \param blen The length of the destination buffer.
  241. * \param f_rng The RNG function.
  242. * \param p_rng The RNG parameter.
  243. *
  244. * \return \c 0 on success, or an \c MBEDTLS_ERR_ECP_XXX error code
  245. * on failure.
  246. *
  247. * \see ecp.h
  248. *
  249. * \note If \p f_rng is not NULL, it is used to implement
  250. * countermeasures against potential elaborate timing
  251. * attacks. For more information, see mbedtls_ecp_mul().
  252. */
  253. int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
  254. unsigned char *buf, size_t blen,
  255. int (*f_rng)(void *, unsigned char *, size_t),
  256. void *p_rng );
  257. #ifdef __cplusplus
  258. }
  259. #endif
  260. #endif /* ecdh.h */