dsa.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342
  1. /*!
  2. \ingroup DSA
  3. \brief This function initializes a DsaKey object in order to use it for
  4. authentication via the Digital Signature Algorithm (DSA).
  5. \return 0 Returned on success.
  6. \return BAD_FUNC_ARG Returned if a NULL key is passed in.
  7. \param key pointer to the DsaKey structure to initialize
  8. _Example_
  9. \code
  10. DsaKey key;
  11. int ret;
  12. ret = wc_InitDsaKey(&key); // initialize DSA key
  13. \endcode
  14. \sa wc_FreeDsaKey
  15. */
  16. int wc_InitDsaKey(DsaKey* key);
  17. /*!
  18. \ingroup DSA
  19. \brief This function frees a DsaKey object after it has been used.
  20. \return none No returns.
  21. \param key pointer to the DsaKey structure to free
  22. _Example_
  23. \code
  24. DsaKey key;
  25. // initialize key, use for authentication
  26. ...
  27. wc_FreeDsaKey(&key); // free DSA key
  28. \endcode
  29. \sa wc_FreeDsaKey
  30. */
  31. void wc_FreeDsaKey(DsaKey* key);
  32. /*!
  33. \ingroup DSA
  34. \brief This function signs the input digest and stores the result in the
  35. output buffer, out.
  36. \return 0 Returned on successfully signing the input digest
  37. \return MP_INIT_E may be returned if there is an error in processing the
  38. DSA signature.
  39. \return MP_READ_E may be returned if there is an error in processing the
  40. DSA signature.
  41. \return MP_CMP_E may be returned if there is an error in processing the
  42. DSA signature.
  43. \return MP_INVMOD_E may be returned if there is an error in processing the
  44. DSA signature.
  45. \return MP_EXPTMOD_E may be returned if there is an error in processing
  46. the DSA signature.
  47. \return MP_MOD_E may be returned if there is an error in processing the
  48. DSA signature.
  49. \return MP_MUL_E may be returned if there is an error in processing the
  50. DSA signature.
  51. \return MP_ADD_E may be returned if there is an error in processing the
  52. DSA signature.
  53. \return MP_MULMOD_E may be returned if there is an error in processing
  54. the DSA signature.
  55. \return MP_TO_E may be returned if there is an error in processing the
  56. DSA signature.
  57. \return MP_MEM may be returned if there is an error in processing the
  58. DSA signature.
  59. \param digest pointer to the hash to sign
  60. \param out pointer to the buffer in which to store the signature
  61. \param key pointer to the initialized DsaKey structure with which to
  62. generate the signature
  63. \param rng pointer to an initialized RNG to use with the signature
  64. generation
  65. _Example_
  66. \code
  67. DsaKey key;
  68. // initialize DSA key, load private Key
  69. int ret;
  70. WC_RNG rng;
  71. wc_InitRng(&rng);
  72. byte hash[] = { // initialize with hash digest };
  73. byte signature[40]; // signature will be 40 bytes (320 bits)
  74. ret = wc_DsaSign(hash, signature, &key, &rng);
  75. if (ret != 0) {
  76. // error generating DSA signature
  77. }
  78. \endcode
  79. \sa wc_DsaVerify
  80. */
  81. int wc_DsaSign(const byte* digest, byte* out,
  82. DsaKey* key, WC_RNG* rng);
  83. /*!
  84. \ingroup DSA
  85. \brief This function verifies the signature of a digest, given a private
  86. key. It stores whether the key properly verifies in the answer parameter,
  87. with 1 corresponding to a successful verification, and 0 corresponding to
  88. failed verification.
  89. \return 0 Returned on successfully processing the verify request. Note:
  90. this does not mean that the signature is verified, only that the function
  91. succeeded
  92. \return MP_INIT_E may be returned if there is an error in processing the
  93. DSA signature.
  94. \return MP_READ_E may be returned if there is an error in processing the
  95. DSA signature.
  96. \return MP_CMP_E may be returned if there is an error in processing the
  97. DSA signature.
  98. \return MP_INVMOD_E may be returned if there is an error in processing
  99. the DSA signature.
  100. \return MP_EXPTMOD_E may be returned if there is an error in processing
  101. the DSA signature.
  102. \return MP_MOD_E may be returned if there is an error in processing the
  103. DSA signature.
  104. \return MP_MUL_E may be returned if there is an error in processing the
  105. DSA signature.
  106. \return MP_ADD_E may be returned if there is an error in processing the
  107. DSA signature.
  108. \return MP_MULMOD_E may be returned if there is an error in processing
  109. the DSA signature.
  110. \return MP_TO_E may be returned if there is an error in processing the
  111. DSA signature.
  112. \return MP_MEM may be returned if there is an error in processing the
  113. DSA signature.
  114. \param digest pointer to the digest containing the subject of the signature
  115. \param sig pointer to the buffer containing the signature to verify
  116. \param key pointer to the initialized DsaKey structure with which to
  117. verify the signature
  118. \param answer pointer to an integer which will store whether the
  119. verification was successful
  120. _Example_
  121. \code
  122. DsaKey key;
  123. // initialize DSA key, load public Key
  124. int ret;
  125. int verified;
  126. byte hash[] = { // initialize with hash digest };
  127. byte signature[] = { // initialize with signature to verify };
  128. ret = wc_DsaVerify(hash, signature, &key, &verified);
  129. if (ret != 0) {
  130. // error processing verify request
  131. } else if (answer == 0) {
  132. // invalid signature
  133. }
  134. \endcode
  135. \sa wc_DsaSign
  136. */
  137. int wc_DsaVerify(const byte* digest, const byte* sig,
  138. DsaKey* key, int* answer);
  139. /*!
  140. \ingroup DSA
  141. \brief This function decodes a DER formatted certificate buffer containing
  142. a DSA public key, and stores the key in the given DsaKey structure. It
  143. also sets the inOutIdx parameter according to the length of the input read.
  144. \return 0 Returned on successfully setting the public key for the DsaKey
  145. object
  146. \return ASN_PARSE_E Returned if there is an error in the encoding while
  147. reading the certificate buffer
  148. \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly
  149. formatted
  150. \param input pointer to the buffer containing the DER formatted DSA
  151. public key
  152. \param inOutIdx pointer to an integer in which to store the final index
  153. of the certificate read
  154. \param key pointer to the DsaKey structure in which to store the public key
  155. \param inSz size of the input buffer
  156. _Example_
  157. \code
  158. int ret, idx=0;
  159. DsaKey key;
  160. wc_InitDsaKey(&key);
  161. byte derBuff[] = { // DSA public key};
  162. ret = wc_DsaPublicKeyDecode(derBuff, &idx, &key, inSz);
  163. if (ret != 0) {
  164. // error reading public key
  165. }
  166. \endcode
  167. \sa wc_InitDsaKey
  168. \sa wc_DsaPrivateKeyDecode
  169. */
  170. int wc_DsaPublicKeyDecode(const byte* input, word32* inOutIdx,
  171. DsaKey* key, word32 inSz);
  172. /*!
  173. \ingroup DSA
  174. \brief This function decodes a DER formatted certificate buffer containing
  175. a DSA private key, and stores the key in the given DsaKey structure. It
  176. also sets the inOutIdx parameter according to the length of the input read.
  177. \return 0 Returned on successfully setting the private key for the DsaKey
  178. object
  179. \return ASN_PARSE_E Returned if there is an error in the encoding while
  180. reading the certificate buffer
  181. \return ASN_DH_KEY_E Returned if one of the DSA parameters is incorrectly
  182. formatted
  183. \param input pointer to the buffer containing the DER formatted DSA
  184. private key
  185. \param inOutIdx pointer to an integer in which to store the final index
  186. of the certificate read
  187. \param key pointer to the DsaKey structure in which to store the private
  188. key
  189. \param inSz size of the input buffer
  190. _Example_
  191. \code
  192. int ret, idx=0;
  193. DsaKey key;
  194. wc_InitDsaKey(&key);
  195. byte derBuff[] = { // DSA private key };
  196. ret = wc_DsaPrivateKeyDecode(derBuff, &idx, &key, inSz);
  197. if (ret != 0) {
  198. // error reading private key
  199. }
  200. \endcode
  201. \sa wc_InitDsaKey
  202. \sa wc_DsaPublicKeyDecode
  203. */
  204. int wc_DsaPrivateKeyDecode(const byte* input, word32* inOutIdx,
  205. DsaKey* key, word32 inSz);
  206. /*!
  207. \ingroup DSA
  208. \brief Convert DsaKey key to DER format, write to output (inLen),
  209. return bytes written.
  210. \return outLen Success, number of bytes written
  211. \return BAD_FUNC_ARG key or output are null or key->type is not
  212. DSA_PRIVATE.
  213. \return MEMORY_E Error allocating memory.
  214. \param key Pointer to DsaKey structure to convert.
  215. \param output Pointer to output buffer for converted key.
  216. \param inLen Length of key input.
  217. _Example_
  218. \code
  219. DsaKey key;
  220. WC_RNG rng;
  221. int derSz;
  222. int bufferSize = // Sufficient buffer size;
  223. byte der[bufferSize];
  224. wc_InitDsaKey(&key);
  225. wc_InitRng(&rng);
  226. wc_MakeDsaKey(&rng, &key);
  227. derSz = wc_DsaKeyToDer(&key, der, bufferSize);
  228. \endcode
  229. \sa wc_InitDsaKey
  230. \sa wc_FreeDsaKey
  231. \sa wc_MakeDsaKey
  232. */
  233. int wc_DsaKeyToDer(DsaKey* key, byte* output, word32 inLen);
  234. /*!
  235. \ingroup DSA
  236. \brief Create a DSA key.
  237. \return MP_OKAY Success
  238. \return BAD_FUNC_ARG Either rng or dsa is null.
  239. \return MEMORY_E Couldn't allocate memory for buffer.
  240. \return MP_INIT_E Error initializing mp_int
  241. \param rng Pointer to WC_RNG structure.
  242. \param dsa Pointer to DsaKey structure.
  243. _Example_
  244. \code
  245. WC_RNG rng;
  246. DsaKey dsa;
  247. wc_InitRng(&rng);
  248. wc_InitDsa(&dsa);
  249. if(wc_MakeDsaKey(&rng, &dsa) != 0)
  250. {
  251. // Error creating key
  252. }
  253. \endcode
  254. \sa wc_InitDsaKey
  255. \sa wc_FreeDsaKey
  256. \sa wc_DsaSign
  257. */
  258. int wc_MakeDsaKey(WC_RNG *rng, DsaKey *dsa);
  259. /*!
  260. \ingroup DSA
  261. \brief FIPS 186-4 defines valid for modulus_size values as
  262. (1024, 160) (2048, 256) (3072, 256)
  263. \return 0 Success
  264. \return BAD_FUNC_ARG rng or dsa is null or modulus_size is invalid.
  265. \return MEMORY_E Error attempting to allocate memory.
  266. \param rng pointer to wolfCrypt rng.
  267. \param modulus_size 1024, 2048, or 3072 are valid values.
  268. \param dsa Pointer to a DsaKey structure.
  269. _Example_
  270. \code
  271. DsaKey key;
  272. WC_RNG rng;
  273. wc_InitDsaKey(&key);
  274. wc_InitRng(&rng);
  275. if(wc_MakeDsaParameters(&rng, 1024, &genKey) != 0)
  276. {
  277. // Handle error
  278. }
  279. \endcode
  280. \sa wc_MakeDsaKey
  281. \sa wc_DsaKeyToDer
  282. \sa wc_InitDsaKey
  283. */
  284. int wc_MakeDsaParameters(WC_RNG *rng, int modulus_size, DsaKey *dsa);