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