ecjpake.h 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  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. #include "ecp.h"
  43. #include "md.h"
  44. #if !defined(MBEDTLS_ECJPAKE_ALT)
  45. #ifdef __cplusplus
  46. extern "C" {
  47. #endif
  48. /**
  49. * Roles in the EC J-PAKE exchange
  50. */
  51. typedef enum {
  52. MBEDTLS_ECJPAKE_CLIENT = 0, /**< Client */
  53. MBEDTLS_ECJPAKE_SERVER, /**< Server */
  54. } mbedtls_ecjpake_role;
  55. /**
  56. * EC J-PAKE context structure.
  57. *
  58. * J-PAKE is a symmetric protocol, except for the identifiers used in
  59. * Zero-Knowledge Proofs, and the serialization of the second message
  60. * (KeyExchange) as defined by the Thread spec.
  61. *
  62. * In order to benefit from this symmetry, we choose a different naming
  63. * convetion from the Thread v1.0 spec. Correspondance is indicated in the
  64. * description as a pair C: client name, S: server name
  65. */
  66. typedef struct
  67. {
  68. const mbedtls_md_info_t *md_info; /**< Hash to use */
  69. mbedtls_ecp_group grp; /**< Elliptic curve */
  70. mbedtls_ecjpake_role role; /**< Are we client or server? */
  71. int point_format; /**< Format for point export */
  72. mbedtls_ecp_point Xm1; /**< My public key 1 C: X1, S: X3 */
  73. mbedtls_ecp_point Xm2; /**< My public key 2 C: X2, S: X4 */
  74. mbedtls_ecp_point Xp1; /**< Peer public key 1 C: X3, S: X1 */
  75. mbedtls_ecp_point Xp2; /**< Peer public key 2 C: X4, S: X2 */
  76. mbedtls_ecp_point Xp; /**< Peer public key C: Xs, S: Xc */
  77. mbedtls_mpi xm1; /**< My private key 1 C: x1, S: x3 */
  78. mbedtls_mpi xm2; /**< My private key 2 C: x2, S: x4 */
  79. mbedtls_mpi s; /**< Pre-shared secret (passphrase) */
  80. } mbedtls_ecjpake_context;
  81. /**
  82. * \brief Initialize a context
  83. * (just makes it ready for setup() or free()).
  84. *
  85. * \param ctx context to initialize
  86. */
  87. void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
  88. /**
  89. * \brief Set up a context for use
  90. *
  91. * \note Currently the only values for hash/curve allowed by the
  92. * standard are MBEDTLS_MD_SHA256/MBEDTLS_ECP_DP_SECP256R1.
  93. *
  94. * \param ctx context to set up
  95. * \param role Our role: client or server
  96. * \param hash hash function to use (MBEDTLS_MD_XXX)
  97. * \param curve elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
  98. * \param secret pre-shared secret (passphrase)
  99. * \param len length of the shared secret
  100. *
  101. * \return 0 if successfull,
  102. * a negative error code otherwise
  103. */
  104. int mbedtls_ecjpake_setup( mbedtls_ecjpake_context *ctx,
  105. mbedtls_ecjpake_role role,
  106. mbedtls_md_type_t hash,
  107. mbedtls_ecp_group_id curve,
  108. const unsigned char *secret,
  109. size_t len );
  110. /**
  111. * \brief Check if a context is ready for use
  112. *
  113. * \param ctx Context to check
  114. *
  115. * \return 0 if the context is ready for use,
  116. * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise
  117. */
  118. int mbedtls_ecjpake_check( const mbedtls_ecjpake_context *ctx );
  119. /**
  120. * \brief Generate and write the first round message
  121. * (TLS: contents of the Client/ServerHello extension,
  122. * excluding extension type and length bytes)
  123. *
  124. * \param ctx Context to use
  125. * \param buf Buffer to write the contents to
  126. * \param len Buffer size
  127. * \param olen Will be updated with the number of bytes written
  128. * \param f_rng RNG function
  129. * \param p_rng RNG parameter
  130. *
  131. * \return 0 if successfull,
  132. * a negative error code otherwise
  133. */
  134. int mbedtls_ecjpake_write_round_one( mbedtls_ecjpake_context *ctx,
  135. unsigned char *buf, size_t len, size_t *olen,
  136. int (*f_rng)(void *, unsigned char *, size_t),
  137. void *p_rng );
  138. /**
  139. * \brief Read and process the first round message
  140. * (TLS: contents of the Client/ServerHello extension,
  141. * excluding extension type and length bytes)
  142. *
  143. * \param ctx Context to use
  144. * \param buf Pointer to extension contents
  145. * \param len Extension length
  146. *
  147. * \return 0 if successfull,
  148. * a negative error code otherwise
  149. */
  150. int mbedtls_ecjpake_read_round_one( mbedtls_ecjpake_context *ctx,
  151. const unsigned char *buf,
  152. size_t len );
  153. /**
  154. * \brief Generate and write the second round message
  155. * (TLS: contents of the Client/ServerKeyExchange)
  156. *
  157. * \param ctx Context to use
  158. * \param buf Buffer to write the contents to
  159. * \param len Buffer size
  160. * \param olen Will be updated with the number of bytes written
  161. * \param f_rng RNG function
  162. * \param p_rng RNG parameter
  163. *
  164. * \return 0 if successfull,
  165. * a negative error code otherwise
  166. */
  167. int mbedtls_ecjpake_write_round_two( mbedtls_ecjpake_context *ctx,
  168. unsigned char *buf, size_t len, size_t *olen,
  169. int (*f_rng)(void *, unsigned char *, size_t),
  170. void *p_rng );
  171. /**
  172. * \brief Read and process the second round message
  173. * (TLS: contents of the Client/ServerKeyExchange)
  174. *
  175. * \param ctx Context to use
  176. * \param buf Pointer to the message
  177. * \param len Message length
  178. *
  179. * \return 0 if successfull,
  180. * a negative error code otherwise
  181. */
  182. int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
  183. const unsigned char *buf,
  184. size_t len );
  185. /**
  186. * \brief Derive the shared secret
  187. * (TLS: Pre-Master Secret)
  188. *
  189. * \param ctx Context to use
  190. * \param buf Buffer to write the contents to
  191. * \param len Buffer size
  192. * \param olen Will be updated with the number of bytes written
  193. * \param f_rng RNG function
  194. * \param p_rng RNG parameter
  195. *
  196. * \return 0 if successfull,
  197. * a negative error code otherwise
  198. */
  199. int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
  200. unsigned char *buf, size_t len, size_t *olen,
  201. int (*f_rng)(void *, unsigned char *, size_t),
  202. void *p_rng );
  203. /**
  204. * \brief Free a context's content
  205. *
  206. * \param ctx context to free
  207. */
  208. void mbedtls_ecjpake_free( mbedtls_ecjpake_context *ctx );
  209. #ifdef __cplusplus
  210. }
  211. #endif
  212. #else /* MBEDTLS_ECJPAKE_ALT */
  213. #include "ecjpake_alt.h"
  214. #endif /* MBEDTLS_ECJPAKE_ALT */
  215. #if defined(MBEDTLS_SELF_TEST)
  216. #ifdef __cplusplus
  217. extern "C" {
  218. #endif
  219. /**
  220. * \brief Checkup routine
  221. *
  222. * \return 0 if successful, or 1 if a test failed
  223. */
  224. int mbedtls_ecjpake_self_test( int verbose );
  225. #ifdef __cplusplus
  226. }
  227. #endif
  228. #endif /* MBEDTLS_SELF_TEST */
  229. #endif /* ecjpake.h */