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