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