ecjpake.h 8.4 KB

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