des.h 11 KB

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