dh.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400
  1. /*!
  2. \ingroup Diffie-Hellman
  3. \brief This function initializes a Diffie-Hellman key for use in
  4. negotiating a secure secret key with the Diffie-Hellman exchange protocol.
  5. \return none No returns.
  6. \param key pointer to the DhKey structure to initialize for use with
  7. secure key exchanges
  8. _Example_
  9. \code
  10. DhKey key;
  11. wc_InitDhKey(&key); // initialize DH key
  12. \endcode
  13. \sa wc_FreeDhKey
  14. \sa wc_DhGenerateKeyPair
  15. */
  16. int wc_InitDhKey(DhKey* key);
  17. /*!
  18. \ingroup Diffie-Hellman
  19. \brief This function frees a Diffie-Hellman key after it has been used to
  20. negotiate a secure secret key with the Diffie-Hellman exchange protocol.
  21. \return none No returns.
  22. \param key pointer to the DhKey structure to free
  23. _Example_
  24. \code
  25. DhKey key;
  26. // initialize key, perform key exchange
  27. wc_FreeDhKey(&key); // free DH key to avoid memory leaks
  28. \endcode
  29. \sa wc_InitDhKey
  30. */
  31. void wc_FreeDhKey(DhKey* key);
  32. /*!
  33. \ingroup Diffie-Hellman
  34. \brief This function generates a public/private key pair based on the
  35. Diffie-Hellman public parameters, storing the private key in priv and the
  36. public key in pub. It takes an initialized Diffie-Hellman key and an
  37. initialized rng structure.
  38. \return BAD_FUNC_ARG Returned if there is an error parsing one of the
  39. inputs to this function
  40. \return RNG_FAILURE_E Returned if there is an error generating a random
  41. number using rng
  42. \return MP_INIT_E May be returned if there is an error in the math library
  43. while generating the public key
  44. \return MP_READ_E May be returned if there is an error in the math library
  45. while generating the public key
  46. \return MP_EXPTMOD_E May be returned if there is an error in the math
  47. library while generating the public key
  48. \return MP_TO_E May be returned if there is an error in the math library
  49. while generating the public key
  50. \param key pointer to the DhKey structure from which to generate
  51. the key pair
  52. \param rng pointer to an initialized random number generator (rng) with
  53. which to generate the keys
  54. \param priv pointer to a buffer in which to store the private key
  55. \param privSz will store the size of the private key written to priv
  56. \param pub pointer to a buffer in which to store the public key
  57. \param pubSz will store the size of the private key written to pub
  58. _Example_
  59. \code
  60. DhKey key;
  61. int ret;
  62. byte priv[256];
  63. byte pub[256];
  64. word32 privSz, pubSz;
  65. wc_InitDhKey(&key); // initialize key
  66. // Set DH parameters using wc_DhSetKey or wc_DhKeyDecode
  67. WC_RNG rng;
  68. wc_InitRng(&rng); // initialize rng
  69. ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz);
  70. \endcode
  71. \sa wc_InitDhKey
  72. \sa wc_DhSetKey
  73. \sa wc_DhKeyDecode
  74. */
  75. int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv,
  76. word32* privSz, byte* pub, word32* pubSz);
  77. /*!
  78. \ingroup Diffie-Hellman
  79. \brief This function generates an agreed upon secret key based on a local
  80. private key and a received public key. If completed on both sides of an
  81. exchange, this function generates an agreed upon secret key for symmetric
  82. communication. On successfully generating a shared secret key, the size of
  83. the secret key written will be stored in agreeSz.
  84. \return 0 Returned on successfully generating an agreed upon secret key
  85. \return MP_INIT_E May be returned if there is an error while generating
  86. the shared secret key
  87. \return MP_READ_E May be returned if there is an error while generating
  88. the shared secret key
  89. \return MP_EXPTMOD_E May be returned if there is an error while generating
  90. the shared secret key
  91. \return MP_TO_E May be returned if there is an error while generating the
  92. shared secret key
  93. \param key pointer to the DhKey structure to use to compute the shared key
  94. \param agree pointer to the buffer in which to store the secret key
  95. \param agreeSz will hold the size of the secret key after
  96. successful generation
  97. \param priv pointer to the buffer containing the local secret key
  98. \param privSz size of the local secret key
  99. \param otherPub pointer to a buffer containing the received public key
  100. \param pubSz size of the received public key
  101. _Example_
  102. \code
  103. DhKey key;
  104. int ret;
  105. byte priv[256];
  106. byte agree[256];
  107. word32 agreeSz;
  108. // initialize key, set key prime and base
  109. // wc_DhGenerateKeyPair -- store private key in priv
  110. byte pub[] = { // initialized with the received public key };
  111. ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub,
  112. sizeof(pub));
  113. if ( ret != 0 ) {
  114. // error generating shared key
  115. }
  116. \endcode
  117. \sa wc_DhGenerateKeyPair
  118. */
  119. int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
  120. const byte* priv, word32 privSz, const byte* otherPub,
  121. word32 pubSz);
  122. /*!
  123. \ingroup Diffie-Hellman
  124. \brief This function decodes a Diffie-Hellman key from the given input
  125. buffer containing the key in DER format. It stores the result in the
  126. DhKey structure.
  127. \return 0 Returned on successfully decoding the input key
  128. \return ASN_PARSE_E Returned if there is an error parsing the sequence
  129. of the input
  130. \return ASN_DH_KEY_E Returned if there is an error reading the private
  131. key parameters from the parsed input
  132. \param input pointer to the buffer containing the DER formatted
  133. Diffie-Hellman key
  134. \param inOutIdx pointer to an integer in which to store the index parsed
  135. to while decoding the key
  136. \param key pointer to the DhKey structure to initialize with the input key
  137. \param inSz length of the input buffer. Gives the max length that may
  138. be read
  139. _Example_
  140. \code
  141. DhKey key;
  142. word32 idx = 0;
  143. byte keyBuff[1024];
  144. // initialize with DER formatted key
  145. wc_DhKeyInit(&key);
  146. ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff));
  147. if ( ret != 0 ) {
  148. // error decoding key
  149. }
  150. \endcode
  151. \sa wc_DhSetKey
  152. */
  153. int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
  154. word32);
  155. /*!
  156. \ingroup Diffie-Hellman
  157. \brief This function sets the key for a DhKey structure using the input
  158. private key parameters. Unlike wc_DhKeyDecode, this function does not
  159. require that the input key be formatted in DER format, and instead simply
  160. accepts the parsed input parameters p (prime) and g (base).
  161. \return 0 Returned on successfully setting the key
  162. \return BAD_FUNC_ARG Returned if any of the input parameters
  163. evaluate to NULL
  164. \return MP_INIT_E Returned if there is an error initializing the key
  165. parameters for storage
  166. \return ASN_DH_KEY_E Returned if there is an error reading in the
  167. DH key parameters p and g
  168. \param key pointer to the DhKey structure on which to set the key
  169. \param p pointer to the buffer containing the prime for use with the key
  170. \param pSz length of the input prime
  171. \param g pointer to the buffer containing the base for use with the key
  172. \param gSz length of the input base
  173. _Example_
  174. \code
  175. DhKey key;
  176. byte p[] = { // initialize with prime };
  177. byte g[] = { // initialize with base };
  178. wc_DhKeyInit(&key);
  179. ret = wc_DhSetKey(key, p, sizeof(p), g, sizeof(g));
  180. if ( ret != 0 ) {
  181. // error setting key
  182. }
  183. \endcode
  184. \sa wc_DhKeyDecode
  185. */
  186. int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g,
  187. word32 gSz);
  188. /*!
  189. \ingroup Diffie-Hellman
  190. \brief This function loads the Diffie-Hellman parameters, p (prime)
  191. and g (base) out of the given input buffer, DER formatted.
  192. \return 0 Returned on successfully extracting the DH parameters
  193. \return ASN_PARSE_E Returned if an error occurs while parsing the DER
  194. formatted DH certificate
  195. \return BUFFER_E Returned if there is inadequate space in p or g to
  196. store the parsed parameters
  197. \param input pointer to a buffer containing a DER formatted
  198. Diffie-Hellman certificate to parse
  199. \param inSz size of the input buffer
  200. \param p pointer to a buffer in which to store the parsed prime
  201. \param pInOutSz pointer to a word32 object containing the available
  202. size in the p buffer. Will be overwritten with the number of bytes
  203. written to the buffer after completing the function call
  204. \param g pointer to a buffer in which to store the parsed base
  205. \param gInOutSz pointer to a word32 object containing the available size
  206. in the g buffer. Will be overwritten with the number of bytes written to
  207. the buffer after completing the function call
  208. _Example_
  209. \code
  210. byte dhCert[] = { initialize with DER formatted certificate };
  211. byte p[MAX_DH_SIZE];
  212. byte g[MAX_DH_SIZE];
  213. word32 pSz = MAX_DH_SIZE;
  214. word32 gSz = MAX_DH_SIZE;
  215. ret = wc_DhParamsLoad(dhCert, sizeof(dhCert), p, &pSz, g, &gSz);
  216. if ( ret != 0 ) {
  217. // error parsing inputs
  218. }
  219. \endcode
  220. \sa wc_DhSetKey
  221. \sa wc_DhKeyDecode
  222. */
  223. int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p,
  224. word32* pInOutSz, byte* g, word32* gInOutSz);
  225. /*!
  226. \ingroup Diffie-Hellman
  227. \brief This function returns ... and requires that HAVE_FFDHE_2048 be
  228. defined.
  229. \sa wc_Dh_ffdhe3072_Get
  230. \sa wc_Dh_ffdhe4096_Get
  231. \sa wc_Dh_ffdhe6144_Get
  232. \sa wc_Dh_ffdhe8192_Get
  233. */
  234. const DhParams* wc_Dh_ffdhe2048_Get(void);
  235. /*!
  236. \ingroup Diffie-Hellman
  237. \brief This function returns ... and requires that HAVE_FFDHE_3072 be
  238. defined.
  239. \sa wc_Dh_ffdhe2048_Get
  240. \sa wc_Dh_ffdhe4096_Get
  241. \sa wc_Dh_ffdhe6144_Get
  242. \sa wc_Dh_ffdhe8192_Get
  243. */
  244. const DhParams* wc_Dh_ffdhe3072_Get(void);
  245. /*!
  246. \ingroup Diffie-Hellman
  247. \brief This function returns ... and requires that HAVE_FFDHE_4096 be
  248. defined.
  249. \sa wc_Dh_ffdhe2048_Get
  250. \sa wc_Dh_ffdhe3072_Get
  251. \sa wc_Dh_ffdhe6144_Get
  252. \sa wc_Dh_ffdhe8192_Get
  253. */
  254. const DhParams* wc_Dh_ffdhe4096_Get(void);
  255. /*!
  256. \ingroup Diffie-Hellman
  257. \brief This function returns ... and requires that HAVE_FFDHE_6144 be
  258. defined.
  259. \sa wc_Dh_ffdhe2048_Get
  260. \sa wc_Dh_ffdhe3072_Get
  261. \sa wc_Dh_ffdhe4096_Get
  262. \sa wc_Dh_ffdhe8192_Get
  263. */
  264. const DhParams* wc_Dh_ffdhe6144_Get(void);
  265. /*!
  266. \ingroup Diffie-Hellman
  267. \brief This function returns ... and requires that HAVE_FFDHE_8192 be
  268. defined.
  269. \sa wc_Dh_ffdhe2048_Get
  270. \sa wc_Dh_ffdhe3072_Get
  271. \sa wc_Dh_ffdhe4096_Get
  272. \sa wc_Dh_ffdhe6144_Get
  273. */
  274. const DhParams* wc_Dh_ffdhe8192_Get(void);
  275. /*!
  276. \ingroup Diffie-Hellman
  277. \brief Checks DH keys for pair-wise consistency per process in SP 800-56Ar3,
  278. section 5.6.2.1.4, method (b) for FFC.
  279. */
  280. int wc_DhCheckKeyPair(DhKey* key, const byte* pub, word32 pubSz,
  281. const byte* priv, word32 privSz);
  282. /*!
  283. \ingroup Diffie-Hellman
  284. \brief Check DH private key for invalid numbers
  285. */
  286. int wc_DhCheckPrivKey(DhKey* key, const byte* priv, word32 pubSz);
  287. /*!
  288. \ingroup Diffie-Hellman
  289. */
  290. int wc_DhCheckPrivKey_ex(DhKey* key, const byte* priv, word32 pubSz,
  291. const byte* prime, word32 primeSz);
  292. /*!
  293. \ingroup Diffie-Hellman
  294. */
  295. int wc_DhCheckPubKey(DhKey* key, const byte* pub, word32 pubSz);
  296. /*!
  297. \ingroup Diffie-Hellman
  298. */
  299. int wc_DhCheckPubKey_ex(DhKey* key, const byte* pub, word32 pubSz,
  300. const byte* prime, word32 primeSz);
  301. /*!
  302. \ingroup Diffie-Hellman
  303. */
  304. int wc_DhExportParamsRaw(DhKey* dh, byte* p, word32* pSz,
  305. byte* q, word32* qSz, byte* g, word32* gSz);
  306. /*!
  307. \ingroup Diffie-Hellman
  308. */
  309. int wc_DhGenerateParams(WC_RNG *rng, int modSz, DhKey *dh);
  310. /*!
  311. \ingroup Diffie-Hellman
  312. */
  313. int wc_DhSetCheckKey(DhKey* key, const byte* p, word32 pSz,
  314. const byte* g, word32 gSz, const byte* q, word32 qSz,
  315. int trusted, WC_RNG* rng);
  316. /*!
  317. \ingroup Diffie-Hellman
  318. */
  319. int wc_DhSetKey_ex(DhKey* key, const byte* p, word32 pSz,
  320. const byte* g, word32 gSz, const byte* q, word32 qSz);
  321. /*!
  322. \ingroup Diffie-Hellman
  323. */
  324. int wc_FreeDhKey(DhKey* key);