des.h

00001 /**
00002  * \file des.h
00003  *
00004  * \brief DES block cipher
00005  *
00006  * \warning   DES is considered a weak cipher and its use constitutes a
00007  *            security risk. We recommend considering stronger ciphers
00008  *            instead.
00009  */
00010 /*
00011  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00012  *  SPDX-License-Identifier: Apache-2.0
00013  *
00014  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00015  *  not use this file except in compliance with the License.
00016  *  You may obtain a copy of the License at
00017  *
00018  *  http://www.apache.org/licenses/LICENSE-2.0
00019  *
00020  *  Unless required by applicable law or agreed to in writing, software
00021  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00022  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00023  *  See the License for the specific language governing permissions and
00024  *  limitations under the License.
00025  *
00026  *  This file is part of mbed TLS (https://tls.mbed.org)
00027  *
00028  */
00029 #ifndef MBEDTLS_DES_H
00030 #define MBEDTLS_DES_H
00031 
00032 #if !defined(MBEDTLS_CONFIG_FILE)
00033 #include "mbedtls/config.h"
00034 #else
00035 #include MBEDTLS_CONFIG_FILE
00036 #endif
00037 
00038 #include <stddef.h>
00039 #include <stdint.h>
00040 
00041 #define MBEDTLS_DES_ENCRYPT     1
00042 #define MBEDTLS_DES_DECRYPT     0
00043 
00044 #define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH              -0x0032  /**< The data input has an invalid length. */
00045 
00046 /* MBEDTLS_ERR_DES_HW_ACCEL_FAILED is deprecated and should not be used. */
00047 #define MBEDTLS_ERR_DES_HW_ACCEL_FAILED                   -0x0033  /**< DES hardware accelerator failed. */
00048 
00049 #define MBEDTLS_DES_KEY_SIZE    8
00050 
00051 #ifdef __cplusplus
00052 extern "C" {
00053 #endif
00054 
00055 #if !defined(MBEDTLS_DES_ALT)
00056 // Regular implementation
00057 //
00058 
00059 /**
00060  * \brief          DES context structure
00061  *
00062  * \warning        DES is considered a weak cipher and its use constitutes a
00063  *                 security risk. We recommend considering stronger ciphers
00064  *                 instead.
00065  */
00066 typedef struct mbedtls_des_context
00067 {
00068     uint32_t sk [32];            /*!<  DES subkeys       */
00069 }
00070 mbedtls_des_context;
00071 
00072 /**
00073  * \brief          Triple-DES context structure
00074  */
00075 typedef struct mbedtls_des3_context
00076 {
00077     uint32_t sk [96];            /*!<  3DES subkeys      */
00078 }
00079 mbedtls_des3_context;
00080 
00081 #else  /* MBEDTLS_DES_ALT */
00082 #include "des_alt.h"
00083 #endif /* MBEDTLS_DES_ALT */
00084 
00085 /**
00086  * \brief          Initialize DES context
00087  *
00088  * \param ctx      DES context to be initialized
00089  *
00090  * \warning        DES is considered a weak cipher and its use constitutes a
00091  *                 security risk. We recommend considering stronger ciphers
00092  *                 instead.
00093  */
00094 void mbedtls_des_init( mbedtls_des_context *ctx );
00095 
00096 /**
00097  * \brief          Clear DES context
00098  *
00099  * \param ctx      DES context to be cleared
00100  *
00101  * \warning        DES is considered a weak cipher and its use constitutes a
00102  *                 security risk. We recommend considering stronger ciphers
00103  *                 instead.
00104  */
00105 void mbedtls_des_free( mbedtls_des_context *ctx );
00106 
00107 /**
00108  * \brief          Initialize Triple-DES context
00109  *
00110  * \param ctx      DES3 context to be initialized
00111  */
00112 void mbedtls_des3_init( mbedtls_des3_context *ctx );
00113 
00114 /**
00115  * \brief          Clear Triple-DES context
00116  *
00117  * \param ctx      DES3 context to be cleared
00118  */
00119 void mbedtls_des3_free( mbedtls_des3_context *ctx );
00120 
00121 /**
00122  * \brief          Set key parity on the given key to odd.
00123  *
00124  *                 DES keys are 56 bits long, but each byte is padded with
00125  *                 a parity bit to allow verification.
00126  *
00127  * \param key      8-byte secret key
00128  *
00129  * \warning        DES is considered a weak cipher and its use constitutes a
00130  *                 security risk. We recommend considering stronger ciphers
00131  *                 instead.
00132  */
00133 void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] );
00134 
00135 /**
00136  * \brief          Check that key parity on the given key is odd.
00137  *
00138  *                 DES keys are 56 bits long, but each byte is padded with
00139  *                 a parity bit to allow verification.
00140  *
00141  * \param key      8-byte secret key
00142  *
00143  * \return         0 is parity was ok, 1 if parity was not correct.
00144  *
00145  * \warning        DES is considered a weak cipher and its use constitutes a
00146  *                 security risk. We recommend considering stronger ciphers
00147  *                 instead.
00148  */
00149 int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
00150 
00151 /**
00152  * \brief          Check that key is not a weak or semi-weak DES key
00153  *
00154  * \param key      8-byte secret key
00155  *
00156  * \return         0 if no weak key was found, 1 if a weak key was identified.
00157  *
00158  * \warning        DES is considered a weak cipher and its use constitutes a
00159  *                 security risk. We recommend considering stronger ciphers
00160  *                 instead.
00161  */
00162 int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
00163 
00164 /**
00165  * \brief          DES key schedule (56-bit, encryption)
00166  *
00167  * \param ctx      DES context to be initialized
00168  * \param key      8-byte secret key
00169  *
00170  * \return         0
00171  *
00172  * \warning        DES is considered a weak cipher and its use constitutes a
00173  *                 security risk. We recommend considering stronger ciphers
00174  *                 instead.
00175  */
00176 int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
00177 
00178 /**
00179  * \brief          DES key schedule (56-bit, decryption)
00180  *
00181  * \param ctx      DES context to be initialized
00182  * \param key      8-byte secret key
00183  *
00184  * \return         0
00185  *
00186  * \warning        DES is considered a weak cipher and its use constitutes a
00187  *                 security risk. We recommend considering stronger ciphers
00188  *                 instead.
00189  */
00190 int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
00191 
00192 /**
00193  * \brief          Triple-DES key schedule (112-bit, encryption)
00194  *
00195  * \param ctx      3DES context to be initialized
00196  * \param key      16-byte secret key
00197  *
00198  * \return         0
00199  */
00200 int mbedtls_des3_set2key_enc( mbedtls_des3_context *ctx,
00201                       const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] );
00202 
00203 /**
00204  * \brief          Triple-DES key schedule (112-bit, decryption)
00205  *
00206  * \param ctx      3DES context to be initialized
00207  * \param key      16-byte secret key
00208  *
00209  * \return         0
00210  */
00211 int mbedtls_des3_set2key_dec( mbedtls_des3_context *ctx,
00212                       const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] );
00213 
00214 /**
00215  * \brief          Triple-DES key schedule (168-bit, encryption)
00216  *
00217  * \param ctx      3DES context to be initialized
00218  * \param key      24-byte secret key
00219  *
00220  * \return         0
00221  */
00222 int mbedtls_des3_set3key_enc( mbedtls_des3_context *ctx,
00223                       const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] );
00224 
00225 /**
00226  * \brief          Triple-DES key schedule (168-bit, decryption)
00227  *
00228  * \param ctx      3DES context to be initialized
00229  * \param key      24-byte secret key
00230  *
00231  * \return         0
00232  */
00233 int mbedtls_des3_set3key_dec( mbedtls_des3_context *ctx,
00234                       const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] );
00235 
00236 /**
00237  * \brief          DES-ECB block encryption/decryption
00238  *
00239  * \param ctx      DES context
00240  * \param input    64-bit input block
00241  * \param output   64-bit output block
00242  *
00243  * \return         0 if successful
00244  *
00245  * \warning        DES is considered a weak cipher and its use constitutes a
00246  *                 security risk. We recommend considering stronger ciphers
00247  *                 instead.
00248  */
00249 int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx,
00250                     const unsigned char input[8],
00251                     unsigned char output[8] );
00252 
00253 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00254 /**
00255  * \brief          DES-CBC buffer encryption/decryption
00256  *
00257  * \note           Upon exit, the content of the IV is updated so that you can
00258  *                 call the function same function again on the following
00259  *                 block(s) of data and get the same result as if it was
00260  *                 encrypted in one call. This allows a "streaming" usage.
00261  *                 If on the other hand you need to retain the contents of the
00262  *                 IV, you should either save it manually or use the cipher
00263  *                 module instead.
00264  *
00265  * \param ctx      DES context
00266  * \param mode     MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT
00267  * \param length   length of the input data
00268  * \param iv       initialization vector (updated after use)
00269  * \param input    buffer holding the input data
00270  * \param output   buffer holding the output data
00271  *
00272  * \warning        DES is considered a weak cipher and its use constitutes a
00273  *                 security risk. We recommend considering stronger ciphers
00274  *                 instead.
00275  */
00276 int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx,
00277                     int mode,
00278                     size_t length,
00279                     unsigned char iv[8],
00280                     const unsigned char *input,
00281                     unsigned char *output );
00282 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00283 
00284 /**
00285  * \brief          3DES-ECB block encryption/decryption
00286  *
00287  * \param ctx      3DES context
00288  * \param input    64-bit input block
00289  * \param output   64-bit output block
00290  *
00291  * \return         0 if successful
00292  */
00293 int mbedtls_des3_crypt_ecb( mbedtls_des3_context *ctx,
00294                      const unsigned char input[8],
00295                      unsigned char output[8] );
00296 
00297 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00298 /**
00299  * \brief          3DES-CBC buffer encryption/decryption
00300  *
00301  * \note           Upon exit, the content of the IV is updated so that you can
00302  *                 call the function same function again on the following
00303  *                 block(s) of data and get the same result as if it was
00304  *                 encrypted in one call. This allows a "streaming" usage.
00305  *                 If on the other hand you need to retain the contents of the
00306  *                 IV, you should either save it manually or use the cipher
00307  *                 module instead.
00308  *
00309  * \param ctx      3DES context
00310  * \param mode     MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT
00311  * \param length   length of the input data
00312  * \param iv       initialization vector (updated after use)
00313  * \param input    buffer holding the input data
00314  * \param output   buffer holding the output data
00315  *
00316  * \return         0 if successful, or MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH
00317  */
00318 int mbedtls_des3_crypt_cbc( mbedtls_des3_context *ctx,
00319                      int mode,
00320                      size_t length,
00321                      unsigned char iv[8],
00322                      const unsigned char *input,
00323                      unsigned char *output );
00324 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00325 
00326 /**
00327  * \brief          Internal function for key expansion.
00328  *                 (Only exposed to allow overriding it,
00329  *                 see MBEDTLS_DES_SETKEY_ALT)
00330  *
00331  * \param SK       Round keys
00332  * \param key      Base key
00333  *
00334  * \warning        DES is considered a weak cipher and its use constitutes a
00335  *                 security risk. We recommend considering stronger ciphers
00336  *                 instead.
00337  */
00338 void mbedtls_des_setkey( uint32_t SK[32],
00339                          const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
00340 
00341 #if defined(MBEDTLS_SELF_TEST)
00342 
00343 /**
00344  * \brief          Checkup routine
00345  *
00346  * \return         0 if successful, or 1 if the test failed
00347  */
00348 int mbedtls_des_self_test( int verbose );
00349 
00350 #endif /* MBEDTLS_SELF_TEST */
00351 
00352 #ifdef __cplusplus
00353 }
00354 #endif
00355 
00356 #endif /* des.h */