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