git.zerfleddert.de Git - proxmark3-svn/blob - common/mbedtls/des.h

   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: GPL-2.0
  13  *
  14  *  This program is free software; you can redistribute it and/or modify
  15  *  it under the terms of the GNU General Public License as published by
  16  *  the Free Software Foundation; either version 2 of the License, or
  17  *  (at your option) any later version.
  18  *
  19  *  This program is distributed in the hope that it will be useful,
  20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  *  GNU General Public License for more details.
  23  *
  24  *  You should have received a copy of the GNU General Public License along
  25  *  with this program; if not, write to the Free Software Foundation, Inc.,
  26  *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  27  *
  28  *  This file is part of mbed TLS (https://tls.mbed.org)
  29  *
  30  */
  31 #ifndef MBEDTLS_DES_H
  32 #define MBEDTLS_DES_H
  33
  34 #if !defined(MBEDTLS_CONFIG_FILE)
  35 #include "config.h"
  36 #else
  37 #include MBEDTLS_CONFIG_FILE
  38 #endif
  39
  40 #include <stddef.h>
  41 #include <stdint.h>
  42
  43 #define MBEDTLS_DES_ENCRYPT     1
  44 #define MBEDTLS_DES_DECRYPT     0
  45
  46 #define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH              -0x0032  /**< The data input has an invalid length. */
  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 */