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 OR GPL-2.0-or-later 13 * 14 * This file is provided under the Apache License 2.0, or the 15 * GNU General Public License v2.0 or later. 16 * 17 * ********** 18 * Apache License 2.0: 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); you may 21 * not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 28 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 * 32 * ********** 33 * 34 * ********** 35 * GNU General Public License v2.0 or later: 36 * 37 * This program is free software; you can redistribute it and/or modify 38 * it under the terms of the GNU General Public License as published by 39 * the Free Software Foundation; either version 2 of the License, or 40 * (at your option) any later version. 41 * 42 * This program is distributed in the hope that it will be useful, 43 * but WITHOUT ANY WARRANTY; without even the implied warranty of 44 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 45 * GNU General Public License for more details. 46 * 47 * You should have received a copy of the GNU General Public License along 48 * with this program; if not, write to the Free Software Foundation, Inc., 49 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 50 * 51 * ********** 52 * 53 */ 54 #ifndef MBEDTLS_DES_H 55 #define MBEDTLS_DES_H 56 57 #if !defined(MBEDTLS_CONFIG_FILE) 58 #include "config.h" 59 #else 60 #include MBEDTLS_CONFIG_FILE 61 #endif 62 63 #include <stddef.h> 64 #include <stdint.h> 65 66 #define MBEDTLS_DES_ENCRYPT 1 67 #define MBEDTLS_DES_DECRYPT 0 68 69 #define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH -0x0032 /**< The data input has an invalid length. */ 70 71 /* MBEDTLS_ERR_DES_HW_ACCEL_FAILED is deprecated and should not be used. */ 72 #define MBEDTLS_ERR_DES_HW_ACCEL_FAILED -0x0033 /**< DES hardware accelerator failed. */ 73 74 #define MBEDTLS_DES_KEY_SIZE 8 75 76 #ifdef __cplusplus 77 extern "C" { 78 #endif 79 80 #if !defined(MBEDTLS_DES_ALT) 81 // Regular implementation 82 // 83 84 /** 85 * \brief DES context structure 86 * 87 * \warning DES is considered a weak cipher and its use constitutes a 88 * security risk. We recommend considering stronger ciphers 89 * instead. 90 */ 91 typedef struct mbedtls_des_context 92 { 93 uint32_t sk[32]; /*!< DES subkeys */ 94 } 95 mbedtls_des_context; 96 97 /** 98 * \brief Triple-DES context structure 99 */ 100 typedef struct mbedtls_des3_context 101 { 102 uint32_t sk[96]; /*!< 3DES subkeys */ 103 } 104 mbedtls_des3_context; 105 106 #else /* MBEDTLS_DES_ALT */ 107 #include "des_alt.h" 108 #endif /* MBEDTLS_DES_ALT */ 109 110 /** 111 * \brief Initialize DES context 112 * 113 * \param ctx DES context to be initialized 114 * 115 * \warning DES is considered a weak cipher and its use constitutes a 116 * security risk. We recommend considering stronger ciphers 117 * instead. 118 */ 119 void mbedtls_des_init( mbedtls_des_context *ctx ); 120 121 /** 122 * \brief Clear DES context 123 * 124 * \param ctx DES context to be cleared 125 * 126 * \warning DES is considered a weak cipher and its use constitutes a 127 * security risk. We recommend considering stronger ciphers 128 * instead. 129 */ 130 void mbedtls_des_free( mbedtls_des_context *ctx ); 131 132 /** 133 * \brief Initialize Triple-DES context 134 * 135 * \param ctx DES3 context to be initialized 136 */ 137 void mbedtls_des3_init( mbedtls_des3_context *ctx ); 138 139 /** 140 * \brief Clear Triple-DES context 141 * 142 * \param ctx DES3 context to be cleared 143 */ 144 void mbedtls_des3_free( mbedtls_des3_context *ctx ); 145 146 /** 147 * \brief Set key parity on the given key to odd. 148 * 149 * DES keys are 56 bits long, but each byte is padded with 150 * a parity bit to allow verification. 151 * 152 * \param key 8-byte secret key 153 * 154 * \warning DES is considered a weak cipher and its use constitutes a 155 * security risk. We recommend considering stronger ciphers 156 * instead. 157 */ 158 void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] ); 159 160 /** 161 * \brief Check that key parity on the given key is odd. 162 * 163 * DES keys are 56 bits long, but each byte is padded with 164 * a parity bit to allow verification. 165 * 166 * \param key 8-byte secret key 167 * 168 * \return 0 is parity was ok, 1 if parity was not correct. 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_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); 175 176 /** 177 * \brief Check that key is not a weak or semi-weak DES key 178 * 179 * \param key 8-byte secret key 180 * 181 * \return 0 if no weak key was found, 1 if a weak key was identified. 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 int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); 188 189 /** 190 * \brief DES key schedule (56-bit, encryption) 191 * 192 * \param ctx DES context to be initialized 193 * \param key 8-byte secret key 194 * 195 * \return 0 196 * 197 * \warning DES is considered a weak cipher and its use constitutes a 198 * security risk. We recommend considering stronger ciphers 199 * instead. 200 */ 201 int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); 202 203 /** 204 * \brief DES key schedule (56-bit, decryption) 205 * 206 * \param ctx DES context to be initialized 207 * \param key 8-byte secret key 208 * 209 * \return 0 210 * 211 * \warning DES is considered a weak cipher and its use constitutes a 212 * security risk. We recommend considering stronger ciphers 213 * instead. 214 */ 215 int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); 216 217 /** 218 * \brief Triple-DES key schedule (112-bit, encryption) 219 * 220 * \param ctx 3DES context to be initialized 221 * \param key 16-byte secret key 222 * 223 * \return 0 224 */ 225 int mbedtls_des3_set2key_enc( mbedtls_des3_context *ctx, 226 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] ); 227 228 /** 229 * \brief Triple-DES key schedule (112-bit, decryption) 230 * 231 * \param ctx 3DES context to be initialized 232 * \param key 16-byte secret key 233 * 234 * \return 0 235 */ 236 int mbedtls_des3_set2key_dec( mbedtls_des3_context *ctx, 237 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] ); 238 239 /** 240 * \brief Triple-DES key schedule (168-bit, encryption) 241 * 242 * \param ctx 3DES context to be initialized 243 * \param key 24-byte secret key 244 * 245 * \return 0 246 */ 247 int mbedtls_des3_set3key_enc( mbedtls_des3_context *ctx, 248 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] ); 249 250 /** 251 * \brief Triple-DES key schedule (168-bit, decryption) 252 * 253 * \param ctx 3DES context to be initialized 254 * \param key 24-byte secret key 255 * 256 * \return 0 257 */ 258 int mbedtls_des3_set3key_dec( mbedtls_des3_context *ctx, 259 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] ); 260 261 /** 262 * \brief DES-ECB block encryption/decryption 263 * 264 * \param ctx DES context 265 * \param input 64-bit input block 266 * \param output 64-bit output block 267 * 268 * \return 0 if successful 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_ecb( mbedtls_des_context *ctx, 275 const unsigned char input[8], 276 unsigned char output[8] ); 277 278 #if defined(MBEDTLS_CIPHER_MODE_CBC) 279 /** 280 * \brief DES-CBC buffer encryption/decryption 281 * 282 * \note Upon exit, the content of the IV is updated so that you can 283 * call the function same function again on the following 284 * block(s) of data and get the same result as if it was 285 * encrypted in one call. This allows a "streaming" usage. 286 * If on the other hand you need to retain the contents of the 287 * IV, you should either save it manually or use the cipher 288 * module instead. 289 * 290 * \param ctx DES context 291 * \param mode MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT 292 * \param length length of the input data 293 * \param iv initialization vector (updated after use) 294 * \param input buffer holding the input data 295 * \param output buffer holding the output data 296 * 297 * \warning DES is considered a weak cipher and its use constitutes a 298 * security risk. We recommend considering stronger ciphers 299 * instead. 300 */ 301 int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx, 302 int mode, 303 size_t length, 304 unsigned char iv[8], 305 const unsigned char *input, 306 unsigned char *output ); 307 #endif /* MBEDTLS_CIPHER_MODE_CBC */ 308 309 /** 310 * \brief 3DES-ECB block encryption/decryption 311 * 312 * \param ctx 3DES context 313 * \param input 64-bit input block 314 * \param output 64-bit output block 315 * 316 * \return 0 if successful 317 */ 318 int mbedtls_des3_crypt_ecb( mbedtls_des3_context *ctx, 319 const unsigned char input[8], 320 unsigned char output[8] ); 321 322 #if defined(MBEDTLS_CIPHER_MODE_CBC) 323 /** 324 * \brief 3DES-CBC buffer encryption/decryption 325 * 326 * \note Upon exit, the content of the IV is updated so that you can 327 * call the function same function again on the following 328 * block(s) of data and get the same result as if it was 329 * encrypted in one call. This allows a "streaming" usage. 330 * If on the other hand you need to retain the contents of the 331 * IV, you should either save it manually or use the cipher 332 * module instead. 333 * 334 * \param ctx 3DES context 335 * \param mode MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT 336 * \param length length of the input data 337 * \param iv initialization vector (updated after use) 338 * \param input buffer holding the input data 339 * \param output buffer holding the output data 340 * 341 * \return 0 if successful, or MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH 342 */ 343 int mbedtls_des3_crypt_cbc( mbedtls_des3_context *ctx, 344 int mode, 345 size_t length, 346 unsigned char iv[8], 347 const unsigned char *input, 348 unsigned char *output ); 349 #endif /* MBEDTLS_CIPHER_MODE_CBC */ 350 351 /** 352 * \brief Internal function for key expansion. 353 * (Only exposed to allow overriding it, 354 * see MBEDTLS_DES_SETKEY_ALT) 355 * 356 * \param SK Round keys 357 * \param key Base key 358 * 359 * \warning DES is considered a weak cipher and its use constitutes a 360 * security risk. We recommend considering stronger ciphers 361 * instead. 362 */ 363 void mbedtls_des_setkey( uint32_t SK[32], 364 const unsigned char key[MBEDTLS_DES_KEY_SIZE] ); 365 366 #if defined(MBEDTLS_SELF_TEST) 367 368 /** 369 * \brief Checkup routine 370 * 371 * \return 0 if successful, or 1 if the test failed 372 */ 373 int mbedtls_des_self_test( int verbose ); 374 375 #endif /* MBEDTLS_SELF_TEST */ 376 377 #ifdef __cplusplus 378 } 379 #endif 380 381 #endif /* des.h */ 382