wc_encrypt.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212
  1. /*!
  2. \ingroup AES
  3. \brief Decrypts a cipher from the input buffer in, and places the
  4. resulting plain text in the output buffer out using cipher block
  5. chaining with AES. This function does not require an AES structure
  6. to be initialized. Instead, it takes in a key and an iv
  7. (initialization vector) and uses these to initialize an
  8. AES object and then decrypt the cipher text.
  9. \return 0 On successfully decrypting message
  10. \return BAD_ALIGN_E Returned on block align error
  11. \return BAD_FUNC_ARG Returned if key length is invalid or AES object
  12. is null during AesSetIV
  13. \return MEMORY_E Returned if WOLFSSL_SMALL_STACK is enabled and
  14. XMALLOC fails to instantiate an AES object.
  15. \param out pointer to the output buffer in which to store the plain
  16. text of the decrypted message
  17. \param in pointer to the input buffer containing cipher text to be
  18. decrypted
  19. \param inSz size of input message
  20. \param key 16, 24, or 32 byte secret key for decryption
  21. \param keySz size of key used for decryption
  22. _Example_
  23. \code
  24. int ret = 0;
  25. byte key[] = { some 16, 24, or 32 byte key };
  26. byte iv[] = { some 16 byte iv };
  27. byte cipher[AES_BLOCK_SIZE * n]; //n being a positive integer making
  28. cipher some multiple of 16 bytes
  29. // fill cipher with cipher text
  30. byte plain [AES_BLOCK_SIZE * n];
  31. if ((ret = wc_AesCbcDecryptWithKey(plain, cipher, AES_BLOCK_SIZE, key,
  32. AES_BLOCK_SIZE, iv)) != 0 ) {
  33. // Decrypt Error
  34. }
  35. \endcode
  36. \sa wc_AesSetKey
  37. \sa wc_AesSetIV
  38. \sa wc_AesCbcEncrypt
  39. \sa wc_AesCbcDecrypt
  40. */
  41. int wc_AesCbcDecryptWithKey(byte* out, const byte* in, word32 inSz,
  42. const byte* key, word32 keySz,
  43. const byte* iv);
  44. /*!
  45. \ingroup 3DES
  46. \brief This function decrypts the input ciphertext, in, and stores the
  47. resulting plaintext in the output buffer, out. It uses DES encryption
  48. with cipher block chaining (CBC) mode. This function is a substitute
  49. for wc_Des_CbcDecrypt, allowing the user to decrypt a message without
  50. directly instantiating a Des structure.
  51. \return 0 Returned upon successfully decrypting the given ciphertext
  52. \return MEMORY_E Returned if there is an error allocating space for a
  53. Des structure
  54. \param out pointer to the buffer in which to store the decrypted plaintext
  55. \param in pointer to the input buffer containing the encrypted ciphertext
  56. \param sz length of the ciphertext to decrypt
  57. \param key pointer to the buffer containing the 8 byte key to use for
  58. decryption
  59. \param iv pointer to the buffer containing the 8 byte iv to use for
  60. decryption. If no iv is provided, the iv defaults to 0
  61. _Example_
  62. \code
  63. int ret;
  64. byte key[] = { // initialize with 8 byte key };
  65. byte iv[] = { // initialize with 8 byte iv };
  66. byte cipher[] = { // initialize with ciphertext };
  67. byte decoded[sizeof(cipher)];
  68. if ( wc_Des_CbcDecryptWithKey(decoded, cipher, sizeof(cipher), key,
  69. iv) != 0) {
  70. // error decrypting message
  71. }
  72. \endcode
  73. \sa wc_Des_CbcDecrypt
  74. */
  75. int wc_Des_CbcDecryptWithKey(byte* out,
  76. const byte* in, word32 sz,
  77. const byte* key, const byte* iv);
  78. /*!
  79. \ingroup 3DES
  80. \brief This function encrypts the input plaintext, in, and stores the
  81. resulting ciphertext in the output buffer, out. It uses DES encryption
  82. with cipher block chaining (CBC) mode. This function is a substitute
  83. for wc_Des_CbcEncrypt, allowing the user to encrypt a message without
  84. directly instantiating a Des structure.
  85. \return 0 Returned after successfully encrypting data.
  86. \return MEMORY_E Returned if there's an error allocating memory for a
  87. Des structure.
  88. \return <0 Returned on any error during encryption.
  89. \param out Final encrypted data
  90. \param in Data to be encrypted, must be padded to Des block size.
  91. \param sz Size of input buffer.
  92. \param key Pointer to the key to use for encryption.
  93. \param iv Initialization vector
  94. _Example_
  95. \code
  96. byte key[] = { // initialize with 8 byte key };
  97. byte iv[] = { // initialize with 8 byte iv };
  98. byte in[] = { // Initialize with plaintext };
  99. byte out[sizeof(in)];
  100. if ( wc_Des_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0)
  101. {
  102. // error encrypting message
  103. }
  104. \endcode
  105. \sa wc_Des_CbcDecryptWithKey
  106. \sa wc_Des_CbcEncrypt
  107. */
  108. int wc_Des_CbcEncryptWithKey(byte* out,
  109. const byte* in, word32 sz,
  110. const byte* key, const byte* iv);
  111. /*!
  112. \ingroup 3DES
  113. \brief This function encrypts the input plaintext, in, and stores
  114. the resulting ciphertext in the output buffer, out. It uses Triple
  115. DES (3DES) encryption with cipher block chaining (CBC) mode. This
  116. function is a substitute for wc_Des3_CbcEncrypt, allowing the user
  117. to encrypt a message without directly instantiating a Des3 structure.
  118. \return 0 Returned after successfully encrypting data.
  119. \return MEMORY_E Returned if there's an error allocating memory for
  120. a Des structure.
  121. \return <0 Returned on any error during encryption.
  122. \param out Final encrypted data
  123. \param in Data to be encrypted, must be padded to Des block size.
  124. \param sz Size of input buffer.
  125. \param key Pointer to the key to use for encryption.
  126. \param iv Initialization vector
  127. _Example_
  128. \code
  129. byte key[] = { // initialize with 8 byte key };
  130. byte iv[] = { // initialize with 8 byte iv };
  131. byte in[] = { // Initialize with plaintext };
  132. byte out[sizeof(in)];
  133. if ( wc_Des3_CbcEncryptWithKey(&out, in, sizeof(in), key, iv) != 0)
  134. {
  135. // error encrypting message
  136. }
  137. \endcode
  138. \sa wc_Des3_CbcDecryptWithKey
  139. \sa wc_Des_CbcEncryptWithKey
  140. \sa wc_Des_CbcDecryptWithKey
  141. */
  142. int wc_Des3_CbcEncryptWithKey(byte* out,
  143. const byte* in, word32 sz,
  144. const byte* key, const byte* iv);
  145. /*!
  146. \ingroup 3DES
  147. \brief This function decrypts the input ciphertext, in, and stores
  148. the resulting plaintext in the output buffer, out. It uses Triple
  149. Des (3DES) encryption with cipher block chaining (CBC) mode. This
  150. function is a substitute for wc_Des3_CbcDecrypt, allowing the user
  151. to decrypt a message without directly instantiating a Des3 structure.
  152. \return 0 Returned upon successfully decrypting the given ciphertext
  153. \return MEMORY_E Returned if there is an error allocating space for
  154. a Des structure
  155. \param out pointer to the buffer in which to store the decrypted plaintext
  156. \param in pointer to the input buffer containing the encrypted ciphertext
  157. \param sz length of the ciphertext to decrypt
  158. \param key pointer to the buffer containing the 24 byte key to use
  159. for decryption
  160. \param iv pointer to the buffer containing the 8 byte iv to use for
  161. decryption. If no iv is provided, the iv defaults to 0
  162. _Example_
  163. \code
  164. int ret;
  165. byte key[] = { // initialize with 24 byte key };
  166. byte iv[] = { // initialize with 8 byte iv };
  167. byte cipher[] = { // initialize with ciphertext };
  168. byte decoded[sizeof(cipher)];
  169. if ( wc_Des3_CbcDecryptWithKey(decoded, cipher, sizeof(cipher),
  170. key, iv) != 0) {
  171. // error decrypting message
  172. }
  173. \endcode
  174. \sa wc_Des3_CbcDecrypt
  175. */
  176. int wc_Des3_CbcDecryptWithKey(byte* out,
  177. const byte* in, word32 sz,
  178. const byte* key, const byte* iv);