1
0

dh.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281
  1. /*!
  2. \ingroup Diffie-Hellman
  3. \brief この関数は、Diffie-Hellman Exchangeプロトコルを使用して安全な秘密鍵を交渉するのに使用するためのDiffie-Hellmanキーを初期化します。
  4. \return none いいえ返します。
  5. _Example_
  6. \code
  7. DhKey key;
  8. wc_InitDhKey(&key); // initialize DH key
  9. \endcode
  10. \sa wc_FreeDhKey
  11. \sa wc_DhGenerateKeyPair
  12. */
  13. int wc_InitDhKey(DhKey* key);
  14. /*!
  15. \ingroup Diffie-Hellman
  16. \brief この関数は、Diffie-Hellman Exchangeプロトコルを使用して安全な秘密鍵をネゴシエートするために使用された後にDiffie-Hellmanキーを解放します。
  17. \return none いいえ返します。
  18. _Example_
  19. \code
  20. DhKey key;
  21. // initialize key, perform key exchange
  22. wc_FreeDhKey(&key); // free DH key to avoid memory leaks
  23. \endcode
  24. \sa wc_InitDhKey
  25. */
  26. void wc_FreeDhKey(DhKey* key);
  27. /*!
  28. \ingroup Diffie-Hellman
  29. \brief この関数はdiffie-hellmanパブリックパラメータに基づいてパブリック/秘密鍵ペアを生成し、PRIVSの秘密鍵とPubの公開鍵を格納します。初期化されたDiffie-Hellmanキーと初期化されたRNG構造を取ります。
  30. \return BAD_FUNC_ARG この関数への入力の1つを解析するエラーがある場合に返されます
  31. \return RNG_FAILURE_E RNGを使用して乱数を生成するエラーが発生した場合
  32. \return MP_INIT_E 公開鍵の生成中に数学ライブラリにエラーがある場合は返却される可能性があります
  33. \return MP_READ_E 公開鍵の生成中に数学ライブラリにエラーがある場合は返却される可能性があります
  34. \return MP_EXPTMOD_E 公開鍵の生成中に数学ライブラリにエラーがある場合は返却される可能性があります
  35. \return MP_TO_E 公開鍵の生成中に数学ライブラリにエラーがある場合は返却される可能性があります
  36. \param key キーペアを生成するDHKEY構造体へのポインタ
  37. \param rng キーを生成するための初期化された乱数発生器(RNG)へのポインタ
  38. \param priv 秘密鍵を保存するバッファへのポインタ
  39. \param privSz PRIVに書かれた秘密鍵のサイズを保存します
  40. \param pub 公開鍵を保存するバッファへのポインタ
  41. _Example_
  42. \code
  43. DhKey key;
  44. int ret;
  45. byte priv[256];
  46. byte pub[256];
  47. word32 privSz, pubSz;
  48. wc_InitDhKey(&key); // initialize key
  49. // Set DH parameters using wc_DhSetKey or wc_DhKeyDecode
  50. WC_RNG rng;
  51. wc_InitRng(&rng); // initialize rng
  52. ret = wc_DhGenerateKeyPair(&key, &rng, priv, &privSz, pub, &pubSz);
  53. \endcode
  54. \sa wc_InitDhKey
  55. \sa wc_DhSetKey
  56. \sa wc_DhKeyDecode
  57. */
  58. int wc_DhGenerateKeyPair(DhKey* key, WC_RNG* rng, byte* priv,
  59. word32* privSz, byte* pub, word32* pubSz);
  60. /*!
  61. \ingroup Diffie-Hellman
  62. \brief この関数は、ローカル秘密鍵と受信した公開鍵に基づいて合意された秘密鍵を生成します。交換の両側で完了した場合、この関数は対称通信のための秘密鍵の合意を生成します。共有秘密鍵の生成に成功すると、書かれた秘密鍵のサイズは仲間に保存されます。
  63. \return 0 合意された秘密鍵の生成に成功しました
  64. \return MP_INIT_E 共有秘密鍵の生成中にエラーが発生した場合に返却される可能性があります
  65. \return MP_READ_E 共有秘密鍵の生成中にエラーが発生した場合に返却される可能性があります
  66. \return MP_EXPTMOD_E 共有秘密鍵の生成中にエラーが発生した場合に返却される可能性があります
  67. \return MP_TO_E 共有秘密鍵の生成中にエラーが発生した場合に返却される可能性があります
  68. \param key 共有キーを計算するために使用するDHKEY構造体へのポインタ
  69. \param agree 秘密キーを保存するバッファへのポインタ
  70. \param agreeSz 成功した後に秘密鍵のサイズを保持します
  71. \param priv ローカル秘密鍵を含むバッファへのポインタ
  72. \param privSz 地元の秘密鍵のサイズ
  73. \param otherPub 受信した公開鍵を含むバッファへのポインタ
  74. _Example_
  75. \code
  76. DhKey key;
  77. int ret;
  78. byte priv[256];
  79. byte agree[256];
  80. word32 agreeSz;
  81. // initialize key, set key prime and base
  82. // wc_DhGenerateKeyPair -- store private key in priv
  83. byte pub[] = { // initialized with the received public key };
  84. ret = wc_DhAgree(&key, agree, &agreeSz, priv, sizeof(priv), pub,
  85. sizeof(pub));
  86. if ( ret != 0 ) {
  87. // error generating shared key
  88. }
  89. \endcode
  90. \sa wc_DhGenerateKeyPair
  91. */
  92. int wc_DhAgree(DhKey* key, byte* agree, word32* agreeSz,
  93. const byte* priv, word32 privSz, const byte* otherPub,
  94. word32 pubSz);
  95. /*!
  96. \ingroup Diffie-Hellman
  97. \brief この機能は、DERフォーマットのキーを含む与えられた入力バッファからDiffie-Hellmanキーをデコードします。結果をDHKEY構造体に格納します。
  98. \return 0 入力キーの復号に成功したときに返されます
  99. \return ASN_PARSE_E 入力のシーケンスを解析したエラーがある場合に返されます
  100. \return ASN_DH_KEY_E 解析された入力から秘密鍵パラメータを読み取るエラーがある場合
  101. \param input derフォーマットされたdiffie-hellmanキーを含むバッファへのポインタ
  102. \param inOutIdx キーをデコードしている間に解析されたインデックスを保存する整数へのポインタ
  103. \param key 入力キーで初期化するためのDHKEY構造体へのポインタ
  104. _Example_
  105. \code
  106. DhKey key;
  107. word32 idx = 0;
  108. byte keyBuff[1024];
  109. // initialize with DER formatted key
  110. wc_DhKeyInit(&key);
  111. ret = wc_DhKeyDecode(keyBuff, &idx, &key, sizeof(keyBuff));
  112. if ( ret != 0 ) {
  113. // error decoding key
  114. }
  115. \endcode
  116. \sa wc_DhSetKey
  117. */
  118. int wc_DhKeyDecode(const byte* input, word32* inOutIdx, DhKey* key,
  119. word32);
  120. /*!
  121. \ingroup Diffie-Hellman
  122. \brief この関数は、入力秘密鍵パラメータを使用してDHKEY構造体のキーを設定します。WC_DHKEYDECODEとは異なり、この関数は入力キーがDERフォーマットでフォーマットされ、代わりにPARSED入力パラメータP(Prime)とG(Base)を受け入れる必要はありません。
  123. \return 0 鍵の設定に成功しました
  124. \return BAD_FUNC_ARG 入力パラメータのいずれかがNULLに評価された場合に返されます。
  125. \return MP_INIT_E ストレージのキーパラメータの初期化中にエラーがある場合に返されます。
  126. \return ASN_DH_KEY_E DHキーパラメータPおよびGでエラーの読み取りがある場合は返されます
  127. \param key キーを設定するDHKEY構造体へのポインタ
  128. \param p キーで使用するためのプライムを含むバッファへのポインタ
  129. \param pSz 入力プライムの長さ
  130. \param g キーで使用するためのベースを含むバッファへのポインタ
  131. _Example_
  132. \code
  133. DhKey key;
  134. byte p[] = { // initialize with prime };
  135. byte g[] = { // initialize with base };
  136. wc_DhKeyInit(&key);
  137. ret = wc_DhSetKey(key, p, sizeof(p), g, sizeof(g));
  138. if ( ret != 0 ) {
  139. // error setting key
  140. }
  141. \endcode
  142. \sa wc_DhKeyDecode
  143. */
  144. int wc_DhSetKey(DhKey* key, const byte* p, word32 pSz, const byte* g,
  145. word32 gSz);
  146. /*!
  147. \ingroup Diffie-Hellman
  148. \brief この関数は、与えられた入力バッファからDiffie-HellmanパラメータP(Prime)とG(ベース)をフォーマットされています。
  149. \return 0 DHパラメータの抽出に成功しました
  150. \return ASN_PARSE_E DERフォーマットのDH証明書の解析中にエラーが発生した場合に返されます。
  151. \return BUFFER_E 解析されたパラメータを格納するためにPまたはGに不適切なスペースがある場合
  152. \param input 解析するDERフォーマットされたDifie-Hellman証明書を含むバッファへのポインタ
  153. \param inSz 入力バッファのサイズ
  154. \param p 解析されたプライムを保存するバッファへのポインタ
  155. \param pInOutSz Pバッファ内の使用可能なサイズを含むWord32オブジェクトへのポインタ。関数呼び出しを完了した後にバッファに書き込まれたバイト数で上書きされます。
  156. \param g 解析されたベースを保存するバッファへのポインタ
  157. _Example_
  158. \code
  159. byte dhCert[] = { initialize with DER formatted certificate };
  160. byte p[MAX_DH_SIZE];
  161. byte g[MAX_DH_SIZE];
  162. word32 pSz = MAX_DH_SIZE;
  163. word32 gSz = MAX_DH_SIZE;
  164. ret = wc_DhParamsLoad(dhCert, sizeof(dhCert), p, &pSz, g, &gSz);
  165. if ( ret != 0 ) {
  166. // error parsing inputs
  167. }
  168. \endcode
  169. \sa wc_DhSetKey
  170. \sa wc_DhKeyDecode
  171. */
  172. int wc_DhParamsLoad(const byte* input, word32 inSz, byte* p,
  173. word32* pInOutSz, byte* g, word32* gInOutSz);
  174. /*!
  175. \ingroup Diffie-Hellman
  176. \sa wc_Dh_ffdhe3072_Get
  177. \sa wc_Dh_ffdhe4096_Get
  178. \sa wc_Dh_ffdhe6144_Get
  179. \sa wc_Dh_ffdhe8192_Get
  180. */
  181. const DhParams* wc_Dh_ffdhe2048_Get(void);
  182. /*!
  183. \ingroup Diffie-Hellman
  184. \sa wc_Dh_ffdhe2048_Get
  185. \sa wc_Dh_ffdhe4096_Get
  186. \sa wc_Dh_ffdhe6144_Get
  187. \sa wc_Dh_ffdhe8192_Get
  188. */
  189. const DhParams* wc_Dh_ffdhe3072_Get(void);
  190. /*!
  191. \ingroup Diffie-Hellman
  192. \sa wc_Dh_ffdhe2048_Get
  193. \sa wc_Dh_ffdhe3072_Get
  194. \sa wc_Dh_ffdhe6144_Get
  195. \sa wc_Dh_ffdhe8192_Get
  196. */
  197. const DhParams* wc_Dh_ffdhe4096_Get(void);
  198. /*!
  199. \ingroup Diffie-Hellman
  200. \sa wc_Dh_ffdhe2048_Get
  201. \sa wc_Dh_ffdhe3072_Get
  202. \sa wc_Dh_ffdhe4096_Get
  203. \sa wc_Dh_ffdhe8192_Get
  204. */
  205. const DhParams* wc_Dh_ffdhe6144_Get(void);
  206. /*!
  207. \ingroup Diffie-Hellman
  208. \sa wc_Dh_ffdhe2048_Get
  209. \sa wc_Dh_ffdhe3072_Get
  210. \sa wc_Dh_ffdhe4096_Get
  211. \sa wc_Dh_ffdhe6144_Get
  212. */
  213. const DhParams* wc_Dh_ffdhe8192_Get(void);
  214. /*!
  215. \ingroup Diffie-Hellman
  216. */
  217. int wc_DhCheckKeyPair(DhKey* key, const byte* pub, word32 pubSz,
  218. const byte* priv, word32 privSz);
  219. /*!
  220. \ingroup Diffie-Hellman
  221. */
  222. int wc_DhCheckPrivKey(DhKey* key, const byte* priv, word32 pubSz);
  223. /*!
  224. */
  225. int wc_DhCheckPrivKey_ex(DhKey* key, const byte* priv, word32 pubSz,
  226. const byte* prime, word32 primeSz);
  227. /*!
  228. */
  229. int wc_DhCheckPubKey(DhKey* key, const byte* pub, word32 pubSz);
  230. /*!
  231. */
  232. int wc_DhCheckPubKey_ex(DhKey* key, const byte* pub, word32 pubSz,
  233. const byte* prime, word32 primeSz);
  234. /*!
  235. */
  236. int wc_DhExportParamsRaw(DhKey* dh, byte* p, word32* pSz,
  237. byte* q, word32* qSz, byte* g, word32* gSz);
  238. /*!
  239. */
  240. int wc_DhGenerateParams(WC_RNG *rng, int modSz, DhKey *dh);
  241. /*!
  242. */
  243. int wc_DhSetCheckKey(DhKey* key, const byte* p, word32 pSz,
  244. const byte* g, word32 gSz, const byte* q, word32 qSz,
  245. int trusted, WC_RNG* rng);
  246. /*!
  247. */
  248. int wc_DhSetKey_ex(DhKey* key, const byte* p, word32 pSz,
  249. const byte* g, word32 gSz, const byte* q, word32 qSz);
  250. /*!
  251. */
  252. int wc_FreeDhKey(DhKey* key);