4 * \brief DES block cipher
\r
6 * \warning DES is considered a weak cipher and its use constitutes a
\r
7 * security risk. We recommend considering stronger ciphers
\r
11 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
\r
12 * SPDX-License-Identifier: Apache-2.0
\r
14 * Licensed under the Apache License, Version 2.0 (the "License"); you may
\r
15 * not use this file except in compliance with the License.
\r
16 * You may obtain a copy of the License at
\r
18 * http://www.apache.org/licenses/LICENSE-2.0
\r
20 * Unless required by applicable law or agreed to in writing, software
\r
21 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
\r
22 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
23 * See the License for the specific language governing permissions and
\r
24 * limitations under the License.
\r
26 * This file is part of mbed TLS (https://tls.mbed.org)
\r
29 #ifndef MBEDTLS_DES_H
\r
30 #define MBEDTLS_DES_H
\r
32 #if !defined(MBEDTLS_CONFIG_FILE)
\r
35 #include MBEDTLS_CONFIG_FILE
\r
41 #define MBEDTLS_DES_ENCRYPT 1
\r
42 #define MBEDTLS_DES_DECRYPT 0
\r
44 #define MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH -0x0032 /**< The data input has an invalid length. */
\r
46 /* MBEDTLS_ERR_DES_HW_ACCEL_FAILED is deprecated and should not be used. */
\r
47 #define MBEDTLS_ERR_DES_HW_ACCEL_FAILED -0x0033 /**< DES hardware accelerator failed. */
\r
49 #define MBEDTLS_DES_KEY_SIZE 8
\r
55 #if !defined(MBEDTLS_DES_ALT)
\r
56 // Regular implementation
\r
60 * \brief DES context structure
\r
62 * \warning DES is considered a weak cipher and its use constitutes a
\r
63 * security risk. We recommend considering stronger ciphers
\r
66 typedef struct mbedtls_des_context
\r
68 uint32_t sk[32]; /*!< DES subkeys */
\r
70 mbedtls_des_context;
\r
73 * \brief Triple-DES context structure
\r
75 typedef struct mbedtls_des3_context
\r
77 uint32_t sk[96]; /*!< 3DES subkeys */
\r
79 mbedtls_des3_context;
\r
81 #else /* MBEDTLS_DES_ALT */
\r
82 #include "des_alt.h"
\r
83 #endif /* MBEDTLS_DES_ALT */
\r
86 * \brief Initialize DES context
\r
88 * \param ctx DES context to be initialized
\r
90 * \warning DES is considered a weak cipher and its use constitutes a
\r
91 * security risk. We recommend considering stronger ciphers
\r
94 void mbedtls_des_init( mbedtls_des_context *ctx );
\r
97 * \brief Clear DES context
\r
99 * \param ctx DES context to be cleared
\r
101 * \warning DES is considered a weak cipher and its use constitutes a
\r
102 * security risk. We recommend considering stronger ciphers
\r
105 void mbedtls_des_free( mbedtls_des_context *ctx );
\r
108 * \brief Initialize Triple-DES context
\r
110 * \param ctx DES3 context to be initialized
\r
112 void mbedtls_des3_init( mbedtls_des3_context *ctx );
\r
115 * \brief Clear Triple-DES context
\r
117 * \param ctx DES3 context to be cleared
\r
119 void mbedtls_des3_free( mbedtls_des3_context *ctx );
\r
122 * \brief Set key parity on the given key to odd.
\r
124 * DES keys are 56 bits long, but each byte is padded with
\r
125 * a parity bit to allow verification.
\r
127 * \param key 8-byte secret key
\r
129 * \warning DES is considered a weak cipher and its use constitutes a
\r
130 * security risk. We recommend considering stronger ciphers
\r
133 void mbedtls_des_key_set_parity( unsigned char key[MBEDTLS_DES_KEY_SIZE] );
\r
136 * \brief Check that key parity on the given key is odd.
\r
138 * DES keys are 56 bits long, but each byte is padded with
\r
139 * a parity bit to allow verification.
\r
141 * \param key 8-byte secret key
\r
143 * \return 0 is parity was ok, 1 if parity was not correct.
\r
145 * \warning DES is considered a weak cipher and its use constitutes a
\r
146 * security risk. We recommend considering stronger ciphers
\r
149 int mbedtls_des_key_check_key_parity( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
\r
152 * \brief Check that key is not a weak or semi-weak DES key
\r
154 * \param key 8-byte secret key
\r
156 * \return 0 if no weak key was found, 1 if a weak key was identified.
\r
158 * \warning DES is considered a weak cipher and its use constitutes a
\r
159 * security risk. We recommend considering stronger ciphers
\r
162 int mbedtls_des_key_check_weak( const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
\r
165 * \brief DES key schedule (56-bit, encryption)
\r
167 * \param ctx DES context to be initialized
\r
168 * \param key 8-byte secret key
\r
172 * \warning DES is considered a weak cipher and its use constitutes a
\r
173 * security risk. We recommend considering stronger ciphers
\r
176 int mbedtls_des_setkey_enc( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
\r
179 * \brief DES key schedule (56-bit, decryption)
\r
181 * \param ctx DES context to be initialized
\r
182 * \param key 8-byte secret key
\r
186 * \warning DES is considered a weak cipher and its use constitutes a
\r
187 * security risk. We recommend considering stronger ciphers
\r
190 int mbedtls_des_setkey_dec( mbedtls_des_context *ctx, const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
\r
193 * \brief Triple-DES key schedule (112-bit, encryption)
\r
195 * \param ctx 3DES context to be initialized
\r
196 * \param key 16-byte secret key
\r
200 int mbedtls_des3_set2key_enc( mbedtls_des3_context *ctx,
\r
201 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] );
\r
204 * \brief Triple-DES key schedule (112-bit, decryption)
\r
206 * \param ctx 3DES context to be initialized
\r
207 * \param key 16-byte secret key
\r
211 int mbedtls_des3_set2key_dec( mbedtls_des3_context *ctx,
\r
212 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 2] );
\r
215 * \brief Triple-DES key schedule (168-bit, encryption)
\r
217 * \param ctx 3DES context to be initialized
\r
218 * \param key 24-byte secret key
\r
222 int mbedtls_des3_set3key_enc( mbedtls_des3_context *ctx,
\r
223 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] );
\r
226 * \brief Triple-DES key schedule (168-bit, decryption)
\r
228 * \param ctx 3DES context to be initialized
\r
229 * \param key 24-byte secret key
\r
233 int mbedtls_des3_set3key_dec( mbedtls_des3_context *ctx,
\r
234 const unsigned char key[MBEDTLS_DES_KEY_SIZE * 3] );
\r
237 * \brief DES-ECB block encryption/decryption
\r
239 * \param ctx DES context
\r
240 * \param input 64-bit input block
\r
241 * \param output 64-bit output block
\r
243 * \return 0 if successful
\r
245 * \warning DES is considered a weak cipher and its use constitutes a
\r
246 * security risk. We recommend considering stronger ciphers
\r
249 int mbedtls_des_crypt_ecb( mbedtls_des_context *ctx,
\r
250 const unsigned char input[8],
\r
251 unsigned char output[8] );
\r
253 #if defined(MBEDTLS_CIPHER_MODE_CBC)
\r
255 * \brief DES-CBC buffer encryption/decryption
\r
257 * \note Upon exit, the content of the IV is updated so that you can
\r
258 * call the function same function again on the following
\r
259 * block(s) of data and get the same result as if it was
\r
260 * encrypted in one call. This allows a "streaming" usage.
\r
261 * If on the other hand you need to retain the contents of the
\r
262 * IV, you should either save it manually or use the cipher
\r
265 * \param ctx DES context
\r
266 * \param mode MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT
\r
267 * \param length length of the input data
\r
268 * \param iv initialization vector (updated after use)
\r
269 * \param input buffer holding the input data
\r
270 * \param output buffer holding the output data
\r
272 * \warning DES is considered a weak cipher and its use constitutes a
\r
273 * security risk. We recommend considering stronger ciphers
\r
276 int mbedtls_des_crypt_cbc( mbedtls_des_context *ctx,
\r
279 unsigned char iv[8],
\r
280 const unsigned char *input,
\r
281 unsigned char *output );
\r
282 #endif /* MBEDTLS_CIPHER_MODE_CBC */
\r
285 * \brief 3DES-ECB block encryption/decryption
\r
287 * \param ctx 3DES context
\r
288 * \param input 64-bit input block
\r
289 * \param output 64-bit output block
\r
291 * \return 0 if successful
\r
293 int mbedtls_des3_crypt_ecb( mbedtls_des3_context *ctx,
\r
294 const unsigned char input[8],
\r
295 unsigned char output[8] );
\r
297 #if defined(MBEDTLS_CIPHER_MODE_CBC)
\r
299 * \brief 3DES-CBC buffer encryption/decryption
\r
301 * \note Upon exit, the content of the IV is updated so that you can
\r
302 * call the function same function again on the following
\r
303 * block(s) of data and get the same result as if it was
\r
304 * encrypted in one call. This allows a "streaming" usage.
\r
305 * If on the other hand you need to retain the contents of the
\r
306 * IV, you should either save it manually or use the cipher
\r
309 * \param ctx 3DES context
\r
310 * \param mode MBEDTLS_DES_ENCRYPT or MBEDTLS_DES_DECRYPT
\r
311 * \param length length of the input data
\r
312 * \param iv initialization vector (updated after use)
\r
313 * \param input buffer holding the input data
\r
314 * \param output buffer holding the output data
\r
316 * \return 0 if successful, or MBEDTLS_ERR_DES_INVALID_INPUT_LENGTH
\r
318 int mbedtls_des3_crypt_cbc( mbedtls_des3_context *ctx,
\r
321 unsigned char iv[8],
\r
322 const unsigned char *input,
\r
323 unsigned char *output );
\r
324 #endif /* MBEDTLS_CIPHER_MODE_CBC */
\r
327 * \brief Internal function for key expansion.
\r
328 * (Only exposed to allow overriding it,
\r
329 * see MBEDTLS_DES_SETKEY_ALT)
\r
331 * \param SK Round keys
\r
332 * \param key Base key
\r
334 * \warning DES is considered a weak cipher and its use constitutes a
\r
335 * security risk. We recommend considering stronger ciphers
\r
338 void mbedtls_des_setkey( uint32_t SK[32],
\r
339 const unsigned char key[MBEDTLS_DES_KEY_SIZE] );
\r
341 #if defined(MBEDTLS_SELF_TEST)
\r
344 * \brief Checkup routine
\r
346 * \return 0 if successful, or 1 if the test failed
\r
348 int mbedtls_des_self_test( int verbose );
\r
350 #endif /* MBEDTLS_SELF_TEST */
\r