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