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