ecdh.h 18 KB

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