srp.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313
  1. /* srp.h
  2. *
  3. * Copyright (C) 2006-2022 wolfSSL Inc.
  4. *
  5. * This file is part of wolfSSL.
  6. *
  7. * wolfSSL is free software; you can redistribute it and/or modify
  8. * it under the terms of the GNU General Public License as published by
  9. * the Free Software Foundation; either version 2 of the License, or
  10. * (at your option) any later version.
  11. *
  12. * wolfSSL is distributed in the hope that it will be useful,
  13. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15. * GNU General Public License for more details.
  16. *
  17. * You should have received a copy of the GNU General Public License
  18. * along with this program; if not, write to the Free Software
  19. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
  20. */
  21. /*!
  22. \file wolfssl/wolfcrypt/srp.h
  23. */
  24. #ifdef WOLFCRYPT_HAVE_SRP
  25. #ifndef WOLFCRYPT_SRP_H
  26. #define WOLFCRYPT_SRP_H
  27. #include <wolfssl/wolfcrypt/types.h>
  28. #include <wolfssl/wolfcrypt/sha.h>
  29. #include <wolfssl/wolfcrypt/sha256.h>
  30. #include <wolfssl/wolfcrypt/sha512.h>
  31. #include <wolfssl/wolfcrypt/integer.h>
  32. #ifdef __cplusplus
  33. extern "C" {
  34. #endif
  35. /* Select the largest available hash for the buffer size. */
  36. #if defined(WOLFSSL_SHA512)
  37. #define SRP_MAX_DIGEST_SIZE WC_SHA512_DIGEST_SIZE
  38. #elif defined(WOLFSSL_SHA384)
  39. #define SRP_MAX_DIGEST_SIZE WC_SHA384_DIGEST_SIZE
  40. #elif !defined(NO_SHA256)
  41. #define SRP_MAX_DIGEST_SIZE WC_SHA256_DIGEST_SIZE
  42. #elif !defined(NO_SHA)
  43. #define SRP_MAX_DIGEST_SIZE WC_SHA_DIGEST_SIZE
  44. #else
  45. #error "You have to have some kind of SHA hash if you want to use SRP."
  46. #endif
  47. /* Set the minimum number of bits acceptable in an SRP modulus */
  48. #define SRP_MODULUS_MIN_BITS 512
  49. /* Set the minimum number of bits acceptable for private keys (RFC 5054) */
  50. #define SRP_PRIVATE_KEY_MIN_BITS 256
  51. /* salt size for SRP password */
  52. #define SRP_SALT_SIZE 16
  53. /**
  54. * SRP side, client or server.
  55. */
  56. typedef enum {
  57. SRP_CLIENT_SIDE = 0,
  58. SRP_SERVER_SIDE = 1,
  59. } SrpSide;
  60. /**
  61. * SRP hash type, SHA[1|256|384|512].
  62. */
  63. typedef enum {
  64. SRP_TYPE_SHA = 1,
  65. SRP_TYPE_SHA256 = 2,
  66. SRP_TYPE_SHA384 = 3,
  67. SRP_TYPE_SHA512 = 4,
  68. } SrpType;
  69. /**
  70. * SRP hash struct.
  71. */
  72. typedef struct {
  73. byte type;
  74. union {
  75. #ifndef NO_SHA
  76. wc_Sha sha;
  77. #endif
  78. #ifndef NO_SHA256
  79. wc_Sha256 sha256;
  80. #endif
  81. #ifdef WOLFSSL_SHA384
  82. wc_Sha384 sha384;
  83. #endif
  84. #ifdef WOLFSSL_SHA512
  85. wc_Sha512 sha512;
  86. #endif
  87. } data;
  88. } SrpHash;
  89. typedef struct Srp {
  90. SrpSide side; /**< Client or Server, @see SrpSide. */
  91. SrpType type; /**< Hash type, @see SrpType. */
  92. byte* user; /**< Username, login. */
  93. word32 userSz; /**< Username length. */
  94. byte* salt; /**< Small salt. */
  95. word32 saltSz; /**< Salt length. */
  96. mp_int N; /**< Modulus. N = 2q+1, [q, N] are primes.*/
  97. mp_int g; /**< Generator. A generator modulo N. */
  98. byte k[SRP_MAX_DIGEST_SIZE]; /**< Multiplier parameter. k = H(N, g) */
  99. mp_int auth; /**< Client: x = H(salt + H(user:pswd)) */
  100. /**< Server: v = g ^ x % N */
  101. mp_int priv; /**< Private ephemeral value. */
  102. SrpHash client_proof; /**< Client proof. Sent to the Server. */
  103. SrpHash server_proof; /**< Server proof. Sent to the Client. */
  104. byte* key; /**< Session key. */
  105. word32 keySz; /**< Session key length. */
  106. int (*keyGenFunc_cb) (struct Srp* srp, byte* secret, word32 size);
  107. /**< Function responsible for generating the session key. */
  108. /**< It MUST use XMALLOC with type DYNAMIC_TYPE_SRP to allocate the */
  109. /**< key buffer for this structure and set keySz to the buffer size. */
  110. /**< The default function used by this implementation is a modified */
  111. /**< version of t_mgf1 that uses the proper hash function according */
  112. /**< to srp->type. */
  113. void* heap; /**< heap hint pointer */
  114. } Srp;
  115. /**
  116. * Initializes the Srp struct for usage.
  117. *
  118. * @param[out] srp the Srp structure to be initialized.
  119. * @param[in] type the hash type to be used.
  120. * @param[in] side the side of the communication.
  121. *
  122. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  123. */
  124. WOLFSSL_API int wc_SrpInit(Srp* srp, SrpType type, SrpSide side);
  125. WOLFSSL_API int wc_SrpInit_ex(Srp* srp, SrpType type, SrpSide side,
  126. void* heap, int devId);
  127. /**
  128. * Releases the Srp struct resources after usage.
  129. *
  130. * @param[in,out] srp the Srp structure to be terminated.
  131. */
  132. WOLFSSL_API void wc_SrpTerm(Srp* srp);
  133. /**
  134. * Sets the username.
  135. *
  136. * This function MUST be called after wc_SrpInit.
  137. *
  138. * @param[in,out] srp the Srp structure.
  139. * @param[in] username the buffer containing the username.
  140. * @param[in] size the username size in bytes
  141. *
  142. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  143. */
  144. WOLFSSL_API int wc_SrpSetUsername(Srp* srp, const byte* username, word32 size);
  145. /**
  146. * Sets the srp parameters based on the username.
  147. *
  148. * This function MUST be called after wc_SrpSetUsername.
  149. *
  150. * @param[in,out] srp the Srp structure.
  151. * @param[in] N the Modulus. N = 2q+1, [q, N] are primes.
  152. * @param[in] nSz the N size in bytes.
  153. * @param[in] g the Generator modulo N.
  154. * @param[in] gSz the g size in bytes
  155. * @param[in] salt a small random salt. Specific for each username.
  156. * @param[in] saltSz the salt size in bytes
  157. *
  158. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  159. */
  160. WOLFSSL_API int wc_SrpSetParams(Srp* srp, const byte* N, word32 nSz,
  161. const byte* g, word32 gSz,
  162. const byte* salt, word32 saltSz);
  163. /**
  164. * Sets the password.
  165. *
  166. * Setting the password does not persists the clear password data in the
  167. * srp structure. The client calculates x = H(salt + H(user:pswd)) and stores
  168. * it in the auth field.
  169. *
  170. * This function MUST be called after wc_SrpSetParams and is CLIENT SIDE ONLY.
  171. *
  172. * @param[in,out] srp the Srp structure.
  173. * @param[in] password the buffer containing the password.
  174. * @param[in] size the password size in bytes.
  175. *
  176. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  177. */
  178. WOLFSSL_API int wc_SrpSetPassword(Srp* srp, const byte* password, word32 size);
  179. /**
  180. * Sets the verifier.
  181. *
  182. * This function MUST be called after wc_SrpSetParams and is SERVER SIDE ONLY.
  183. *
  184. * @param[in,out] srp the Srp structure.
  185. * @param[in] verifier the buffer containing the verifier.
  186. * @param[in] size the verifier size in bytes.
  187. *
  188. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  189. */
  190. WOLFSSL_API int wc_SrpSetVerifier(Srp* srp, const byte* verifier, word32 size);
  191. /**
  192. * Gets the verifier.
  193. *
  194. * The client calculates the verifier with v = g ^ x % N.
  195. * This function MAY be called after wc_SrpSetPassword and is CLIENT SIDE ONLY.
  196. *
  197. * @param[in,out] srp the Srp structure.
  198. * @param[out] verifier the buffer to write the verifier.
  199. * @param[in,out] size the buffer size in bytes. Will be updated with the
  200. * verifier size.
  201. *
  202. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  203. */
  204. WOLFSSL_API int wc_SrpGetVerifier(Srp* srp, byte* verifier, word32* size);
  205. /**
  206. * Sets the private ephemeral value.
  207. *
  208. * The private ephemeral value is known as:
  209. * a at the client side. a = random()
  210. * b at the server side. b = random()
  211. * This function is handy for unit test cases or if the developer wants to use
  212. * an external random source to set the ephemeral value.
  213. * This function MAY be called before wc_SrpGetPublic.
  214. *
  215. * @param[in,out] srp the Srp structure.
  216. * @param[in] priv the ephemeral value.
  217. * @param[in] size the private size in bytes.
  218. *
  219. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  220. */
  221. WOLFSSL_API int wc_SrpSetPrivate(Srp* srp, const byte* priv, word32 size);
  222. /**
  223. * Gets the public ephemeral value.
  224. *
  225. * The public ephemeral value is known as:
  226. * A at the client side. A = g ^ a % N
  227. * B at the server side. B = (k * v + (g ^ b % N)) % N
  228. * This function MUST be called after wc_SrpSetPassword or wc_SrpSetVerifier.
  229. *
  230. * @param[in,out] srp the Srp structure.
  231. * @param[out] pub the buffer to write the public ephemeral value.
  232. * @param[in,out] size the the buffer size in bytes. Will be updated with
  233. * the ephemeral value size.
  234. *
  235. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  236. */
  237. WOLFSSL_API int wc_SrpGetPublic(Srp* srp, byte* pub, word32* size);
  238. /**
  239. * Computes the session key.
  240. *
  241. * The key can be accessed at srp->key after success.
  242. *
  243. * @param[in,out] srp the Srp structure.
  244. * @param[in] clientPubKey the client's public ephemeral value.
  245. * @param[in] clientPubKeySz the client's public ephemeral value size.
  246. * @param[in] serverPubKey the server's public ephemeral value.
  247. * @param[in] serverPubKeySz the server's public ephemeral value size.
  248. *
  249. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  250. */
  251. WOLFSSL_API int wc_SrpComputeKey(Srp* srp,
  252. byte* clientPubKey, word32 clientPubKeySz,
  253. byte* serverPubKey, word32 serverPubKeySz);
  254. /**
  255. * Gets the proof.
  256. *
  257. * This function MUST be called after wc_SrpComputeKey.
  258. *
  259. * @param[in,out] srp the Srp structure.
  260. * @param[out] proof the buffer to write the proof.
  261. * @param[in,out] size the buffer size in bytes. Will be updated with the
  262. * proof size.
  263. *
  264. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  265. */
  266. WOLFSSL_API int wc_SrpGetProof(Srp* srp, byte* proof, word32* size);
  267. /**
  268. * Verifies the peers proof.
  269. *
  270. * This function MUST be called before wc_SrpGetSessionKey.
  271. *
  272. * @param[in,out] srp the Srp structure.
  273. * @param[in] proof the peers proof.
  274. * @param[in] size the proof size in bytes.
  275. *
  276. * @return 0 on success, {@literal <} 0 on error. @see error-crypt.h
  277. */
  278. WOLFSSL_API int wc_SrpVerifyPeersProof(Srp* srp, byte* proof, word32 size);
  279. #ifdef __cplusplus
  280. } /* extern "C" */
  281. #endif
  282. #endif /* WOLFCRYPT_SRP_H */
  283. #endif /* WOLFCRYPT_HAVE_SRP */