ecjpake.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277
  1. /**
  2. * \file ecjpake.h
  3. *
  4. * \brief Elliptic curve J-PAKE
  5. */
  6. /*
  7. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. *
  22. * This file is part of mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_ECJPAKE_H
  25. #define MBEDTLS_ECJPAKE_H
  26. /*
  27. * J-PAKE is a password-authenticated key exchange that allows deriving a
  28. * strong shared secret from a (potentially low entropy) pre-shared
  29. * passphrase, with forward secrecy and mutual authentication.
  30. * https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
  31. *
  32. * This file implements the Elliptic Curve variant of J-PAKE,
  33. * as defined in Chapter 7.4 of the Thread v1.0 Specification,
  34. * available to members of the Thread Group http://threadgroup.org/
  35. *
  36. * As the J-PAKE algorithm is inherently symmetric, so is our API.
  37. * Each party needs to send its first round message, in any order, to the
  38. * other party, then each sends its second round message, in any order.
  39. * The payloads are serialized in a way suitable for use in TLS, but could
  40. * also be use outside TLS.
  41. */
  42. #if !defined(MBEDTLS_CONFIG_FILE)
  43. #include "config.h"
  44. #else
  45. #include MBEDTLS_CONFIG_FILE
  46. #endif
  47. #include "ecp.h"
  48. #include "md.h"
  49. #ifdef __cplusplus
  50. extern "C" {
  51. #endif
  52. /**
  53. * Roles in the EC J-PAKE exchange
  54. */
  55. typedef enum {
  56. MBEDTLS_ECJPAKE_CLIENT = 0, /**< Client */
  57. MBEDTLS_ECJPAKE_SERVER, /**< Server */
  58. } mbedtls_ecjpake_role;
  59. #if !defined(MBEDTLS_ECJPAKE_ALT)
  60. /**
  61. * EC J-PAKE context structure.
  62. *
  63. * J-PAKE is a symmetric protocol, except for the identifiers used in
  64. * Zero-Knowledge Proofs, and the serialization of the second message
  65. * (KeyExchange) as defined by the Thread spec.
  66. *
  67. * In order to benefit from this symmetry, we choose a different naming
  68. * convetion from the Thread v1.0 spec. Correspondance is indicated in the
  69. * description as a pair C: client name, S: server name
  70. */
  71. typedef struct mbedtls_ecjpake_context
  72. {
  73. const mbedtls_md_info_t *md_info; /**< Hash to use */
  74. mbedtls_ecp_group grp; /**< Elliptic curve */
  75. mbedtls_ecjpake_role role; /**< Are we client or server? */
  76. int point_format; /**< Format for point export */
  77. mbedtls_ecp_point Xm1; /**< My public key 1 C: X1, S: X3 */
  78. mbedtls_ecp_point Xm2; /**< My public key 2 C: X2, S: X4 */
  79. mbedtls_ecp_point Xp1; /**< Peer public key 1 C: X3, S: X1 */
  80. mbedtls_ecp_point Xp2; /**< Peer public key 2 C: X4, S: X2 */
  81. mbedtls_ecp_point Xp; /**< Peer public key C: Xs, S: Xc */
  82. mbedtls_mpi xm1; /**< My private key 1 C: x1, S: x3 */
  83. mbedtls_mpi xm2; /**< My private key 2 C: x2, S: x4 */
  84. mbedtls_mpi s; /**< Pre-shared secret (passphrase) */
  85. } mbedtls_ecjpake_context;
  86. #else /* MBEDTLS_ECJPAKE_ALT */
  87. #include "ecjpake_alt.h"
  88. #endif /* MBEDTLS_ECJPAKE_ALT */
  89. /**
  90. * \brief Initialize an ECJPAKE context.
  91. *
  92. * \param ctx The ECJPAKE context to initialize.
  93. * This must not be \c NULL.
  94. */
  95. void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
  96. /**
  97. * \brief Set up an ECJPAKE context for use.
  98. *
  99. * \note Currently the only values for hash/curve allowed by the
  100. * standard are #MBEDTLS_MD_SHA256/#MBEDTLS_ECP_DP_SECP256R1.
  101. *
  102. * \param ctx The ECJPAKE context to set up. This must be initialized.
  103. * \param role The role of the caller. This must be either
  104. * #MBEDTLS_ECJPAKE_CLIENT or #MBEDTLS_ECJPAKE_SERVER.
  105. * \param hash The identifier of the hash function to use,
  106. * for example #MBEDTLS_MD_SHA256.
  107. * \param curve The identifier of the elliptic curve to use,
  108. * for example #MBEDTLS_ECP_DP_SECP256R1.
  109. * \param secret The pre-shared secret (passphrase). This must be
  110. * a readable buffer of length \p len Bytes. It need
  111. * only be valid for the duration of this call.
  112. * \param len The length of the pre-shared secret \p secret.
  113. *
  114. * \return \c 0 if successful.
  115. * \return A negative error code on failure.
  116. */
  117. int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
  118. mbedtls_ecjpake_role role,
  119. mbedtls_md_type_t hash,
  120. mbedtls_ecp_group_id curve,
  121. const unsigned char *secret,
  122. size_t len );
  123. /**
  124. * \brief Check if an ECJPAKE context is ready for use.
  125. *
  126. * \param ctx The ECJPAKE context to check. This must be
  127. * initialized.
  128. *
  129. * \return \c 0 if the context is ready for use.
  130. * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise.
  131. */
  132. int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
  133. /**
  134. * \brief Generate and write the first round message
  135. * (TLS: contents of the Client/ServerHello extension,
  136. * excluding extension type and length bytes).
  137. *
  138. * \param ctx The ECJPAKE context to use. This must be
  139. * initialized and set up.
  140. * \param buf The buffer to write the contents to. This must be a
  141. * writable buffer of length \p len Bytes.
  142. * \param len The length of \p buf in Bytes.
  143. * \param olen The address at which to store the total number
  144. * of Bytes written to \p buf. This must not be \c NULL.
  145. * \param f_rng The RNG function to use. This must not be \c NULL.
  146. * \param p_rng The RNG parameter to be passed to \p f_rng. This
  147. * may be \c NULL if \p f_rng doesn't use a context.
  148. *
  149. * \return \c 0 if successful.
  150. * \return A negative error code on failure.
  151. */
  152. int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
  153. unsigned char *buf, size_t len, size_t *olen,
  154. int (*f_rng)(void *, unsigned char *, size_t),
  155. void *p_rng );
  156. /**
  157. * \brief Read and process the first round message
  158. * (TLS: contents of the Client/ServerHello extension,
  159. * excluding extension type and length bytes).
  160. *
  161. * \param ctx The ECJPAKE context to use. This must be initialized
  162. * and set up.
  163. * \param buf The buffer holding the first round message. This must
  164. * be a readable buffer of length \p len Bytes.
  165. * \param len The length in Bytes of \p buf.
  166. *
  167. * \return \c 0 if successful.
  168. * \return A negative error code on failure.
  169. */
  170. int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
  171. const unsigned char *buf,
  172. size_t len );
  173. /**
  174. * \brief Generate and write the second round message
  175. * (TLS: contents of the Client/ServerKeyExchange).
  176. *
  177. * \param ctx The ECJPAKE context to use. This must be initialized,
  178. * set up, and already have performed round one.
  179. * \param buf The buffer to write the round two contents to.
  180. * This must be a writable buffer of length \p len Bytes.
  181. * \param len The size of \p buf in Bytes.
  182. * \param olen The address at which to store the total number of Bytes
  183. * written to \p buf. This must not be \c NULL.
  184. * \param f_rng The RNG function to use. This must not be \c NULL.
  185. * \param p_rng The RNG parameter to be passed to \p f_rng. This
  186. * may be \c NULL if \p f_rng doesn't use a context.
  187. *
  188. * \return \c 0 if successful.
  189. * \return A negative error code on failure.
  190. */
  191. int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
  192. unsigned char *buf, size_t len, size_t *olen,
  193. int (*f_rng)(void *, unsigned char *, size_t),
  194. void *p_rng );
  195. /**
  196. * \brief Read and process the second round message
  197. * (TLS: contents of the Client/ServerKeyExchange).
  198. *
  199. * \param ctx The ECJPAKE context to use. This must be initialized
  200. * and set up and already have performed round one.
  201. * \param buf The buffer holding the second round message. This must
  202. * be a readable buffer of length \p len Bytes.
  203. * \param len The length in Bytes of \p buf.
  204. *
  205. * \return \c 0 if successful.
  206. * \return A negative error code on failure.
  207. */
  208. int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
  209. const unsigned char *buf,
  210. size_t len );
  211. /**
  212. * \brief Derive the shared secret
  213. * (TLS: Pre-Master Secret).
  214. *
  215. * \param ctx The ECJPAKE context to use. This must be initialized,
  216. * set up and have performed both round one and two.
  217. * \param buf The buffer to write the derived secret to. This must
  218. * be a writable buffer of length \p len Bytes.
  219. * \param len The length of \p buf in Bytes.
  220. * \param olen The address at which to store the total number of Bytes
  221. * written to \p buf. This must not be \c NULL.
  222. * \param f_rng The RNG function to use. This must not be \c NULL.
  223. * \param p_rng The RNG parameter to be passed to \p f_rng. This
  224. * may be \c NULL if \p f_rng doesn't use a context.
  225. *
  226. * \return \c 0 if successful.
  227. * \return A negative error code on failure.
  228. */
  229. int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
  230. unsigned char *buf, size_t len, size_t *olen,
  231. int (*f_rng)(void *, unsigned char *, size_t),
  232. void *p_rng );
  233. /**
  234. * \brief This clears an ECJPAKE context and frees any
  235. * embedded data structure.
  236. *
  237. * \param ctx The ECJPAKE context to free. This may be \c NULL,
  238. * in which case this function does nothing. If it is not
  239. * \c NULL, it must point to an initialized ECJPAKE context.
  240. */
  241. void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
  242. #if defined(MBEDTLS_SELF_TEST)
  243. /**
  244. * \brief Checkup routine
  245. *
  246. * \return 0 if successful, or 1 if a test failed
  247. */
  248. int mbedtls_ecjpake_self_test( int verbose );
  249. #endif /* MBEDTLS_SELF_TEST */
  250. #ifdef __cplusplus
  251. }
  252. #endif
  253. #endif /* ecjpake.h */