des.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354
  1. /**
  2. * \file des.h
  3. *
  4. * \brief DES block cipher
  5. *
  6. * \warning DES is considered a weak cipher and its use constitutes a
  7. * security risk. We recommend considering stronger ciphers
  8. * instead.
  9. */
  10. /*
  11. * Copyright The Mbed TLS Contributors
  12. * SPDX-License-Identifier: Apache-2.0
  13. *
  14. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  15. * not use this file except in compliance with the License.
  16. * You may obtain a copy of the License at
  17. *
  18. * http://www.apache.org/licenses/LICENSE-2.0
  19. *
  20. * Unless required by applicable law or agreed to in writing, software
  21. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  22. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  23. * See the License for the specific language governing permissions and
  24. * limitations under the License.
  25. *
  26. */
  27. #ifndef MBEDTLS_DES_H
  28. #define MBEDTLS_DES_H
  29. #if !defined(MBEDTLS_CONFIG_FILE)
  30. #include "mbedtls/config.h"
  31. #else
  32. #include MBEDTLS_CONFIG_FILE
  33. #endif
  34. #include <stddef.h>
  35. #include <stdint.h>
  36. #define MBEDTLS_DES_ENCRYPT 1
  37. #define MBEDTLS_DES_DECRYPT 0
  38. #define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH -0x0032 /**< The data input has an invalid length. */
  39. /* MBEDTLS_ERR_DES_HW_ACCEL_FAILED is deprecated and should not be used. */
  40. #define MBEDTLS_ERR_DES_HW_ACCEL_FAILED -0x0033 /**< DES hardware accelerator failed. */
  41. #define MBEDTLS_DES_KEY_SIZE 8
  42. #ifdef __cplusplus
  43. extern "C" {
  44. #endif
  45. #if !defined(MBEDTLS_DES_ALT)
  46. // Regular implementation
  47. //
  48. /**
  49. * \brief DES context structure
  50. *
  51. * \warning DES is considered a weak cipher and its use constitutes a
  52. * security risk. We recommend considering stronger ciphers
  53. * instead.
  54. */
  55. typedef struct mbedtls_des_context
  56. {
  57. uint32_t sk[32]; /*!< DES subkeys */
  58. }
  59. mbedtls_des_context;
  60. /**
  61. * \brief Triple-DES context structure
  62. */
  63. typedef struct mbedtls_des3_context
  64. {
  65. uint32_t sk[96]; /*!< 3DES subkeys */
  66. }
  67. mbedtls_des3_context;
  68. #else /* MBEDTLS_DES_ALT */
  69. #include "des_alt.h"
  70. #endif /* MBEDTLS_DES_ALT */
  71. /**
  72. * \brief Initialize DES context
  73. *
  74. * \param ctx DES context to be initialized
  75. *
  76. * \warning DES is considered a weak cipher and its use constitutes a
  77. * security risk. We recommend considering stronger ciphers
  78. * instead.
  79. */
  80. void mbedtls_des_init( mbedtls_des_context *ctx );
  81. /**
  82. * \brief Clear DES context
  83. *
  84. * \param ctx DES context to be cleared
  85. *
  86. * \warning DES is considered a weak cipher and its use constitutes a
  87. * security risk. We recommend considering stronger ciphers
  88. * instead.
  89. */
  90. void mbedtls_des_free( mbedtls_des_context *ctx );
  91. /**
  92. * \brief Initialize Triple-DES context
  93. *
  94. * \param ctx DES3 context to be initialized
  95. */
  96. void mbedtls_des3_init( mbedtls_des3_context *ctx );
  97. /**
  98. * \brief Clear Triple-DES context
  99. *
  100. * \param ctx DES3 context to be cleared
  101. */
  102. void mbedtls_des3_free( mbedtls_des3_context *ctx );
  103. /**
  104. * \brief Set key parity on the given key to odd.
  105. *
  106. * DES keys are 56 bits long, but each byte is padded with
  107. * a parity bit to allow verification.
  108. *
  109. * \param key 8-byte secret key
  110. *
  111. * \warning DES is considered a weak cipher and its use constitutes a
  112. * security risk. We recommend considering stronger ciphers
  113. * instead.
  114. */
  115. void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  116. /**
  117. * \brief Check that key parity on the given key is odd.
  118. *
  119. * DES keys are 56 bits long, but each byte is padded with
  120. * a parity bit to allow verification.
  121. *
  122. * \param key 8-byte secret key
  123. *
  124. * \return 0 is parity was ok, 1 if parity was not correct.
  125. *
  126. * \warning DES is considered a weak cipher and its use constitutes a
  127. * security risk. We recommend considering stronger ciphers
  128. * instead.
  129. */
  130. int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  131. /**
  132. * \brief Check that key is not a weak or semi-weak DES key
  133. *
  134. * \param key 8-byte secret key
  135. *
  136. * \return 0 if no weak key was found, 1 if a weak key was identified.
  137. *
  138. * \warning DES is considered a weak cipher and its use constitutes a
  139. * security risk. We recommend considering stronger ciphers
  140. * instead.
  141. */
  142. int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  143. /**
  144. * \brief DES key schedule (56-bit, encryption)
  145. *
  146. * \param ctx DES context to be initialized
  147. * \param key 8-byte secret key
  148. *
  149. * \return 0
  150. *
  151. * \warning DES is considered a weak cipher and its use constitutes a
  152. * security risk. We recommend considering stronger ciphers
  153. * instead.
  154. */
  155. int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  156. /**
  157. * \brief DES key schedule (56-bit, decryption)
  158. *
  159. * \param ctx DES context to be initialized
  160. * \param key 8-byte secret key
  161. *
  162. * \return 0
  163. *
  164. * \warning DES is considered a weak cipher and its use constitutes a
  165. * security risk. We recommend considering stronger ciphers
  166. * instead.
  167. */
  168. int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  169. /**
  170. * \brief Triple-DES key schedule (112-bit, encryption)
  171. *
  172. * \param ctx 3DES context to be initialized
  173. * \param key 16-byte secret key
  174. *
  175. * \return 0
  176. */
  177. int mbedtls_des3_set2key_enc( mbedtls_des3_context *ctx,
  178. const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] );
  179. /**
  180. * \brief Triple-DES key schedule (112-bit, decryption)
  181. *
  182. * \param ctx 3DES context to be initialized
  183. * \param key 16-byte secret key
  184. *
  185. * \return 0
  186. */
  187. int mbedtls_des3_set2key_dec( mbedtls_des3_context *ctx,
  188. const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] );
  189. /**
  190. * \brief Triple-DES key schedule (168-bit, encryption)
  191. *
  192. * \param ctx 3DES context to be initialized
  193. * \param key 24-byte secret key
  194. *
  195. * \return 0
  196. */
  197. int mbedtls_des3_set3key_enc( mbedtls_des3_context *ctx,
  198. const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] );
  199. /**
  200. * \brief Triple-DES key schedule (168-bit, decryption)
  201. *
  202. * \param ctx 3DES context to be initialized
  203. * \param key 24-byte secret key
  204. *
  205. * \return 0
  206. */
  207. int mbedtls_des3_set3key_dec( mbedtls_des3_context *ctx,
  208. const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] );
  209. /**
  210. * \brief DES-ECB block encryption/decryption
  211. *
  212. * \param ctx DES context
  213. * \param input 64-bit input block
  214. * \param output 64-bit output block
  215. *
  216. * \return 0 if successful
  217. *
  218. * \warning DES is considered a weak cipher and its use constitutes a
  219. * security risk. We recommend considering stronger ciphers
  220. * instead.
  221. */
  222. int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx,
  223. const unsigned char input[8],
  224. unsigned char output[8] );
  225. #if defined(MBEDTLS_CIPHER_MODE_CBC)
  226. /**
  227. * \brief DES-CBC buffer encryption/decryption
  228. *
  229. * \note Upon exit, the content of the IV is updated so that you can
  230. * call the function same function again on the following
  231. * block(s) of data and get the same result as if it was
  232. * encrypted in one call. This allows a "streaming" usage.
  233. * If on the other hand you need to retain the contents of the
  234. * IV, you should either save it manually or use the cipher
  235. * module instead.
  236. *
  237. * \param ctx DES context
  238. * \param mode MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT
  239. * \param length length of the input data
  240. * \param iv initialization vector (updated after use)
  241. * \param input buffer holding the input data
  242. * \param output buffer holding the output data
  243. *
  244. * \warning DES is considered a weak cipher and its use constitutes a
  245. * security risk. We recommend considering stronger ciphers
  246. * instead.
  247. */
  248. int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx,
  249. int mode,
  250. size_t length,
  251. unsigned char iv[8],
  252. const unsigned char *input,
  253. unsigned char *output );
  254. #endif /* MBEDTLS_CIPHER_MODE_CBC */
  255. /**
  256. * \brief 3DES-ECB block encryption/decryption
  257. *
  258. * \param ctx 3DES context
  259. * \param input 64-bit input block
  260. * \param output 64-bit output block
  261. *
  262. * \return 0 if successful
  263. */
  264. int mbedtls_des3_crypt_ecb( mbedtls_des3_context *ctx,
  265. const unsigned char input[8],
  266. unsigned char output[8] );
  267. #if defined(MBEDTLS_CIPHER_MODE_CBC)
  268. /**
  269. * \brief 3DES-CBC buffer encryption/decryption
  270. *
  271. * \note Upon exit, the content of the IV is updated so that you can
  272. * call the function same function again on the following
  273. * block(s) of data and get the same result as if it was
  274. * encrypted in one call. This allows a "streaming" usage.
  275. * If on the other hand you need to retain the contents of the
  276. * IV, you should either save it manually or use the cipher
  277. * module instead.
  278. *
  279. * \param ctx 3DES context
  280. * \param mode MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT
  281. * \param length length of the input data
  282. * \param iv initialization vector (updated after use)
  283. * \param input buffer holding the input data
  284. * \param output buffer holding the output data
  285. *
  286. * \return 0 if successful, or MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH
  287. */
  288. int mbedtls_des3_crypt_cbc( mbedtls_des3_context *ctx,
  289. int mode,
  290. size_t length,
  291. unsigned char iv[8],
  292. const unsigned char *input,
  293. unsigned char *output );
  294. #endif /* MBEDTLS_CIPHER_MODE_CBC */
  295. /**
  296. * \brief Internal function for key expansion.
  297. * (Only exposed to allow overriding it,
  298. * see MBEDTLS_DES_SETKEY_ALT)
  299. *
  300. * \param SK Round keys
  301. * \param key Base key
  302. *
  303. * \warning DES is considered a weak cipher and its use constitutes a
  304. * security risk. We recommend considering stronger ciphers
  305. * instead.
  306. */
  307. void mbedtls_des_setkey( uint32_t SK[32],
  308. const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
  309. #if defined(MBEDTLS_SELF_TEST)
  310. /**
  311. * \brief Checkup routine
  312. *
  313. * \return 0 if successful, or 1 if the test failed
  314. */
  315. int mbedtls_des_self_test( int verbose );
  316. #endif /* MBEDTLS_SELF_TEST */
  317. #ifdef __cplusplus
  318. }
  319. #endif
  320. #endif /* des.h */