des3.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332
  1. /*!
  2. \ingroup 3DES
  3. \brief This function sets the key and initialization vector (iv) for the
  4. Des structure given as argument. It also initializes and allocates space
  5. for the buffers needed for encryption and decryption, if these have not
  6. yet been initialized. Note: If no iv is provided (i.e. iv == NULL)
  7. the initialization vector defaults to an iv of 0.
  8. \return 0 On successfully setting the key and initialization vector for
  9. the Des structure
  10. \param des pointer to the Des structure to initialize
  11. \param key pointer to the buffer containing the 8 byte key with which to
  12. initialize the Des structure
  13. \param iv pointer to the buffer containing the 8 byte iv with which to
  14. initialize the Des structure. If this is not provided, the iv defaults to 0
  15. \param dir direction of encryption. Valid options are: DES_ENCRYPTION,
  16. and DES_DECRYPTION
  17. _Example_
  18. \code
  19. Des enc; // Des structure used for encryption
  20. int ret;
  21. byte key[] = { // initialize with 8 byte key };
  22. byte iv[] = { // initialize with 8 byte iv };
  23. ret = wc_Des_SetKey(&des, key, iv, DES_ENCRYPTION);
  24. if (ret != 0) {
  25. // error initializing des structure
  26. }
  27. \endcode
  28. \sa wc_Des_SetIV
  29. \sa wc_Des3_SetKey
  30. */
  31. WOLFSSL_API int wc_Des_SetKey(Des* des, const byte* key,
  32. const byte* iv, int dir);
  33. /*!
  34. \ingroup 3DES
  35. \brief This function sets the initialization vector (iv) for the Des
  36. structure given as argument. When passed a NULL iv, it sets the
  37. initialization vector to 0.
  38. \return none No returns.
  39. \param des pointer to the Des structure for which to set the iv
  40. \param iv pointer to the buffer containing the 8 byte iv with which to
  41. initialize the Des structure. If this is not provided, the iv defaults to 0
  42. _Example_
  43. \code
  44. Des enc; // Des structure used for encryption
  45. // initialize enc with wc_Des_SetKey
  46. byte iv[] = { // initialize with 8 byte iv };
  47. wc_Des_SetIV(&enc, iv);
  48. }
  49. \endcode
  50. \sa wc_Des_SetKey
  51. */
  52. WOLFSSL_API void wc_Des_SetIV(Des* des, const byte* iv);
  53. /*!
  54. \ingroup 3DES
  55. \brief This function encrypts the input message, in, and stores the result
  56. in the output buffer, out. It uses DES encryption with cipher block
  57. chaining (CBC) mode.
  58. \return 0 Returned upon successfully encrypting the given input message
  59. \param des pointer to the Des structure to use for encryption
  60. \param out pointer to the buffer in which to store the encrypted ciphertext
  61. \param in pointer to the input buffer containing the message to encrypt
  62. \param sz length of the message to encrypt
  63. _Example_
  64. \code
  65. Des enc; // Des structure used for encryption
  66. // initialize enc with wc_Des_SetKey, use mode DES_ENCRYPTION
  67. byte plain[] = { // initialize with message };
  68. byte cipher[sizeof(plain)];
  69. if ( wc_Des_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) {
  70. // error encrypting message
  71. }
  72. \endcode
  73. \sa wc_Des_SetKey
  74. \sa wc_Des_CbcDecrypt
  75. */
  76. WOLFSSL_API int wc_Des_CbcEncrypt(Des* des, byte* out,
  77. const byte* in, word32 sz);
  78. /*!
  79. \ingroup 3DES
  80. \brief This function decrypts the input ciphertext, in, and stores the
  81. resulting plaintext in the output buffer, out. It uses DES encryption
  82. with cipher block chaining (CBC) mode.
  83. \return 0 Returned upon successfully decrypting the given ciphertext
  84. \param des pointer to the Des structure to use for decryption
  85. \param out pointer to the buffer in which to store the decrypted plaintext
  86. \param in pointer to the input buffer containing the encrypted ciphertext
  87. \param sz length of the ciphertext to decrypt
  88. _Example_
  89. \code
  90. Des dec; // Des structure used for decryption
  91. // initialize dec with wc_Des_SetKey, use mode DES_DECRYPTION
  92. byte cipher[] = { // initialize with ciphertext };
  93. byte decoded[sizeof(cipher)];
  94. if ( wc_Des_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) {
  95. // error decrypting message
  96. }
  97. \endcode
  98. \sa wc_Des_SetKey
  99. \sa wc_Des_CbcEncrypt
  100. */
  101. WOLFSSL_API int wc_Des_CbcDecrypt(Des* des, byte* out,
  102. const byte* in, word32 sz);
  103. /*!
  104. \ingroup 3DES
  105. \brief This function encrypts the input message, in, and stores the result
  106. in the output buffer, out. It uses Des encryption with Electronic
  107. Codebook (ECB) mode.
  108. \return 0: Returned upon successfully encrypting the given plaintext.
  109. \param des pointer to the Des structure to use for encryption
  110. \param out pointer to the buffer in which to store the encrypted message
  111. \param in pointer to the input buffer containing the plaintext to encrypt
  112. \param sz length of the plaintext to encrypt
  113. _Example_
  114. \code
  115. Des enc; // Des structure used for encryption
  116. // initialize enc with wc_Des_SetKey, use mode DES_ENCRYPTION
  117. byte plain[] = { // initialize with message to encrypt };
  118. byte cipher[sizeof(plain)];
  119. if ( wc_Des_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
  120. // error encrypting message
  121. }
  122. \endcode
  123. \sa wc_Des_SetKe
  124. */
  125. WOLFSSL_API int wc_Des_EcbEncrypt(Des* des, byte* out,
  126. const byte* in, word32 sz);
  127. /*!
  128. \ingroup 3DES
  129. \brief This function encrypts the input message, in, and stores the
  130. result in the output buffer, out. It uses Des3 encryption with
  131. Electronic Codebook (ECB) mode. Warning: In nearly all use cases ECB
  132. mode is considered to be less secure. Please avoid using ECB API’s
  133. directly whenever possible.
  134. \return 0 Returned upon successfully encrypting the given plaintext
  135. \param des3 pointer to the Des3 structure to use for encryption
  136. \param out pointer to the buffer in which to store the encrypted message
  137. \param in pointer to the input buffer containing the plaintext to encrypt
  138. \param sz length of the plaintext to encrypt
  139. _Example_
  140. /code
  141. Des3 enc; // Des3 structure used for encryption
  142. // initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION
  143. byte plain[] = { // initialize with message to encrypt };
  144. byte cipher[sizeof(plain)];
  145. if ( wc_Des3_EcbEncrypt(&enc,cipher, plain, sizeof(plain)) != 0) {
  146. // error encrypting message
  147. }
  148. /endcode
  149. \sa wc_Des3_SetKey
  150. */
  151. WOLFSSL_API int wc_Des3_EcbEncrypt(Des3* des, byte* out,
  152. const byte* in, word32 sz);
  153. /*!
  154. \ingroup 3DES
  155. \brief This function sets the key and initialization vector (iv) for
  156. the Des3 structure given as argument. It also initializes and allocates
  157. space for the buffers needed for encryption and decryption, if these
  158. have not yet been initialized. Note: If no iv is provided (i.e. iv ==
  159. NULL) the initialization vector defaults to an iv of 0.
  160. \return 0 On successfully setting the key and initialization vector
  161. for the Des structure
  162. \param des3 pointer to the Des3 structure to initialize
  163. \param key pointer to the buffer containing the 24 byte key with which
  164. to initialize the Des3 structure
  165. \param iv pointer to the buffer containing the 8 byte iv with which to
  166. initialize the Des3 structure. If this is not provided, the iv defaults
  167. to 0
  168. \param dir direction of encryption. Valid options are: DES_ENCRYPTION,
  169. and DES_DECRYPTION
  170. _Example_
  171. \code
  172. Des3 enc; // Des3 structure used for encryption
  173. int ret;
  174. byte key[] = { // initialize with 24 byte key };
  175. byte iv[] = { // initialize with 8 byte iv };
  176. ret = wc_Des3_SetKey(&des, key, iv, DES_ENCRYPTION);
  177. if (ret != 0) {
  178. // error initializing des structure
  179. }
  180. \endcode
  181. \sa wc_Des3_SetIV
  182. \sa wc_Des3_CbcEncrypt
  183. \sa wc_Des3_CbcDecrypt
  184. */
  185. WOLFSSL_API int wc_Des3_SetKey(Des3* des, const byte* key,
  186. const byte* iv,int dir);
  187. /*!
  188. \ingroup 3DES
  189. \brief This function sets the initialization vector (iv) for the Des3
  190. structure given as argument. When passed a NULL iv, it sets the
  191. initialization vector to 0.
  192. \return none No returns.
  193. \param des pointer to the Des3 structure for which to set the iv
  194. \param iv pointer to the buffer containing the 8 byte iv with which to
  195. initialize the Des3 structure. If this is not provided, the iv
  196. defaults to 0
  197. _Example_
  198. \code
  199. Des3 enc; // Des3 structure used for encryption
  200. // initialize enc with wc_Des3_SetKey
  201. byte iv[] = { // initialize with 8 byte iv };
  202. wc_Des3_SetIV(&enc, iv);
  203. }
  204. \endcode
  205. \sa wc_Des3_SetKey
  206. */
  207. WOLFSSL_API int wc_Des3_SetIV(Des3* des, const byte* iv);
  208. /*!
  209. \ingroup 3DES
  210. \brief This function encrypts the input message, in, and stores the
  211. result in the output buffer, out. It uses Triple Des (3DES) encryption
  212. with cipher block chaining (CBC) mode.
  213. \return 0 Returned upon successfully encrypting the given input message
  214. \param des pointer to the Des3 structure to use for encryption
  215. \param out pointer to the buffer in which to store the encrypted ciphertext
  216. \param in pointer to the input buffer containing the message to encrypt
  217. \param sz length of the message to encrypt
  218. _Example_
  219. \code
  220. Des3 enc; // Des3 structure used for encryption
  221. // initialize enc with wc_Des3_SetKey, use mode DES_ENCRYPTION
  222. byte plain[] = { // initialize with message };
  223. byte cipher[sizeof(plain)];
  224. if ( wc_Des3_CbcEncrypt(&enc, cipher, plain, sizeof(plain)) != 0) {
  225. // error encrypting message
  226. }
  227. \endcode
  228. \sa wc_Des3_SetKey
  229. \sa wc_Des3_CbcDecrypt
  230. */
  231. WOLFSSL_API int wc_Des3_CbcEncrypt(Des3* des, byte* out,
  232. const byte* in,word32 sz);
  233. /*!
  234. \ingroup 3DES
  235. \brief This function decrypts the input ciphertext, in, and stores the
  236. resulting plaintext in the output buffer, out. It uses Triple Des (3DES)
  237. encryption with cipher block chaining (CBC) mode.
  238. \return 0 Returned upon successfully decrypting the given ciphertext
  239. \param des pointer to the Des3 structure to use for decryption
  240. \param out pointer to the buffer in which to store the decrypted plaintext
  241. \param in pointer to the input buffer containing the encrypted ciphertext
  242. \param sz length of the ciphertext to decrypt
  243. _Example_
  244. \code
  245. Des3 dec; // Des structure used for decryption
  246. // initialize dec with wc_Des3_SetKey, use mode DES_DECRYPTION
  247. byte cipher[] = { // initialize with ciphertext };
  248. byte decoded[sizeof(cipher)];
  249. if ( wc_Des3_CbcDecrypt(&dec, decoded, cipher, sizeof(cipher)) != 0) {
  250. // error decrypting message
  251. }
  252. \endcode
  253. \sa wc_Des3_SetKey
  254. \sa wc_Des3_CbcEncrypt
  255. */
  256. WOLFSSL_API int wc_Des3_CbcDecrypt(Des3* des, byte* out,
  257. const byte* in,word32 sz);