1 /**
2 * \file cipher.h
3 *
4 * \brief This file contains an abstraction interface for use with the cipher
5 * primitives provided by the library. It provides a common interface to all of
6 * the available cipher operations.
7 *
8 * \author Adriaan de Jong <dejong@fox-it.com>
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_CIPHER_H
55 #define MBEDTLS_CIPHER_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 "platform_util.h"
65
66 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
67 #define MBEDTLS_CIPHER_MODE_AEAD
68 #endif
69
70 #if defined(MBEDTLS_CIPHER_MODE_CBC)
71 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
72 #endif
73
74 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
75 defined(MBEDTLS_CHACHA20_C)
76 #define MBEDTLS_CIPHER_MODE_STREAM
77 #endif
78
79 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
80 !defined(inline) && !defined(__cplusplus)
81 #define inline __inline
82 #endif
83
84 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
85 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters. */
86 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
87 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
88 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
89 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
90 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid. For example, because it was freed. */
91
92 /* MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED is deprecated and should not be used. */
93 #define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400 /**< Cipher hardware accelerator failed. */
94
95 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length. */
96 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length. */
97
98 #ifdef __cplusplus
99 extern "C" {
100 #endif
101
102 /**
103 * \brief Supported cipher types.
104 *
105 * \warning RC4 and DES are considered weak ciphers and their use
106 * constitutes a security risk. Arm recommends considering stronger
107 * ciphers instead.
108 */
109 typedef enum {
110 MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */
111 MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */
112 MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */
113 MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. */
114 MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. */
115 MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */
116 MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */
117 MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */
118 MBEDTLS_CIPHER_ID_ARIA, /**< The Aria cipher. */
119 MBEDTLS_CIPHER_ID_CHACHA20, /**< The ChaCha20 cipher. */
120 } mbedtls_cipher_id_t;
121
122 /**
123 * \brief Supported {cipher type, cipher mode} pairs.
124 *
125 * \warning RC4 and DES are considered weak ciphers and their use
126 * constitutes a security risk. Arm recommends considering stronger
127 * ciphers instead.
128 */
129 typedef enum {
130 MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */
131 MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */
132 MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */
133 MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */
134 MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */
135 MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */
136 MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */
137 MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */
138 MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */
139 MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */
140 MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */
141 MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */
142 MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */
143 MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */
144 MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */
145 MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */
146 MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */
147 MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */
148 MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */
149 MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */
150 MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */
151 MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */
152 MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */
153 MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */
154 MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */
155 MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */
156 MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */
157 MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */
158 MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */
159 MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */
160 MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */
161 MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */
162 MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. */
163 MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. */
164 MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. */
165 MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. */
166 MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. */
167 MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. */
168 MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */
169 MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */
170 MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */
171 MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */
172 MBEDTLS_CIPHER_ARC4_128, /**< RC4 cipher with 128-bit mode. */
173 MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */
174 MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */
175 MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */
176 MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */
177 MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */
178 MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */
179 MBEDTLS_CIPHER_ARIA_128_ECB, /**< Aria cipher with 128-bit key and ECB mode. */
180 MBEDTLS_CIPHER_ARIA_192_ECB, /**< Aria cipher with 192-bit key and ECB mode. */
181 MBEDTLS_CIPHER_ARIA_256_ECB, /**< Aria cipher with 256-bit key and ECB mode. */
182 MBEDTLS_CIPHER_ARIA_128_CBC, /**< Aria cipher with 128-bit key and CBC mode. */
183 MBEDTLS_CIPHER_ARIA_192_CBC, /**< Aria cipher with 192-bit key and CBC mode. */
184 MBEDTLS_CIPHER_ARIA_256_CBC, /**< Aria cipher with 256-bit key and CBC mode. */
185 MBEDTLS_CIPHER_ARIA_128_CFB128, /**< Aria cipher with 128-bit key and CFB-128 mode. */
186 MBEDTLS_CIPHER_ARIA_192_CFB128, /**< Aria cipher with 192-bit key and CFB-128 mode. */
187 MBEDTLS_CIPHER_ARIA_256_CFB128, /**< Aria cipher with 256-bit key and CFB-128 mode. */
188 MBEDTLS_CIPHER_ARIA_128_CTR, /**< Aria cipher with 128-bit key and CTR mode. */
189 MBEDTLS_CIPHER_ARIA_192_CTR, /**< Aria cipher with 192-bit key and CTR mode. */
190 MBEDTLS_CIPHER_ARIA_256_CTR, /**< Aria cipher with 256-bit key and CTR mode. */
191 MBEDTLS_CIPHER_ARIA_128_GCM, /**< Aria cipher with 128-bit key and GCM mode. */
192 MBEDTLS_CIPHER_ARIA_192_GCM, /**< Aria cipher with 192-bit key and GCM mode. */
193 MBEDTLS_CIPHER_ARIA_256_GCM, /**< Aria cipher with 256-bit key and GCM mode. */
194 MBEDTLS_CIPHER_ARIA_128_CCM, /**< Aria cipher with 128-bit key and CCM mode. */
195 MBEDTLS_CIPHER_ARIA_192_CCM, /**< Aria cipher with 192-bit key and CCM mode. */
196 MBEDTLS_CIPHER_ARIA_256_CCM, /**< Aria cipher with 256-bit key and CCM mode. */
197 MBEDTLS_CIPHER_AES_128_OFB, /**< AES 128-bit cipher in OFB mode. */
198 MBEDTLS_CIPHER_AES_192_OFB, /**< AES 192-bit cipher in OFB mode. */
199 MBEDTLS_CIPHER_AES_256_OFB, /**< AES 256-bit cipher in OFB mode. */
200 MBEDTLS_CIPHER_AES_128_XTS, /**< AES 128-bit cipher in XTS block mode. */
201 MBEDTLS_CIPHER_AES_256_XTS, /**< AES 256-bit cipher in XTS block mode. */
202 MBEDTLS_CIPHER_CHACHA20, /**< ChaCha20 stream cipher. */
203 MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< ChaCha20-Poly1305 AEAD cipher. */
204 } mbedtls_cipher_type_t;
205
206 /** Supported cipher modes. */
207 typedef enum {
208 MBEDTLS_MODE_NONE = 0, /**< None. */
209 MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */
210 MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */
211 MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */
212 MBEDTLS_MODE_OFB, /**< The OFB cipher mode. */
213 MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */
214 MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */
215 MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */
216 MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */
217 MBEDTLS_MODE_XTS, /**< The XTS cipher mode. */
218 MBEDTLS_MODE_CHACHAPOLY, /**< The ChaCha-Poly cipher mode. */
219 } mbedtls_cipher_mode_t;
220
221 /** Supported cipher padding types. */
222 typedef enum {
223 MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */
224 MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */
225 MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */
226 MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */
227 MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */
228 } mbedtls_cipher_padding_t;
229
230 /** Type of operation. */
231 typedef enum {
232 MBEDTLS_OPERATION_NONE = -1,
233 MBEDTLS_DECRYPT = 0,
234 MBEDTLS_ENCRYPT,
235 } mbedtls_operation_t;
236
237 enum {
238 /** Undefined key length. */
239 MBEDTLS_KEY_LENGTH_NONE = 0,
240 /** Key length, in bits (including parity), for DES keys. */
241 MBEDTLS_KEY_LENGTH_DES = 64,
242 /** Key length in bits, including parity, for DES in two-key EDE. */
243 MBEDTLS_KEY_LENGTH_DES_EDE = 128,
244 /** Key length in bits, including parity, for DES in three-key EDE. */
245 MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
246 };
247
248 /** Maximum length of any IV, in Bytes. */
249 #define MBEDTLS_MAX_IV_LENGTH 16
250 /** Maximum block size of any cipher, in Bytes. */
251 #define MBEDTLS_MAX_BLOCK_LENGTH 16
252
253 /**
254 * Base cipher information (opaque struct).
255 */
256 typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t;
257
258 /**
259 * CMAC context (opaque struct).
260 */
261 typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
262
263 /**
264 * Cipher information. Allows calling cipher functions
265 * in a generic way.
266 */
267 typedef struct mbedtls_cipher_info_t
268 {
269 /** Full cipher identifier. For example,
270 * MBEDTLS_CIPHER_AES_256_CBC.
271 */
272 mbedtls_cipher_type_t type;
273
274 /** The cipher mode. For example, MBEDTLS_MODE_CBC. */
275 mbedtls_cipher_mode_t mode;
276
277 /** The cipher key length, in bits. This is the
278 * default length for variable sized ciphers.
279 * Includes parity bits for ciphers like DES.
280 */
281 unsigned int key_bitlen;
282
283 /** Name of the cipher. */
284 const char * name;
285
286 /** IV or nonce size, in Bytes.
287 * For ciphers that accept variable IV sizes,
288 * this is the recommended size.
289 */
290 unsigned int iv_size;
291
292 /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and
293 * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the
294 * cipher supports variable IV or variable key sizes, respectively.
295 */
296 int flags;
297
298 /** The block size, in Bytes. */
299 unsigned int block_size;
300
301 /** Struct for base cipher information and functions. */
302 const mbedtls_cipher_base_t *base;
303
304 } mbedtls_cipher_info_t;
305
306 /**
307 * Generic cipher context.
308 */
309 typedef struct mbedtls_cipher_context_t
310 {
311 /** Information about the associated cipher. */
312 const mbedtls_cipher_info_t *cipher_info;
313
314 /** Key length to use. */
315 int key_bitlen;
316
317 /** Operation that the key of the context has been
318 * initialized for.
319 */
320 mbedtls_operation_t operation;
321
322 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
323 /** Padding functions to use, if relevant for
324 * the specific cipher mode.
325 */
326 void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
327 int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
328 #endif
329
330 /** Buffer for input that has not been processed yet. */
331 unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
332
333 /** Number of Bytes that have not been processed yet. */
334 size_t unprocessed_len;
335
336 /** Current IV or NONCE_COUNTER for CTR-mode, data unit (or sector) number
337 * for XTS-mode. */
338 unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
339
340 /** IV size in Bytes, for ciphers with variable-length IVs. */
341 size_t iv_size;
342
343 /** The cipher-specific context. */
344 void *cipher_ctx;
345
346 #if defined(MBEDTLS_CMAC_C)
347 /** CMAC-specific context. */
348 mbedtls_cmac_context_t *cmac_ctx;
349 #endif
350 } mbedtls_cipher_context_t;
351
352 /**
353 * \brief This function retrieves the list of ciphers supported by the generic
354 * cipher module.
355 *
356 * \return A statically-allocated array of ciphers. The last entry
357 * is zero.
358 */
359 const int *mbedtls_cipher_list( void );
360
361 /**
362 * \brief This function retrieves the cipher-information
363 * structure associated with the given cipher name.
364 *
365 * \param cipher_name Name of the cipher to search for. This must not be
366 * \c NULL.
367 *
368 * \return The cipher information structure associated with the
369 * given \p cipher_name.
370 * \return \c NULL if the associated cipher information is not found.
371 */
372 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
373
374 /**
375 * \brief This function retrieves the cipher-information
376 * structure associated with the given cipher type.
377 *
378 * \param cipher_type Type of the cipher to search for.
379 *
380 * \return The cipher information structure associated with the
381 * given \p cipher_type.
382 * \return \c NULL if the associated cipher information is not found.
383 */
384 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
385
386 /**
387 * \brief This function retrieves the cipher-information
388 * structure associated with the given cipher ID,
389 * key size and mode.
390 *
391 * \param cipher_id The ID of the cipher to search for. For example,
392 * #MBEDTLS_CIPHER_ID_AES.
393 * \param key_bitlen The length of the key in bits.
394 * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC.
395 *
396 * \return The cipher information structure associated with the
397 * given \p cipher_id.
398 * \return \c NULL if the associated cipher information is not found.
399 */
400 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
401 int key_bitlen,
402 const mbedtls_cipher_mode_t mode );
403
404 /**
405 * \brief This function initializes a \p cipher_context as NONE.
406 *
407 * \param ctx The context to be initialized. This must not be \c NULL.
408 */
409 void mbedtls_cipher_init( mbedtls_cipher_context_t *ctx );
410
411 /**
412 * \brief This function frees and clears the cipher-specific
413 * context of \p ctx. Freeing \p ctx itself remains the
414 * responsibility of the caller.
415 *
416 * \param ctx The context to be freed. If this is \c NULL, the
417 * function has no effect, otherwise this must point to an
418 * initialized context.
419 */
420 void mbedtls_cipher_free( mbedtls_cipher_context_t *ctx );
421
422
423 /**
424 * \brief This function initializes and fills the cipher-context
425 * structure with the appropriate values. It also clears
426 * the structure.
427 *
428 * \param ctx The context to initialize. This must be initialized.
429 * \param cipher_info The cipher to use.
430 *
431 * \return \c 0 on success.
432 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
433 * parameter-verification failure.
434 * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
435 * cipher-specific context fails.
436 *
437 * \internal Currently, the function also clears the structure.
438 * In future versions, the caller will be required to call
439 * mbedtls_cipher_init() on the structure first.
440 */
441 int mbedtls_cipher_setup( mbedtls_cipher_context_t *ctx,
442 const mbedtls_cipher_info_t *cipher_info );
443
444 /**
445 * \brief This function returns the block size of the given cipher.
446 *
447 * \param ctx The context of the cipher. This must be initialized.
448 *
449 * \return The block size of the underlying cipher.
450 * \return \c 0 if \p ctx has not been initialized.
451 */
mbedtls_cipher_get_block_size(const mbedtls_cipher_context_t * ctx)452 static inline unsigned int mbedtls_cipher_get_block_size(
453 const mbedtls_cipher_context_t *ctx )
454 {
455 MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
456 if( ctx->cipher_info == NULL )
457 return 0;
458
459 return ctx->cipher_info->block_size;
460 }
461
462 /**
463 * \brief This function returns the mode of operation for
464 * the cipher. For example, MBEDTLS_MODE_CBC.
465 *
466 * \param ctx The context of the cipher. This must be initialized.
467 *
468 * \return The mode of operation.
469 * \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized.
470 */
mbedtls_cipher_get_cipher_mode(const mbedtls_cipher_context_t * ctx)471 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(
472 const mbedtls_cipher_context_t *ctx )
473 {
474 MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, MBEDTLS_MODE_NONE );
475 if( ctx->cipher_info == NULL )
476 return MBEDTLS_MODE_NONE;
477
478 return ctx->cipher_info->mode;
479 }
480
481 /**
482 * \brief This function returns the size of the IV or nonce
483 * of the cipher, in Bytes.
484 *
485 * \param ctx The context of the cipher. This must be initialized.
486 *
487 * \return The recommended IV size if no IV has been set.
488 * \return \c 0 for ciphers not using an IV or a nonce.
489 * \return The actual size if an IV has been set.
490 */
mbedtls_cipher_get_iv_size(const mbedtls_cipher_context_t * ctx)491 static inline int mbedtls_cipher_get_iv_size(
492 const mbedtls_cipher_context_t *ctx )
493 {
494 MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
495 if( ctx->cipher_info == NULL )
496 return 0;
497
498 if( ctx->iv_size != 0 )
499 return (int) ctx->iv_size;
500
501 return (int) ctx->cipher_info->iv_size;
502 }
503
504 /**
505 * \brief This function returns the type of the given cipher.
506 *
507 * \param ctx The context of the cipher. This must be initialized.
508 *
509 * \return The type of the cipher.
510 * \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized.
511 */
mbedtls_cipher_get_type(const mbedtls_cipher_context_t * ctx)512 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type(
513 const mbedtls_cipher_context_t *ctx )
514 {
515 MBEDTLS_INTERNAL_VALIDATE_RET(
516 ctx != NULL, MBEDTLS_CIPHER_NONE );
517 if( ctx->cipher_info == NULL )
518 return MBEDTLS_CIPHER_NONE;
519
520 return ctx->cipher_info->type;
521 }
522
523 /**
524 * \brief This function returns the name of the given cipher
525 * as a string.
526 *
527 * \param ctx The context of the cipher. This must be initialized.
528 *
529 * \return The name of the cipher.
530 * \return NULL if \p ctx has not been not initialized.
531 */
mbedtls_cipher_get_name(const mbedtls_cipher_context_t * ctx)532 static inline const char *mbedtls_cipher_get_name(
533 const mbedtls_cipher_context_t *ctx )
534 {
535 MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
536 if( ctx->cipher_info == NULL )
537 return 0;
538
539 return ctx->cipher_info->name;
540 }
541
542 /**
543 * \brief This function returns the key length of the cipher.
544 *
545 * \param ctx The context of the cipher. This must be initialized.
546 *
547 * \return The key length of the cipher in bits.
548 * \return #MBEDTLS_KEY_LENGTH_NONE if ctx \p has not been
549 * initialized.
550 */
mbedtls_cipher_get_key_bitlen(const mbedtls_cipher_context_t * ctx)551 static inline int mbedtls_cipher_get_key_bitlen(
552 const mbedtls_cipher_context_t *ctx )
553 {
554 MBEDTLS_INTERNAL_VALIDATE_RET(
555 ctx != NULL, MBEDTLS_KEY_LENGTH_NONE );
556 if( ctx->cipher_info == NULL )
557 return MBEDTLS_KEY_LENGTH_NONE;
558
559 return (int) ctx->cipher_info->key_bitlen;
560 }
561
562 /**
563 * \brief This function returns the operation of the given cipher.
564 *
565 * \param ctx The context of the cipher. This must be initialized.
566 *
567 * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
568 * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized.
569 */
mbedtls_cipher_get_operation(const mbedtls_cipher_context_t * ctx)570 static inline mbedtls_operation_t mbedtls_cipher_get_operation(
571 const mbedtls_cipher_context_t *ctx )
572 {
573 MBEDTLS_INTERNAL_VALIDATE_RET(
574 ctx != NULL, MBEDTLS_OPERATION_NONE );
575 if( ctx->cipher_info == NULL )
576 return MBEDTLS_OPERATION_NONE;
577
578 return ctx->operation;
579 }
580
581 /**
582 * \brief This function sets the key to use with the given context.
583 *
584 * \param ctx The generic cipher context. This must be initialized and
585 * bound to a cipher information structure.
586 * \param key The key to use. This must be a readable buffer of at
587 * least \p key_bitlen Bits.
588 * \param key_bitlen The key length to use, in Bits.
589 * \param operation The operation that the key will be used for:
590 * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
591 *
592 * \return \c 0 on success.
593 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
594 * parameter-verification failure.
595 * \return A cipher-specific error code on failure.
596 */
597 int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx,
598 const unsigned char *key,
599 int key_bitlen,
600 const mbedtls_operation_t operation );
601
602 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
603 /**
604 * \brief This function sets the padding mode, for cipher modes
605 * that use padding.
606 *
607 * The default passing mode is PKCS7 padding.
608 *
609 * \param ctx The generic cipher context. This must be initialized and
610 * bound to a cipher information structure.
611 * \param mode The padding mode.
612 *
613 * \return \c 0 on success.
614 * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
615 * if the selected padding mode is not supported.
616 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
617 * does not support padding.
618 */
619 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx,
620 mbedtls_cipher_padding_t mode );
621 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
622
623 /**
624 * \brief This function sets the initialization vector (IV)
625 * or nonce.
626 *
627 * \note Some ciphers do not use IVs nor nonce. For these
628 * ciphers, this function has no effect.
629 *
630 * \param ctx The generic cipher context. This must be initialized and
631 * bound to a cipher information structure.
632 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This
633 * must be a readable buffer of at least \p iv_len Bytes.
634 * \param iv_len The IV length for ciphers with variable-size IV.
635 * This parameter is discarded by ciphers with fixed-size IV.
636 *
637 * \return \c 0 on success.
638 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
639 * parameter-verification failure.
640 */
641 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t *ctx,
642 const unsigned char *iv,
643 size_t iv_len );
644
645 /**
646 * \brief This function resets the cipher state.
647 *
648 * \param ctx The generic cipher context. This must be initialized.
649 *
650 * \return \c 0 on success.
651 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
652 * parameter-verification failure.
653 */
654 int mbedtls_cipher_reset( mbedtls_cipher_context_t *ctx );
655
656 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
657 /**
658 * \brief This function adds additional data for AEAD ciphers.
659 * Currently supported with GCM and ChaCha20+Poly1305.
660 * This must be called exactly once, after
661 * mbedtls_cipher_reset().
662 *
663 * \param ctx The generic cipher context. This must be initialized.
664 * \param ad The additional data to use. This must be a readable
665 * buffer of at least \p ad_len Bytes.
666 * \param ad_len the Length of \p ad Bytes.
667 *
668 * \return \c 0 on success.
669 * \return A specific error code on failure.
670 */
671 int mbedtls_cipher_update_ad( mbedtls_cipher_context_t *ctx,
672 const unsigned char *ad, size_t ad_len );
673 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
674
675 /**
676 * \brief The generic cipher update function. It encrypts or
677 * decrypts using the given cipher context. Writes as
678 * many block-sized blocks of data as possible to output.
679 * Any data that cannot be written immediately is either
680 * added to the next block, or flushed when
681 * mbedtls_cipher_finish() is called.
682 * Exception: For MBEDTLS_MODE_ECB, expects a single block
683 * in size. For example, 16 Bytes for AES.
684 *
685 * \note If the underlying cipher is used in GCM mode, all calls
686 * to this function, except for the last one before
687 * mbedtls_cipher_finish(), must have \p ilen as a
688 * multiple of the block size of the cipher.
689 *
690 * \param ctx The generic cipher context. This must be initialized and
691 * bound to a key.
692 * \param input The buffer holding the input data. This must be a
693 * readable buffer of at least \p ilen Bytes.
694 * \param ilen The length of the input data.
695 * \param output The buffer for the output data. This must be able to
696 * hold at least `ilen + block_size`. This must not be the
697 * same buffer as \p input.
698 * \param olen The length of the output data, to be updated with the
699 * actual number of Bytes written. This must not be
700 * \c NULL.
701 *
702 * \return \c 0 on success.
703 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
704 * parameter-verification failure.
705 * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
706 * unsupported mode for a cipher.
707 * \return A cipher-specific error code on failure.
708 */
709 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
710 size_t ilen, unsigned char *output, size_t *olen );
711
712 /**
713 * \brief The generic cipher finalization function. If data still
714 * needs to be flushed from an incomplete block, the data
715 * contained in it is padded to the size of
716 * the last block, and written to the \p output buffer.
717 *
718 * \param ctx The generic cipher context. This must be initialized and
719 * bound to a key.
720 * \param output The buffer to write data to. This needs to be a writable
721 * buffer of at least \p block_size Bytes.
722 * \param olen The length of the data written to the \p output buffer.
723 * This may not be \c NULL.
724 *
725 * \return \c 0 on success.
726 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
727 * parameter-verification failure.
728 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
729 * expecting a full block but not receiving one.
730 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
731 * while decrypting.
732 * \return A cipher-specific error code on failure.
733 */
734 int mbedtls_cipher_finish( mbedtls_cipher_context_t *ctx,
735 unsigned char *output, size_t *olen );
736
737 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
738 /**
739 * \brief This function writes a tag for AEAD ciphers.
740 * Currently supported with GCM and ChaCha20+Poly1305.
741 * This must be called after mbedtls_cipher_finish().
742 *
743 * \param ctx The generic cipher context. This must be initialized,
744 * bound to a key, and have just completed a cipher
745 * operation through mbedtls_cipher_finish() the tag for
746 * which should be written.
747 * \param tag The buffer to write the tag to. This must be a writable
748 * buffer of at least \p tag_len Bytes.
749 * \param tag_len The length of the tag to write.
750 *
751 * \return \c 0 on success.
752 * \return A specific error code on failure.
753 */
754 int mbedtls_cipher_write_tag( mbedtls_cipher_context_t *ctx,
755 unsigned char *tag, size_t tag_len );
756
757 /**
758 * \brief This function checks the tag for AEAD ciphers.
759 * Currently supported with GCM and ChaCha20+Poly1305.
760 * This must be called after mbedtls_cipher_finish().
761 *
762 * \param ctx The generic cipher context. This must be initialized.
763 * \param tag The buffer holding the tag. This must be a readable
764 * buffer of at least \p tag_len Bytes.
765 * \param tag_len The length of the tag to check.
766 *
767 * \return \c 0 on success.
768 * \return A specific error code on failure.
769 */
770 int mbedtls_cipher_check_tag( mbedtls_cipher_context_t *ctx,
771 const unsigned char *tag, size_t tag_len );
772 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
773
774 /**
775 * \brief The generic all-in-one encryption/decryption function,
776 * for all ciphers except AEAD constructs.
777 *
778 * \param ctx The generic cipher context. This must be initialized.
779 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
780 * This must be a readable buffer of at least \p iv_len
781 * Bytes.
782 * \param iv_len The IV length for ciphers with variable-size IV.
783 * This parameter is discarded by ciphers with fixed-size
784 * IV.
785 * \param input The buffer holding the input data. This must be a
786 * readable buffer of at least \p ilen Bytes.
787 * \param ilen The length of the input data in Bytes.
788 * \param output The buffer for the output data. This must be able to
789 * hold at least `ilen + block_size`. This must not be the
790 * same buffer as \p input.
791 * \param olen The length of the output data, to be updated with the
792 * actual number of Bytes written. This must not be
793 * \c NULL.
794 *
795 * \note Some ciphers do not use IVs nor nonce. For these
796 * ciphers, use \p iv = NULL and \p iv_len = 0.
797 *
798 * \return \c 0 on success.
799 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
800 * parameter-verification failure.
801 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
802 * expecting a full block but not receiving one.
803 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
804 * while decrypting.
805 * \return A cipher-specific error code on failure.
806 */
807 int mbedtls_cipher_crypt( mbedtls_cipher_context_t *ctx,
808 const unsigned char *iv, size_t iv_len,
809 const unsigned char *input, size_t ilen,
810 unsigned char *output, size_t *olen );
811
812 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
813 /**
814 * \brief The generic autenticated encryption (AEAD) function.
815 *
816 * \param ctx The generic cipher context. This must be initialized and
817 * bound to a key.
818 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
819 * This must be a readable buffer of at least \p iv_len
820 * Bytes.
821 * \param iv_len The IV length for ciphers with variable-size IV.
822 * This parameter is discarded by ciphers with fixed-size IV.
823 * \param ad The additional data to authenticate. This must be a
824 * readable buffer of at least \p ad_len Bytes.
825 * \param ad_len The length of \p ad.
826 * \param input The buffer holding the input data. This must be a
827 * readable buffer of at least \p ilen Bytes.
828 * \param ilen The length of the input data.
829 * \param output The buffer for the output data. This must be able to
830 * hold at least \p ilen Bytes.
831 * \param olen The length of the output data, to be updated with the
832 * actual number of Bytes written. This must not be
833 * \c NULL.
834 * \param tag The buffer for the authentication tag. This must be a
835 * writable buffer of at least \p tag_len Bytes.
836 * \param tag_len The desired length of the authentication tag.
837 *
838 * \return \c 0 on success.
839 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
840 * parameter-verification failure.
841 * \return A cipher-specific error code on failure.
842 */
843 int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t *ctx,
844 const unsigned char *iv, size_t iv_len,
845 const unsigned char *ad, size_t ad_len,
846 const unsigned char *input, size_t ilen,
847 unsigned char *output, size_t *olen,
848 unsigned char *tag, size_t tag_len );
849
850 /**
851 * \brief The generic autenticated decryption (AEAD) function.
852 *
853 * \note If the data is not authentic, then the output buffer
854 * is zeroed out to prevent the unauthentic plaintext being
855 * used, making this interface safer.
856 *
857 * \param ctx The generic cipher context. This must be initialized and
858 * and bound to a key.
859 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
860 * This must be a readable buffer of at least \p iv_len
861 * Bytes.
862 * \param iv_len The IV length for ciphers with variable-size IV.
863 * This parameter is discarded by ciphers with fixed-size IV.
864 * \param ad The additional data to be authenticated. This must be a
865 * readable buffer of at least \p ad_len Bytes.
866 * \param ad_len The length of \p ad.
867 * \param input The buffer holding the input data. This must be a
868 * readable buffer of at least \p ilen Bytes.
869 * \param ilen The length of the input data.
870 * \param output The buffer for the output data.
871 * This must be able to hold at least \p ilen Bytes.
872 * \param olen The length of the output data, to be updated with the
873 * actual number of Bytes written. This must not be
874 * \c NULL.
875 * \param tag The buffer holding the authentication tag. This must be
876 * a readable buffer of at least \p tag_len Bytes.
877 * \param tag_len The length of the authentication tag.
878 *
879 * \return \c 0 on success.
880 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
881 * parameter-verification failure.
882 * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
883 * \return A cipher-specific error code on failure.
884 */
885 int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t *ctx,
886 const unsigned char *iv, size_t iv_len,
887 const unsigned char *ad, size_t ad_len,
888 const unsigned char *input, size_t ilen,
889 unsigned char *output, size_t *olen,
890 const unsigned char *tag, size_t tag_len );
891 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
892
893 #ifdef __cplusplus
894 }
895 #endif
896
897 #endif /* MBEDTLS_CIPHER_H */
898