ecdh.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214
  1. /**
  2. * \file ecdh.h
  3. *
  4. * \brief Elliptic curve Diffie-Hellman
  5. *
  6. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  7. * SPDX-License-Identifier: Apache-2.0
  8. *
  9. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  10. * not use this file except in compliance with the License.
  11. * You may obtain a copy of the License at
  12. *
  13. * http://www.apache.org/licenses/LICENSE-2.0
  14. *
  15. * Unless required by applicable law or agreed to in writing, software
  16. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  17. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18. * See the License for the specific language governing permissions and
  19. * limitations under the License.
  20. *
  21. * This file is part of mbed TLS (https://tls.mbed.org)
  22. */
  23. #ifndef MBEDTLS_ECDH_H
  24. #define MBEDTLS_ECDH_H
  25. #include "ecp.h"
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29. /**
  30. * When importing from an EC key, select if it is our key or the peer's key
  31. */
  32. typedef enum
  33. {
  34. MBEDTLS_ECDH_OURS,
  35. MBEDTLS_ECDH_THEIRS,
  36. } mbedtls_ecdh_side;
  37. /**
  38. * \brief ECDH context structure
  39. */
  40. typedef struct
  41. {
  42. mbedtls_ecp_group grp; /*!< elliptic curve used */
  43. mbedtls_mpi d; /*!< our secret value (private key) */
  44. mbedtls_ecp_point Q; /*!< our public value (public key) */
  45. mbedtls_ecp_point Qp; /*!< peer's public value (public key) */
  46. mbedtls_mpi z; /*!< shared secret */
  47. int point_format; /*!< format for point export in TLS messages */
  48. mbedtls_ecp_point Vi; /*!< blinding value (for later) */
  49. mbedtls_ecp_point Vf; /*!< un-blinding value (for later) */
  50. mbedtls_mpi _d; /*!< previous d (for later) */
  51. }
  52. mbedtls_ecdh_context;
  53. /**
  54. * \brief Generate a public key.
  55. * Raw function that only does the core computation.
  56. *
  57. * \param grp ECP group
  58. * \param d Destination MPI (secret exponent, aka private key)
  59. * \param Q Destination point (public key)
  60. * \param f_rng RNG function
  61. * \param p_rng RNG parameter
  62. *
  63. * \return 0 if successful,
  64. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  65. */
  66. int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
  67. int (*f_rng)(void *, unsigned char *, size_t),
  68. void *p_rng );
  69. /**
  70. * \brief Compute shared secret
  71. * Raw function that only does the core computation.
  72. *
  73. * \param grp ECP group
  74. * \param z Destination MPI (shared secret)
  75. * \param Q Public key from other party
  76. * \param d Our secret exponent (private key)
  77. * \param f_rng RNG function (see notes)
  78. * \param p_rng RNG parameter
  79. *
  80. * \return 0 if successful,
  81. * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code
  82. *
  83. * \note If f_rng is not NULL, it is used to implement
  84. * countermeasures against potential elaborate timing
  85. * attacks, see \c mbedtls_ecp_mul() for details.
  86. */
  87. int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
  88. const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
  89. int (*f_rng)(void *, unsigned char *, size_t),
  90. void *p_rng );
  91. /**
  92. * \brief Initialize context
  93. *
  94. * \param ctx Context to initialize
  95. */
  96. void mbedtls_ecdh_init( mbedtls_ecdh_context *ctx );
  97. /**
  98. * \brief Free context
  99. *
  100. * \param ctx Context to free
  101. */
  102. void mbedtls_ecdh_free( mbedtls_ecdh_context *ctx );
  103. /**
  104. * \brief Generate a public key and a TLS ServerKeyExchange payload.
  105. * (First function used by a TLS server for ECDHE.)
  106. *
  107. * \param ctx ECDH context
  108. * \param olen number of chars written
  109. * \param buf destination buffer
  110. * \param blen length of buffer
  111. * \param f_rng RNG function
  112. * \param p_rng RNG parameter
  113. *
  114. * \note This function assumes that ctx->grp has already been
  115. * properly set (for example using mbedtls_ecp_group_load).
  116. *
  117. * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
  118. */
  119. int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
  120. unsigned char *buf, size_t blen,
  121. int (*f_rng)(void *, unsigned char *, size_t),
  122. void *p_rng );
  123. /**
  124. * \brief Parse and procress a TLS ServerKeyExhange payload.
  125. * (First function used by a TLS client for ECDHE.)
  126. *
  127. * \param ctx ECDH context
  128. * \param buf pointer to start of input buffer
  129. * \param end one past end of buffer
  130. *
  131. * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
  132. */
  133. int mbedtls_ecdh_read_params( mbedtls_ecdh_context *ctx,
  134. const unsigned char **buf, const unsigned char *end );
  135. /**
  136. * \brief Setup an ECDH context from an EC key.
  137. * (Used by clients and servers in place of the
  138. * ServerKeyEchange for static ECDH: import ECDH parameters
  139. * from a certificate's EC key information.)
  140. *
  141. * \param ctx ECDH constext to set
  142. * \param key EC key to use
  143. * \param side Is it our key (1) or the peer's key (0) ?
  144. *
  145. * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
  146. */
  147. int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
  148. mbedtls_ecdh_side side );
  149. /**
  150. * \brief Generate a public key and a TLS ClientKeyExchange payload.
  151. * (Second function used by a TLS client for ECDH(E).)
  152. *
  153. * \param ctx ECDH context
  154. * \param olen number of bytes actually written
  155. * \param buf destination buffer
  156. * \param blen size of destination buffer
  157. * \param f_rng RNG function
  158. * \param p_rng RNG parameter
  159. *
  160. * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
  161. */
  162. int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
  163. unsigned char *buf, size_t blen,
  164. int (*f_rng)(void *, unsigned char *, size_t),
  165. void *p_rng );
  166. /**
  167. * \brief Parse and process a TLS ClientKeyExchange payload.
  168. * (Second function used by a TLS server for ECDH(E).)
  169. *
  170. * \param ctx ECDH context
  171. * \param buf start of input buffer
  172. * \param blen length of input buffer
  173. *
  174. * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
  175. */
  176. int mbedtls_ecdh_read_public( mbedtls_ecdh_context *ctx,
  177. const unsigned char *buf, size_t blen );
  178. /**
  179. * \brief Derive and export the shared secret.
  180. * (Last function used by both TLS client en servers.)
  181. *
  182. * \param ctx ECDH context
  183. * \param olen number of bytes written
  184. * \param buf destination buffer
  185. * \param blen buffer length
  186. * \param f_rng RNG function, see notes for \c mbedtls_ecdh_compute_shared()
  187. * \param p_rng RNG parameter
  188. *
  189. * \return 0 if successful, or an MBEDTLS_ERR_ECP_XXX error code
  190. */
  191. int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
  192. unsigned char *buf, size_t blen,
  193. int (*f_rng)(void *, unsigned char *, size_t),
  194. void *p_rng );
  195. #ifdef __cplusplus
  196. }
  197. #endif
  198. #endif /* ecdh.h */