des.h 11 KB

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