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