ecdh.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440
  1. /**
  2. * \file ecdh.h
  3. *
  4. * \brief This file contains ECDH definitions and functions.
  5. *
  6. * The Elliptic Curve Diffie-Hellman (ECDH) protocol is an anonymous
  7. * key agreement protocol allowing two parties to establish a shared
  8. * secret over an insecure channel. Each party must have an
  9. * elliptic-curve public–private key pair.
  10. *
  11. * For more information, see <em>NIST SP 800-56A Rev. 2: Recommendation for
  12. * Pair-Wise Key Establishment Schemes Using Discrete Logarithm
  13. * Cryptography</em>.
  14. */
  15. /*
  16. * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  17. * SPDX-License-Identifier: Apache-2.0
  18. *
  19. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  20. * not use this file except in compliance with the License.
  21. * You may obtain a copy of the License at
  22. *
  23. * http://www.apache.org/licenses/LICENSE-2.0
  24. *
  25. * Unless required by applicable law or agreed to in writing, software
  26. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  27. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  28. * See the License for the specific language governing permissions and
  29. * limitations under the License.
  30. *
  31. * This file is part of Mbed TLS (https://tls.mbed.org)
  32. */
  33. #ifndef MBEDTLS_ECDH_H
  34. #define MBEDTLS_ECDH_H
  35. #if !defined(MBEDTLS_CONFIG_FILE)
  36. #include "config.h"
  37. #else
  38. #include MBEDTLS_CONFIG_FILE
  39. #endif
  40. #include "ecp.h"
  41. /*
  42. * Use a backward compatible ECDH context.
  43. *
  44. * This flag is always enabled for now and future versions might add a
  45. * configuration option that conditionally undefines this flag.
  46. * The configuration option in question may have a different name.
  47. *
  48. * Features undefining this flag, must have a warning in their description in
  49. * config.h stating that the feature breaks backward compatibility.
  50. */
  51. #define MBEDTLS_ECDH_LEGACY_CONTEXT
  52. #ifdef __cplusplus
  53. extern "C" {
  54. #endif
  55. /**
  56. * Defines the source of the imported EC key.
  57. */
  58. typedef enum
  59. {
  60. MBEDTLS_ECDH_OURS, /**< Our key. */
  61. MBEDTLS_ECDH_THEIRS, /**< The key of the peer. */
  62. } mbedtls_ecdh_side;
  63. #if !defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
  64. /**
  65. * Defines the ECDH implementation used.
  66. *
  67. * Later versions of the library may add new variants, therefore users should
  68. * not make any assumptions about them.
  69. */
  70. typedef enum
  71. {
  72. MBEDTLS_ECDH_VARIANT_NONE = 0, /*!< Implementation not defined. */
  73. MBEDTLS_ECDH_VARIANT_MBEDTLS_2_0,/*!< The default Mbed TLS implementation */
  74. } mbedtls_ecdh_variant;
  75. /**
  76. * The context used by the default ECDH implementation.
  77. *
  78. * Later versions might change the structure of this context, therefore users
  79. * should not make any assumptions about the structure of
  80. * mbedtls_ecdh_context_mbed.
  81. */
  82. typedef struct mbedtls_ecdh_context_mbed
  83. {
  84. mbedtls_ecp_group grp; /*!< The elliptic curve used. */
  85. mbedtls_mpi d; /*!< The private key. */
  86. mbedtls_ecp_point Q; /*!< The public key. */
  87. mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
  88. mbedtls_mpi z; /*!< The shared secret. */
  89. #if defined(MBEDTLS_ECP_RESTARTABLE)
  90. mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
  91. #endif
  92. } mbedtls_ecdh_context_mbed;
  93. #endif
  94. /**
  95. *
  96. * \warning Performing multiple operations concurrently on the same
  97. * ECDSA context is not supported; objects of this type
  98. * should not be shared between multiple threads.
  99. * \brief The ECDH context structure.
  100. */
  101. typedef struct mbedtls_ecdh_context
  102. {
  103. #if defined(MBEDTLS_ECDH_LEGACY_CONTEXT)
  104. mbedtls_ecp_group grp; /*!< The elliptic curve used. */
  105. mbedtls_mpi d; /*!< The private key. */
  106. mbedtls_ecp_point Q; /*!< The public key. */
  107. mbedtls_ecp_point Qp; /*!< The value of the public key of the peer. */
  108. mbedtls_mpi z; /*!< The shared secret. */
  109. int point_format; /*!< The format of point export in TLS messages. */
  110. mbedtls_ecp_point Vi; /*!< The blinding value. */
  111. mbedtls_ecp_point Vf; /*!< The unblinding value. */
  112. mbedtls_mpi _d; /*!< The previous \p d. */
  113. #if defined(MBEDTLS_ECP_RESTARTABLE)
  114. int restart_enabled; /*!< The flag for restartable mode. */
  115. mbedtls_ecp_restart_ctx rs; /*!< The restart context for EC computations. */
  116. #endif /* MBEDTLS_ECP_RESTARTABLE */
  117. #else
  118. uint8_t point_format; /*!< The format of point export in TLS messages
  119. as defined in RFC 4492. */
  120. mbedtls_ecp_group_id grp_id;/*!< The elliptic curve used. */
  121. mbedtls_ecdh_variant var; /*!< The ECDH implementation/structure used. */
  122. union
  123. {
  124. mbedtls_ecdh_context_mbed mbed_ecdh;
  125. } ctx; /*!< Implementation-specific context. The
  126. context in use is specified by the \c var
  127. field. */
  128. #if defined(MBEDTLS_ECP_RESTARTABLE)
  129. uint8_t restart_enabled; /*!< The flag for restartable mode. Functions of
  130. an alternative implementation not supporting
  131. restartable mode must return
  132. MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED error
  133. if this flag is set. */
  134. #endif /* MBEDTLS_ECP_RESTARTABLE */
  135. #endif /* MBEDTLS_ECDH_LEGACY_CONTEXT */
  136. }
  137. mbedtls_ecdh_context;
  138. /**
  139. * \brief This function generates an ECDH keypair on an elliptic
  140. * curve.
  141. *
  142. * This function performs the first of two core computations
  143. * implemented during the ECDH key exchange. The second core
  144. * computation is performed by mbedtls_ecdh_compute_shared().
  145. *
  146. * \see ecp.h
  147. *
  148. * \param grp The ECP group to use. This must be initialized and have
  149. * domain parameters loaded, for example through
  150. * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
  151. * \param d The destination MPI (private key).
  152. * This must be initialized.
  153. * \param Q The destination point (public key).
  154. * This must be initialized.
  155. * \param f_rng The RNG function to use. This must not be \c NULL.
  156. * \param p_rng The RNG context to be passed to \p f_rng. This may be
  157. * \c NULL in case \p f_rng doesn't need a context argument.
  158. *
  159. * \return \c 0 on success.
  160. * \return Another \c MBEDTLS_ERR_ECP_XXX or
  161. * \c MBEDTLS_MPI_XXX error code on failure.
  162. */
  163. int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
  164. int (*f_rng)(void *, unsigned char *, size_t),
  165. void *p_rng );
  166. /**
  167. * \brief This function computes the shared secret.
  168. *
  169. * This function performs the second of two core computations
  170. * implemented during the ECDH key exchange. The first core
  171. * computation is performed by mbedtls_ecdh_gen_public().
  172. *
  173. * \see ecp.h
  174. *
  175. * \note If \p f_rng is not NULL, it is used to implement
  176. * countermeasures against side-channel attacks.
  177. * For more information, see mbedtls_ecp_mul().
  178. *
  179. * \param grp The ECP group to use. This must be initialized and have
  180. * domain parameters loaded, for example through
  181. * mbedtls_ecp_load() or mbedtls_ecp_tls_read_group().
  182. * \param z The destination MPI (shared secret).
  183. * This must be initialized.
  184. * \param Q The public key from another party.
  185. * This must be initialized.
  186. * \param d Our secret exponent (private key).
  187. * This must be initialized.
  188. * \param f_rng The RNG function. This may be \c NULL if randomization
  189. * of intermediate results during the ECP computations is
  190. * not needed (discouraged). See the documentation of
  191. * mbedtls_ecp_mul() for more.
  192. * \param p_rng The RNG context to be passed to \p f_rng. This may be
  193. * \c NULL if \p f_rng is \c NULL or doesn't need a
  194. * context argument.
  195. *
  196. * \return \c 0 on success.
  197. * \return Another \c MBEDTLS_ERR_ECP_XXX or
  198. * \c MBEDTLS_MPI_XXX error code on failure.
  199. */
  200. int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
  201. const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
  202. int (*f_rng)(void *, unsigned char *, size_t),
  203. void *p_rng );
  204. /**
  205. * \brief This function initializes an ECDH context.
  206. *
  207. * \param ctx The ECDH context to initialize. This must not be \c NULL.
  208. */
  209. void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
  210. /**
  211. * \brief This function sets up the ECDH context with the information
  212. * given.
  213. *
  214. * This function should be called after mbedtls_ecdh_init() but
  215. * before mbedtls_ecdh_make_params(). There is no need to call
  216. * this function before mbedtls_ecdh_read_params().
  217. *
  218. * This is the first function used by a TLS server for ECDHE
  219. * ciphersuites.
  220. *
  221. * \param ctx The ECDH context to set up. This must be initialized.
  222. * \param grp_id The group id of the group to set up the context for.
  223. *
  224. * \return \c 0 on success.
  225. */
  226. int mbedtls_ecdh_setup( mbedtls_ecdh_context *ctx,
  227. mbedtls_ecp_group_id grp_id );
  228. /**
  229. * \brief This function frees a context.
  230. *
  231. * \param ctx The context to free. This may be \c NULL, in which
  232. * case this function does nothing. If it is not \c NULL,
  233. * it must point to an initialized ECDH context.
  234. */
  235. void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
  236. /**
  237. * \brief This function generates an EC key pair and exports its
  238. * in the format used in a TLS ServerKeyExchange handshake
  239. * message.
  240. *
  241. * This is the second function used by a TLS server for ECDHE
  242. * ciphersuites. (It is called after mbedtls_ecdh_setup().)
  243. *
  244. * \see ecp.h
  245. *
  246. * \param ctx The ECDH context to use. This must be initialized
  247. * and bound to a group, for example via mbedtls_ecdh_setup().
  248. * \param olen The address at which to store the number of Bytes written.
  249. * \param buf The destination buffer. This must be a writable buffer of
  250. * length \p blen Bytes.
  251. * \param blen The length of the destination buffer \p buf in Bytes.
  252. * \param f_rng The RNG function to use. This must not be \c NULL.
  253. * \param p_rng The RNG context to be passed to \p f_rng. This may be
  254. * \c NULL in case \p f_rng doesn't need a context argument.
  255. *
  256. * \return \c 0 on success.
  257. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  258. * operations was reached: see \c mbedtls_ecp_set_max_ops().
  259. * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  260. */
  261. int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
  262. unsigned char *buf, size_t blen,
  263. int (*f_rng)(void *, unsigned char *, size_t),
  264. void *p_rng );
  265. /**
  266. * \brief This function parses the ECDHE parameters in a
  267. * TLS ServerKeyExchange handshake message.
  268. *
  269. * \note In a TLS handshake, this is the how the client
  270. * sets up its ECDHE context from the server's public
  271. * ECDHE key material.
  272. *
  273. * \see ecp.h
  274. *
  275. * \param ctx The ECDHE context to use. This must be initialized.
  276. * \param buf On input, \c *buf must be the start of the input buffer.
  277. * On output, \c *buf is updated to point to the end of the
  278. * data that has been read. On success, this is the first byte
  279. * past the end of the ServerKeyExchange parameters.
  280. * On error, this is the point at which an error has been
  281. * detected, which is usually not useful except to debug
  282. * failures.
  283. * \param end The end of the input buffer.
  284. *
  285. * \return \c 0 on success.
  286. * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  287. *
  288. */
  289. int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
  290. const unsigned char **buf,
  291. const unsigned char *end );
  292. /**
  293. * \brief This function sets up an ECDH context from an EC key.
  294. *
  295. * It is used by clients and servers in place of the
  296. * ServerKeyEchange for static ECDH, and imports ECDH
  297. * parameters from the EC key information of a certificate.
  298. *
  299. * \see ecp.h
  300. *
  301. * \param ctx The ECDH context to set up. This must be initialized.
  302. * \param key The EC key to use. This must be initialized.
  303. * \param side Defines the source of the key. Possible values are:
  304. * - #MBEDTLS_ECDH_OURS: The key is ours.
  305. * - #MBEDTLS_ECDH_THEIRS: The key is that of the peer.
  306. *
  307. * \return \c 0 on success.
  308. * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  309. *
  310. */
  311. int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx,
  312. const mbedtls_ecp_keypair *key,
  313. mbedtls_ecdh_side side );
  314. /**
  315. * \brief This function generates a public key and exports it
  316. * as a TLS ClientKeyExchange payload.
  317. *
  318. * This is the second function used by a TLS client for ECDH(E)
  319. * ciphersuites.
  320. *
  321. * \see ecp.h
  322. *
  323. * \param ctx The ECDH context to use. This must be initialized
  324. * and bound to a group, the latter usually by
  325. * mbedtls_ecdh_read_params().
  326. * \param olen The address at which to store the number of Bytes written.
  327. * This must not be \c NULL.
  328. * \param buf The destination buffer. This must be a writable buffer
  329. * of length \p blen Bytes.
  330. * \param blen The size of the destination buffer \p buf in Bytes.
  331. * \param f_rng The RNG function to use. This must not be \c NULL.
  332. * \param p_rng The RNG context to be passed to \p f_rng. This may be
  333. * \c NULL in case \p f_rng doesn't need a context argument.
  334. *
  335. * \return \c 0 on success.
  336. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  337. * operations was reached: see \c mbedtls_ecp_set_max_ops().
  338. * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  339. */
  340. int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
  341. unsigned char *buf, size_t blen,
  342. int (*f_rng)(void *, unsigned char *, size_t),
  343. void *p_rng );
  344. /**
  345. * \brief This function parses and processes the ECDHE payload of a
  346. * TLS ClientKeyExchange message.
  347. *
  348. * This is the third function used by a TLS server for ECDH(E)
  349. * ciphersuites. (It is called after mbedtls_ecdh_setup() and
  350. * mbedtls_ecdh_make_params().)
  351. *
  352. * \see ecp.h
  353. *
  354. * \param ctx The ECDH context to use. This must be initialized
  355. * and bound to a group, for example via mbedtls_ecdh_setup().
  356. * \param buf The pointer to the ClientKeyExchange payload. This must
  357. * be a readable buffer of length \p blen Bytes.
  358. * \param blen The length of the input buffer \p buf in Bytes.
  359. *
  360. * \return \c 0 on success.
  361. * \return An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  362. */
  363. int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
  364. const unsigned char *buf, size_t blen );
  365. /**
  366. * \brief This function derives and exports the shared secret.
  367. *
  368. * This is the last function used by both TLS client
  369. * and servers.
  370. *
  371. * \note If \p f_rng is not NULL, it is used to implement
  372. * countermeasures against side-channel attacks.
  373. * For more information, see mbedtls_ecp_mul().
  374. *
  375. * \see ecp.h
  376. * \param ctx The ECDH context to use. This must be initialized
  377. * and have its own private key generated and the peer's
  378. * public key imported.
  379. * \param olen The address at which to store the total number of
  380. * Bytes written on success. This must not be \c NULL.
  381. * \param buf The buffer to write the generated shared key to. This
  382. * must be a writable buffer of size \p blen Bytes.
  383. * \param blen The length of the destination buffer \p buf in Bytes.
  384. * \param f_rng The RNG function, for blinding purposes. This may
  385. * b \c NULL if blinding isn't needed.
  386. * \param p_rng The RNG context. This may be \c NULL if \p f_rng
  387. * doesn't need a context argument.
  388. *
  389. * \return \c 0 on success.
  390. * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  391. * operations was reached: see \c mbedtls_ecp_set_max_ops().
  392. * \return Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  393. */
  394. int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
  395. unsigned char *buf, size_t blen,
  396. int (*f_rng)(void *, unsigned char *, size_t),
  397. void *p_rng );
  398. #if defined(MBEDTLS_ECP_RESTARTABLE)
  399. /**
  400. * \brief This function enables restartable EC computations for this
  401. * context. (Default: disabled.)
  402. *
  403. * \see \c mbedtls_ecp_set_max_ops()
  404. *
  405. * \note It is not possible to safely disable restartable
  406. * computations once enabled, except by free-ing the context,
  407. * which cancels possible in-progress operations.
  408. *
  409. * \param ctx The ECDH context to use. This must be initialized.
  410. */
  411. void mbedtls_ecdh_enable_restart( mbedtls_ecdh_context *ctx );
  412. #endif /* MBEDTLS_ECP_RESTARTABLE */
  413. #ifdef __cplusplus
  414. }
  415. #endif
  416. #endif /* ecdh.h */