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
15 #ifndef MBEDTLS_CIPHER_H
16 #define MBEDTLS_CIPHER_H
17
18 #if !defined(MBEDTLS_CONFIG_FILE)
19 #include "mbedtls/config.h"
20 #else
21 #include MBEDTLS_CONFIG_FILE
22 #endif
23
24 #include <stddef.h>
25 #include "mbedtls/platform_util.h"
26
27 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
28 #define MBEDTLS_CIPHER_MODE_AEAD
29 #endif
30
31 #if defined(MBEDTLS_CIPHER_MODE_CBC)
32 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
33 #endif
34
35 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
36 defined(MBEDTLS_CHACHA20_C)
37 #define MBEDTLS_CIPHER_MODE_STREAM
38 #endif
39
40 #if (defined(__ARMCC_VERSION) || defined(_MSC_VER)) && \
41 !defined(inline) && !defined(__cplusplus)
42 #define inline __inline
43 #endif
44
45 /** The selected feature is not available. */
46 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
47 /** Bad input parameters. */
48 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100
49 /** Failed to allocate memory. */
50 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180
51 /** Input data contains invalid padding and is rejected. */
52 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200
53 /** Decryption of block requires a full block. */
54 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
55 /** Authentication failed (for AEAD modes). */
56 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300
57 /** The context is invalid. For example, because it was freed. */
58 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380
59
60 /* MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED is deprecated and should not be used. */
61 /** Cipher hardware accelerator failed. */
62 #define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400
63
64 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length. */
65 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length. */
66
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70
71 /**
72 * \brief Supported cipher types.
73 *
74 * \warning RC4 and DES/3DES are considered weak ciphers and their use
75 * constitutes a security risk. We recommend considering stronger
76 * ciphers instead.
77 */
78 typedef enum {
79 MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */
80 MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */
81 MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */
82 MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. \warning DES is considered weak. */
83 MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. \warning 3DES is considered weak. */
84 MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */
85 MBEDTLS_CIPHER_ID_BLOWFISH, /**< The Blowfish cipher. */
86 MBEDTLS_CIPHER_ID_ARC4, /**< The RC4 cipher. */
87 MBEDTLS_CIPHER_ID_ARIA, /**< The Aria cipher. */
88 MBEDTLS_CIPHER_ID_CHACHA20, /**< The ChaCha20 cipher. */
89 } mbedtls_cipher_id_t;
90
91 /**
92 * \brief Supported {cipher type, cipher mode} pairs.
93 *
94 * \warning RC4 and DES/3DES are considered weak ciphers and their use
95 * constitutes a security risk. We recommend considering stronger
96 * ciphers instead.
97 */
98 typedef enum {
99 MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */
100 MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */
101 MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */
102 MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */
103 MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */
104 MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */
105 MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */
106 MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */
107 MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */
108 MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */
109 MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */
110 MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */
111 MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */
112 MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */
113 MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */
114 MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */
115 MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */
116 MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */
117 MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */
118 MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */
119 MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */
120 MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */
121 MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */
122 MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */
123 MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */
124 MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */
125 MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */
126 MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */
127 MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */
128 MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */
129 MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */
130 MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */
131 MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. \warning DES is considered weak. */
132 MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. \warning DES is considered weak. */
133 MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. \warning 3DES is considered weak. */
134 MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. \warning 3DES is considered weak. */
135 MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. \warning 3DES is considered weak. */
136 MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. \warning 3DES is considered weak. */
137 MBEDTLS_CIPHER_BLOWFISH_ECB, /**< Blowfish cipher with ECB mode. */
138 MBEDTLS_CIPHER_BLOWFISH_CBC, /**< Blowfish cipher with CBC mode. */
139 MBEDTLS_CIPHER_BLOWFISH_CFB64, /**< Blowfish cipher with CFB64 mode. */
140 MBEDTLS_CIPHER_BLOWFISH_CTR, /**< Blowfish cipher with CTR mode. */
141 MBEDTLS_CIPHER_ARC4_128, /**< RC4 cipher with 128-bit mode. */
142 MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */
143 MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */
144 MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */
145 MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */
146 MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */
147 MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */
148 MBEDTLS_CIPHER_ARIA_128_ECB, /**< Aria cipher with 128-bit key and ECB mode. */
149 MBEDTLS_CIPHER_ARIA_192_ECB, /**< Aria cipher with 192-bit key and ECB mode. */
150 MBEDTLS_CIPHER_ARIA_256_ECB, /**< Aria cipher with 256-bit key and ECB mode. */
151 MBEDTLS_CIPHER_ARIA_128_CBC, /**< Aria cipher with 128-bit key and CBC mode. */
152 MBEDTLS_CIPHER_ARIA_192_CBC, /**< Aria cipher with 192-bit key and CBC mode. */
153 MBEDTLS_CIPHER_ARIA_256_CBC, /**< Aria cipher with 256-bit key and CBC mode. */
154 MBEDTLS_CIPHER_ARIA_128_CFB128, /**< Aria cipher with 128-bit key and CFB-128 mode. */
155 MBEDTLS_CIPHER_ARIA_192_CFB128, /**< Aria cipher with 192-bit key and CFB-128 mode. */
156 MBEDTLS_CIPHER_ARIA_256_CFB128, /**< Aria cipher with 256-bit key and CFB-128 mode. */
157 MBEDTLS_CIPHER_ARIA_128_CTR, /**< Aria cipher with 128-bit key and CTR mode. */
158 MBEDTLS_CIPHER_ARIA_192_CTR, /**< Aria cipher with 192-bit key and CTR mode. */
159 MBEDTLS_CIPHER_ARIA_256_CTR, /**< Aria cipher with 256-bit key and CTR mode. */
160 MBEDTLS_CIPHER_ARIA_128_GCM, /**< Aria cipher with 128-bit key and GCM mode. */
161 MBEDTLS_CIPHER_ARIA_192_GCM, /**< Aria cipher with 192-bit key and GCM mode. */
162 MBEDTLS_CIPHER_ARIA_256_GCM, /**< Aria cipher with 256-bit key and GCM mode. */
163 MBEDTLS_CIPHER_ARIA_128_CCM, /**< Aria cipher with 128-bit key and CCM mode. */
164 MBEDTLS_CIPHER_ARIA_192_CCM, /**< Aria cipher with 192-bit key and CCM mode. */
165 MBEDTLS_CIPHER_ARIA_256_CCM, /**< Aria cipher with 256-bit key and CCM mode. */
166 MBEDTLS_CIPHER_AES_128_OFB, /**< AES 128-bit cipher in OFB mode. */
167 MBEDTLS_CIPHER_AES_192_OFB, /**< AES 192-bit cipher in OFB mode. */
168 MBEDTLS_CIPHER_AES_256_OFB, /**< AES 256-bit cipher in OFB mode. */
169 MBEDTLS_CIPHER_AES_128_XTS, /**< AES 128-bit cipher in XTS block mode. */
170 MBEDTLS_CIPHER_AES_256_XTS, /**< AES 256-bit cipher in XTS block mode. */
171 MBEDTLS_CIPHER_CHACHA20, /**< ChaCha20 stream cipher. */
172 MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< ChaCha20-Poly1305 AEAD cipher. */
173 MBEDTLS_CIPHER_AES_128_KW, /**< AES cipher with 128-bit NIST KW mode. */
174 MBEDTLS_CIPHER_AES_192_KW, /**< AES cipher with 192-bit NIST KW mode. */
175 MBEDTLS_CIPHER_AES_256_KW, /**< AES cipher with 256-bit NIST KW mode. */
176 MBEDTLS_CIPHER_AES_128_KWP, /**< AES cipher with 128-bit NIST KWP mode. */
177 MBEDTLS_CIPHER_AES_192_KWP, /**< AES cipher with 192-bit NIST KWP mode. */
178 MBEDTLS_CIPHER_AES_256_KWP, /**< AES cipher with 256-bit NIST KWP mode. */
179 } mbedtls_cipher_type_t;
180
181 /** Supported cipher modes. */
182 typedef enum {
183 MBEDTLS_MODE_NONE = 0, /**< None. */
184 MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */
185 MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */
186 MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */
187 MBEDTLS_MODE_OFB, /**< The OFB cipher mode. */
188 MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */
189 MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */
190 MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */
191 MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */
192 MBEDTLS_MODE_XTS, /**< The XTS cipher mode. */
193 MBEDTLS_MODE_CHACHAPOLY, /**< The ChaCha-Poly cipher mode. */
194 MBEDTLS_MODE_KW, /**< The SP800-38F KW mode */
195 MBEDTLS_MODE_KWP, /**< The SP800-38F KWP mode */
196 } mbedtls_cipher_mode_t;
197
198 /** Supported cipher padding types. */
199 typedef enum {
200 MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */
201 MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */
202 MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */
203 MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */
204 MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */
205 } mbedtls_cipher_padding_t;
206
207 /** Type of operation. */
208 typedef enum {
209 MBEDTLS_OPERATION_NONE = -1,
210 MBEDTLS_DECRYPT = 0,
211 MBEDTLS_ENCRYPT,
212 } mbedtls_operation_t;
213
214 enum {
215 /** Undefined key length. */
216 MBEDTLS_KEY_LENGTH_NONE = 0,
217 /** Key length, in bits (including parity), for DES keys. \warning DES is considered weak. */
218 MBEDTLS_KEY_LENGTH_DES = 64,
219 /** Key length in bits, including parity, for DES in two-key EDE. \warning 3DES is considered weak. */
220 MBEDTLS_KEY_LENGTH_DES_EDE = 128,
221 /** Key length in bits, including parity, for DES in three-key EDE. \warning 3DES is considered weak. */
222 MBEDTLS_KEY_LENGTH_DES_EDE3 = 192,
223 };
224
225 /** Maximum length of any IV, in Bytes. */
226 /* This should ideally be derived automatically from list of ciphers.
227 * This should be kept in sync with MBEDTLS_SSL_MAX_IV_LENGTH defined
228 * in ssl_internal.h. */
229 #define MBEDTLS_MAX_IV_LENGTH 16
230
231 /** Maximum block size of any cipher, in Bytes. */
232 /* This should ideally be derived automatically from list of ciphers.
233 * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
234 * in ssl_internal.h. */
235 #define MBEDTLS_MAX_BLOCK_LENGTH 16
236
237 /** Maximum key length, in Bytes. */
238 /* This should ideally be derived automatically from list of ciphers.
239 * For now, only check whether XTS is enabled which uses 64 Byte keys,
240 * and use 32 Bytes as an upper bound for the maximum key length otherwise.
241 * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
242 * in ssl_internal.h, which however deliberately ignores the case of XTS
243 * since the latter isn't used in SSL/TLS. */
244 #if defined(MBEDTLS_CIPHER_MODE_XTS)
245 #define MBEDTLS_MAX_KEY_LENGTH 64
246 #else
247 #define MBEDTLS_MAX_KEY_LENGTH 32
248 #endif /* MBEDTLS_CIPHER_MODE_XTS */
249
250 /**
251 * Base cipher information (opaque struct).
252 */
253 typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t;
254
255 /**
256 * CMAC context (opaque struct).
257 */
258 typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t;
259
260 /**
261 * Cipher information. Allows calling cipher functions
262 * in a generic way.
263 */
264 typedef struct mbedtls_cipher_info_t {
265 /** Full cipher identifier. For example,
266 * MBEDTLS_CIPHER_AES_256_CBC.
267 */
268 mbedtls_cipher_type_t type;
269
270 /** The cipher mode. For example, MBEDTLS_MODE_CBC. */
271 mbedtls_cipher_mode_t mode;
272
273 /** The cipher key length, in bits. This is the
274 * default length for variable sized ciphers.
275 * Includes parity bits for ciphers like DES.
276 */
277 unsigned int key_bitlen;
278
279 /** Name of the cipher. */
280 const char *name;
281
282 /** IV or nonce size, in Bytes.
283 * For ciphers that accept variable IV sizes,
284 * this is the recommended size.
285 */
286 unsigned int iv_size;
287
288 /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and
289 * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the
290 * cipher supports variable IV or variable key sizes, respectively.
291 */
292 int flags;
293
294 /** The block size, in Bytes. */
295 unsigned int block_size;
296
297 /** Struct for base cipher information and functions. */
298 const mbedtls_cipher_base_t *base;
299
300 } mbedtls_cipher_info_t;
301
302 /**
303 * Generic cipher context.
304 */
305 typedef struct mbedtls_cipher_context_t {
306 /** Information about the associated cipher. */
307 const mbedtls_cipher_info_t *cipher_info;
308
309 /** Key length to use. */
310 int key_bitlen;
311
312 /** Operation that the key of the context has been
313 * initialized for.
314 */
315 mbedtls_operation_t operation;
316
317 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
318 /** Padding functions to use, if relevant for
319 * the specific cipher mode.
320 */
321 void (*add_padding)(unsigned char *output, size_t olen, size_t data_len);
322 int (*get_padding)(unsigned char *input, size_t ilen, size_t *data_len);
323 #endif
324
325 /** Buffer for input that has not been processed yet. */
326 unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
327
328 /** Number of Bytes that have not been processed yet. */
329 size_t unprocessed_len;
330
331 /** Current IV or NONCE_COUNTER for CTR-mode, data unit (or sector) number
332 * for XTS-mode. */
333 unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
334
335 /** IV size in Bytes, for ciphers with variable-length IVs. */
336 size_t iv_size;
337
338 /** The cipher-specific context. */
339 void *cipher_ctx;
340
341 #if defined(MBEDTLS_CMAC_C)
342 /** CMAC-specific context. */
343 mbedtls_cmac_context_t *cmac_ctx;
344 #endif
345
346 #if defined(MBEDTLS_USE_PSA_CRYPTO)
347 /** Indicates whether the cipher operations should be performed
348 * by Mbed TLS' own crypto library or an external implementation
349 * of the PSA Crypto API.
350 * This is unset if the cipher context was established through
351 * mbedtls_cipher_setup(), and set if it was established through
352 * mbedtls_cipher_setup_psa().
353 */
354 unsigned char psa_enabled;
355 #endif /* MBEDTLS_USE_PSA_CRYPTO */
356
357 } mbedtls_cipher_context_t;
358
359 /**
360 * \brief This function retrieves the list of ciphers supported
361 * by the generic cipher module.
362 *
363 * For any cipher identifier in the returned list, you can
364 * obtain the corresponding generic cipher information structure
365 * via mbedtls_cipher_info_from_type(), which can then be used
366 * to prepare a cipher context via mbedtls_cipher_setup().
367 *
368 *
369 * \return A statically-allocated array of cipher identifiers
370 * of type cipher_type_t. The last entry is zero.
371 */
372 const int *mbedtls_cipher_list(void);
373
374 /**
375 * \brief This function retrieves the cipher-information
376 * structure associated with the given cipher name.
377 *
378 * \param cipher_name Name of the cipher to search for. This must not be
379 * \c NULL.
380 *
381 * \return The cipher information structure associated with the
382 * given \p cipher_name.
383 * \return \c NULL if the associated cipher information is not found.
384 */
385 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string(const char *cipher_name);
386
387 /**
388 * \brief This function retrieves the cipher-information
389 * structure associated with the given cipher type.
390 *
391 * \param cipher_type Type of the cipher to search for.
392 *
393 * \return The cipher information structure associated with the
394 * given \p cipher_type.
395 * \return \c NULL if the associated cipher information is not found.
396 */
397 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type(const mbedtls_cipher_type_t cipher_type);
398
399 /**
400 * \brief This function retrieves the cipher-information
401 * structure associated with the given cipher ID,
402 * key size and mode.
403 *
404 * \param cipher_id The ID of the cipher to search for. For example,
405 * #MBEDTLS_CIPHER_ID_AES.
406 * \param key_bitlen The length of the key in bits.
407 * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC.
408 *
409 * \return The cipher information structure associated with the
410 * given \p cipher_id.
411 * \return \c NULL if the associated cipher information is not found.
412 */
413 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values(const mbedtls_cipher_id_t cipher_id,
414 int key_bitlen,
415 const mbedtls_cipher_mode_t mode);
416
417 /**
418 * \brief This function initializes a \p ctx as NONE.
419 *
420 * \param ctx The context to be initialized. This must not be \c NULL.
421 */
422 void mbedtls_cipher_init(mbedtls_cipher_context_t *ctx);
423
424 /**
425 * \brief This function frees and clears the cipher-specific
426 * context of \p ctx. Freeing \p ctx itself remains the
427 * responsibility of the caller.
428 *
429 * \param ctx The context to be freed. If this is \c NULL, the
430 * function has no effect, otherwise this must point to an
431 * initialized context.
432 */
433 void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx);
434
435
436 /**
437 * \brief This function prepares a cipher context for
438 * use with the given cipher primitive.
439 *
440 * \warning In CBC mode, if mbedtls_cipher_set_padding_mode() is not called:
441 * - If MBEDTLS_CIPHER_PADDING_PKCS7 is enabled, the
442 * context will use PKCS7 padding.
443 * - Otherwise the context uses no padding and the input
444 * must be a whole number of blocks.
445 *
446 * \note After calling this function, you should call
447 * mbedtls_cipher_setkey() and, if the mode uses padding,
448 * mbedtls_cipher_set_padding_mode(), then for each
449 * message to encrypt or decrypt with this key, either:
450 * - mbedtls_cipher_crypt() for one-shot processing with
451 * non-AEAD modes;
452 * - mbedtls_cipher_auth_encrypt_ext() or
453 * mbedtls_cipher_auth_decrypt_ext() for one-shot
454 * processing with AEAD modes or NIST_KW;
455 * - for multi-part processing, see the documentation of
456 * mbedtls_cipher_reset().
457 *
458 * \param ctx The context to prepare. This must be initialized by
459 * a call to mbedtls_cipher_init() first.
460 * \param cipher_info The cipher to use.
461 *
462 * \return \c 0 on success.
463 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
464 * parameter-verification failure.
465 * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
466 * cipher-specific context fails.
467 *
468 * \internal Currently, the function also clears the structure.
469 * In future versions, the caller will be required to call
470 * mbedtls_cipher_init() on the structure first.
471 */
472 int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx,
473 const mbedtls_cipher_info_t *cipher_info);
474
475 #if defined(MBEDTLS_USE_PSA_CRYPTO)
476 /**
477 * \brief This function initializes a cipher context for
478 * PSA-based use with the given cipher primitive.
479 *
480 * \note See #MBEDTLS_USE_PSA_CRYPTO for information on PSA.
481 *
482 * \param ctx The context to initialize. May not be \c NULL.
483 * \param cipher_info The cipher to use.
484 * \param taglen For AEAD ciphers, the length in bytes of the
485 * authentication tag to use. Subsequent uses of
486 * mbedtls_cipher_auth_encrypt() or
487 * mbedtls_cipher_auth_decrypt() must provide
488 * the same tag length.
489 * For non-AEAD ciphers, the value must be \c 0.
490 *
491 * \return \c 0 on success.
492 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
493 * parameter-verification failure.
494 * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
495 * cipher-specific context fails.
496 */
497 int mbedtls_cipher_setup_psa(mbedtls_cipher_context_t *ctx,
498 const mbedtls_cipher_info_t *cipher_info,
499 size_t taglen);
500 #endif /* MBEDTLS_USE_PSA_CRYPTO */
501
502 /**
503 * \brief This function returns the block size of the given cipher.
504 *
505 * \param ctx The context of the cipher. This must be initialized.
506 *
507 * \return The block size of the underlying cipher.
508 * \return \c 0 if \p ctx has not been initialized.
509 */
mbedtls_cipher_get_block_size(const mbedtls_cipher_context_t * ctx)510 static inline unsigned int mbedtls_cipher_get_block_size(
511 const mbedtls_cipher_context_t *ctx)
512 {
513 MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
514 if (ctx->cipher_info == NULL) {
515 return 0;
516 }
517
518 return ctx->cipher_info->block_size;
519 }
520
521 /**
522 * \brief This function returns the mode of operation for
523 * the cipher. For example, MBEDTLS_MODE_CBC.
524 *
525 * \param ctx The context of the cipher. This must be initialized.
526 *
527 * \return The mode of operation.
528 * \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized.
529 */
mbedtls_cipher_get_cipher_mode(const mbedtls_cipher_context_t * ctx)530 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(
531 const mbedtls_cipher_context_t *ctx)
532 {
533 MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, MBEDTLS_MODE_NONE);
534 if (ctx->cipher_info == NULL) {
535 return MBEDTLS_MODE_NONE;
536 }
537
538 return ctx->cipher_info->mode;
539 }
540
541 /**
542 * \brief This function returns the size of the IV or nonce
543 * of the cipher, in Bytes.
544 *
545 * \param ctx The context of the cipher. This must be initialized.
546 *
547 * \return The recommended IV size if no IV has been set.
548 * \return \c 0 for ciphers not using an IV or a nonce.
549 * \return The actual size if an IV has been set.
550 */
mbedtls_cipher_get_iv_size(const mbedtls_cipher_context_t * ctx)551 static inline int mbedtls_cipher_get_iv_size(
552 const mbedtls_cipher_context_t *ctx)
553 {
554 MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
555 if (ctx->cipher_info == NULL) {
556 return 0;
557 }
558
559 if (ctx->iv_size != 0) {
560 return (int) ctx->iv_size;
561 }
562
563 return (int) ctx->cipher_info->iv_size;
564 }
565
566 /**
567 * \brief This function returns the type of the given cipher.
568 *
569 * \param ctx The context of the cipher. This must be initialized.
570 *
571 * \return The type of the cipher.
572 * \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized.
573 */
mbedtls_cipher_get_type(const mbedtls_cipher_context_t * ctx)574 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type(
575 const mbedtls_cipher_context_t *ctx)
576 {
577 MBEDTLS_INTERNAL_VALIDATE_RET(
578 ctx != NULL, MBEDTLS_CIPHER_NONE);
579 if (ctx->cipher_info == NULL) {
580 return MBEDTLS_CIPHER_NONE;
581 }
582
583 return ctx->cipher_info->type;
584 }
585
586 /**
587 * \brief This function returns the name of the given cipher
588 * as a string.
589 *
590 * \param ctx The context of the cipher. This must be initialized.
591 *
592 * \return The name of the cipher.
593 * \return NULL if \p ctx has not been not initialized.
594 */
mbedtls_cipher_get_name(const mbedtls_cipher_context_t * ctx)595 static inline const char *mbedtls_cipher_get_name(
596 const mbedtls_cipher_context_t *ctx)
597 {
598 MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
599 if (ctx->cipher_info == NULL) {
600 return 0;
601 }
602
603 return ctx->cipher_info->name;
604 }
605
606 /**
607 * \brief This function returns the key length of the cipher.
608 *
609 * \param ctx The context of the cipher. This must be initialized.
610 *
611 * \return The key length of the cipher in bits.
612 * \return #MBEDTLS_KEY_LENGTH_NONE if \p ctx has not been
613 * initialized.
614 */
mbedtls_cipher_get_key_bitlen(const mbedtls_cipher_context_t * ctx)615 static inline int mbedtls_cipher_get_key_bitlen(
616 const mbedtls_cipher_context_t *ctx)
617 {
618 MBEDTLS_INTERNAL_VALIDATE_RET(
619 ctx != NULL, MBEDTLS_KEY_LENGTH_NONE);
620 if (ctx->cipher_info == NULL) {
621 return MBEDTLS_KEY_LENGTH_NONE;
622 }
623
624 return (int) ctx->cipher_info->key_bitlen;
625 }
626
627 /**
628 * \brief This function returns the operation of the given cipher.
629 *
630 * \param ctx The context of the cipher. This must be initialized.
631 *
632 * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
633 * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized.
634 */
mbedtls_cipher_get_operation(const mbedtls_cipher_context_t * ctx)635 static inline mbedtls_operation_t mbedtls_cipher_get_operation(
636 const mbedtls_cipher_context_t *ctx)
637 {
638 MBEDTLS_INTERNAL_VALIDATE_RET(
639 ctx != NULL, MBEDTLS_OPERATION_NONE);
640 if (ctx->cipher_info == NULL) {
641 return MBEDTLS_OPERATION_NONE;
642 }
643
644 return ctx->operation;
645 }
646
647 /**
648 * \brief This function sets the key to use with the given context.
649 *
650 * \param ctx The generic cipher context. This must be initialized and
651 * bound to a cipher information structure.
652 * \param key The key to use. This must be a readable buffer of at
653 * least \p key_bitlen Bits.
654 * \param key_bitlen The key length to use, in Bits.
655 * \param operation The operation that the key will be used for:
656 * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT.
657 *
658 * \return \c 0 on success.
659 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
660 * parameter-verification failure.
661 * \return A cipher-specific error code on failure.
662 */
663 int mbedtls_cipher_setkey(mbedtls_cipher_context_t *ctx,
664 const unsigned char *key,
665 int key_bitlen,
666 const mbedtls_operation_t operation);
667
668 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
669 /**
670 * \brief This function sets the padding mode, for cipher modes
671 * that use padding.
672 *
673 * \param ctx The generic cipher context. This must be initialized and
674 * bound to a cipher information structure.
675 * \param mode The padding mode.
676 *
677 * \return \c 0 on success.
678 * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
679 * if the selected padding mode is not supported.
680 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
681 * does not support padding.
682 */
683 int mbedtls_cipher_set_padding_mode(mbedtls_cipher_context_t *ctx,
684 mbedtls_cipher_padding_t mode);
685 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
686
687 /**
688 * \brief This function sets the initialization vector (IV)
689 * or nonce.
690 *
691 * \note Some ciphers do not use IVs nor nonce. For these
692 * ciphers, this function has no effect.
693 *
694 * \param ctx The generic cipher context. This must be initialized and
695 * bound to a cipher information structure.
696 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This
697 * must be a readable buffer of at least \p iv_len Bytes.
698 * \param iv_len The IV length for ciphers with variable-size IV.
699 * This parameter is discarded by ciphers with fixed-size IV.
700 *
701 * \return \c 0 on success.
702 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
703 * parameter-verification failure.
704 */
705 int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx,
706 const unsigned char *iv,
707 size_t iv_len);
708
709 /**
710 * \brief This function resets the cipher state.
711 *
712 * \note With non-AEAD ciphers, the order of calls for each message
713 * is as follows:
714 * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce.
715 * 2. mbedtls_cipher_reset()
716 * 3. mbedtls_cipher_update() one or more times
717 * 4. mbedtls_cipher_finish()
718 * .
719 * This sequence can be repeated to encrypt or decrypt multiple
720 * messages with the same key.
721 *
722 * \note With AEAD ciphers, the order of calls for each message
723 * is as follows:
724 * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce.
725 * 2. mbedtls_cipher_reset()
726 * 3. mbedtls_cipher_update_ad()
727 * 4. mbedtls_cipher_update() one or more times
728 * 5. mbedtls_cipher_check_tag() (for decryption) or
729 * mbedtls_cipher_write_tag() (for encryption).
730 * .
731 * This sequence can be repeated to encrypt or decrypt multiple
732 * messages with the same key.
733 *
734 * \param ctx The generic cipher context. This must be bound to a key.
735 *
736 * \return \c 0 on success.
737 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
738 * parameter-verification failure.
739 */
740 int mbedtls_cipher_reset(mbedtls_cipher_context_t *ctx);
741
742 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
743 /**
744 * \brief This function adds additional data for AEAD ciphers.
745 * Currently supported with GCM and ChaCha20+Poly1305.
746 * This must be called exactly once, after
747 * mbedtls_cipher_reset().
748 *
749 * \param ctx The generic cipher context. This must be initialized.
750 * \param ad The additional data to use. This must be a readable
751 * buffer of at least \p ad_len Bytes.
752 * \param ad_len The length of \p ad in Bytes.
753 *
754 * \return \c 0 on success.
755 * \return A specific error code on failure.
756 */
757 int mbedtls_cipher_update_ad(mbedtls_cipher_context_t *ctx,
758 const unsigned char *ad, size_t ad_len);
759 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
760
761 /**
762 * \brief The generic cipher update function. It encrypts or
763 * decrypts using the given cipher context. Writes as
764 * many block-sized blocks of data as possible to output.
765 * Any data that cannot be written immediately is either
766 * added to the next block, or flushed when
767 * mbedtls_cipher_finish() is called.
768 * Exception: For MBEDTLS_MODE_ECB, expects a single block
769 * in size. For example, 16 Bytes for AES.
770 *
771 * \note If the underlying cipher is used in GCM mode, all calls
772 * to this function, except for the last one before
773 * mbedtls_cipher_finish(), must have \p ilen as a
774 * multiple of the block size of the cipher.
775 *
776 * \param ctx The generic cipher context. This must be initialized and
777 * bound to a key.
778 * \param input The buffer holding the input data. This must be a
779 * readable buffer of at least \p ilen Bytes.
780 * \param ilen The length of the input data.
781 * \param output The buffer for the output data. This must be able to
782 * hold at least `ilen + block_size`. This must not be the
783 * same buffer as \p input.
784 * \param olen The length of the output data, to be updated with the
785 * actual number of Bytes written. This must not be
786 * \c NULL.
787 *
788 * \return \c 0 on success.
789 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
790 * parameter-verification failure.
791 * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
792 * unsupported mode for a cipher.
793 * \return A cipher-specific error code on failure.
794 */
795 int mbedtls_cipher_update(mbedtls_cipher_context_t *ctx,
796 const unsigned char *input,
797 size_t ilen, unsigned char *output,
798 size_t *olen);
799
800 /**
801 * \brief The generic cipher finalization function. If data still
802 * needs to be flushed from an incomplete block, the data
803 * contained in it is padded to the size of
804 * the last block, and written to the \p output buffer.
805 *
806 * \param ctx The generic cipher context. This must be initialized and
807 * bound to a key.
808 * \param output The buffer to write data to. This needs to be a writable
809 * buffer of at least block_size Bytes.
810 * \param olen The length of the data written to the \p output buffer.
811 * This may not be \c NULL.
812 *
813 * \return \c 0 on success.
814 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
815 * parameter-verification failure.
816 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
817 * expecting a full block but not receiving one.
818 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
819 * while decrypting.
820 * \return A cipher-specific error code on failure.
821 */
822 int mbedtls_cipher_finish(mbedtls_cipher_context_t *ctx,
823 unsigned char *output, size_t *olen);
824
825 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
826 /**
827 * \brief This function writes a tag for AEAD ciphers.
828 * Currently supported with GCM and ChaCha20+Poly1305.
829 * This must be called after mbedtls_cipher_finish().
830 *
831 * \param ctx The generic cipher context. This must be initialized,
832 * bound to a key, and have just completed a cipher
833 * operation through mbedtls_cipher_finish() the tag for
834 * which should be written.
835 * \param tag The buffer to write the tag to. This must be a writable
836 * buffer of at least \p tag_len Bytes.
837 * \param tag_len The length of the tag to write.
838 *
839 * \return \c 0 on success.
840 * \return A specific error code on failure.
841 */
842 int mbedtls_cipher_write_tag(mbedtls_cipher_context_t *ctx,
843 unsigned char *tag, size_t tag_len);
844
845 /**
846 * \brief This function checks the tag for AEAD ciphers.
847 * Currently supported with GCM and ChaCha20+Poly1305.
848 * This must be called after mbedtls_cipher_finish().
849 *
850 * \param ctx The generic cipher context. This must be initialized.
851 * \param tag The buffer holding the tag. This must be a readable
852 * buffer of at least \p tag_len Bytes.
853 * \param tag_len The length of the tag to check.
854 *
855 * \return \c 0 on success.
856 * \return A specific error code on failure.
857 */
858 int mbedtls_cipher_check_tag(mbedtls_cipher_context_t *ctx,
859 const unsigned char *tag, size_t tag_len);
860 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
861
862 /**
863 * \brief The generic all-in-one encryption/decryption function,
864 * for all ciphers except AEAD constructs.
865 *
866 * \param ctx The generic cipher context. This must be initialized.
867 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers.
868 * This must be a readable buffer of at least \p iv_len
869 * Bytes.
870 * \param iv_len The IV length for ciphers with variable-size IV.
871 * This parameter is discarded by ciphers with fixed-size
872 * IV.
873 * \param input The buffer holding the input data. This must be a
874 * readable buffer of at least \p ilen Bytes.
875 * \param ilen The length of the input data in Bytes.
876 * \param output The buffer for the output data. This must be able to
877 * hold at least `ilen + block_size`. This must not be the
878 * same buffer as \p input.
879 * \param olen The length of the output data, to be updated with the
880 * actual number of Bytes written. This must not be
881 * \c NULL.
882 *
883 * \note Some ciphers do not use IVs nor nonce. For these
884 * ciphers, use \p iv = NULL and \p iv_len = 0.
885 *
886 * \return \c 0 on success.
887 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
888 * parameter-verification failure.
889 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption
890 * expecting a full block but not receiving one.
891 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
892 * while decrypting.
893 * \return A cipher-specific error code on failure.
894 */
895 int mbedtls_cipher_crypt(mbedtls_cipher_context_t *ctx,
896 const unsigned char *iv, size_t iv_len,
897 const unsigned char *input, size_t ilen,
898 unsigned char *output, size_t *olen);
899
900 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
901 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
902 #if defined(MBEDTLS_DEPRECATED_WARNING)
903 #define MBEDTLS_DEPRECATED __attribute__((deprecated))
904 #else
905 #define MBEDTLS_DEPRECATED
906 #endif /* MBEDTLS_DEPRECATED_WARNING */
907 /**
908 * \brief The generic authenticated encryption (AEAD) function.
909 *
910 * \deprecated Superseded by mbedtls_cipher_auth_encrypt_ext().
911 *
912 * \note This function only supports AEAD algorithms, not key
913 * wrapping algorithms such as NIST_KW; for this, see
914 * mbedtls_cipher_auth_encrypt_ext().
915 *
916 * \param ctx The generic cipher context. This must be initialized and
917 * bound to a key associated with an AEAD algorithm.
918 * \param iv The nonce to use. This must be a readable buffer of
919 * at least \p iv_len Bytes and must not be \c NULL.
920 * \param iv_len The length of the nonce. This must satisfy the
921 * constraints imposed by the AEAD cipher used.
922 * \param ad The additional data to authenticate. This must be a
923 * readable buffer of at least \p ad_len Bytes, and may
924 * be \c NULL is \p ad_len is \c 0.
925 * \param ad_len The length of \p ad.
926 * \param input The buffer holding the input data. This must be a
927 * readable buffer of at least \p ilen Bytes, and may be
928 * \c NULL if \p ilen is \c 0.
929 * \param ilen The length of the input data.
930 * \param output The buffer for the output data. This must be a
931 * writable buffer of at least \p ilen Bytes, and must
932 * not be \c NULL.
933 * \param olen This will be filled with the actual number of Bytes
934 * written to the \p output buffer. This must point to a
935 * writable object of type \c size_t.
936 * \param tag The buffer for the authentication tag. This must be a
937 * writable buffer of at least \p tag_len Bytes. See note
938 * below regarding restrictions with PSA-based contexts.
939 * \param tag_len The desired length of the authentication tag. This
940 * must match the constraints imposed by the AEAD cipher
941 * used, and in particular must not be \c 0.
942 *
943 * \note If the context is based on PSA (that is, it was set up
944 * with mbedtls_cipher_setup_psa()), then it is required
945 * that \c tag == output + ilen. That is, the tag must be
946 * appended to the ciphertext as recommended by RFC 5116.
947 *
948 * \return \c 0 on success.
949 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
950 * parameter-verification failure.
951 * \return A cipher-specific error code on failure.
952 */
953 int MBEDTLS_DEPRECATED mbedtls_cipher_auth_encrypt(
954 mbedtls_cipher_context_t *ctx,
955 const unsigned char *iv, size_t iv_len,
956 const unsigned char *ad, size_t ad_len,
957 const unsigned char *input, size_t ilen,
958 unsigned char *output, size_t *olen,
959 unsigned char *tag, size_t tag_len);
960
961 /**
962 * \brief The generic authenticated decryption (AEAD) function.
963 *
964 * \deprecated Superseded by mbedtls_cipher_auth_decrypt_ext().
965 *
966 * \note This function only supports AEAD algorithms, not key
967 * wrapping algorithms such as NIST_KW; for this, see
968 * mbedtls_cipher_auth_decrypt_ext().
969 *
970 * \note If the data is not authentic, then the output buffer
971 * is zeroed out to prevent the unauthentic plaintext being
972 * used, making this interface safer.
973 *
974 * \param ctx The generic cipher context. This must be initialized and
975 * bound to a key associated with an AEAD algorithm.
976 * \param iv The nonce to use. This must be a readable buffer of
977 * at least \p iv_len Bytes and must not be \c NULL.
978 * \param iv_len The length of the nonce. This must satisfy the
979 * constraints imposed by the AEAD cipher used.
980 * \param ad The additional data to authenticate. This must be a
981 * readable buffer of at least \p ad_len Bytes, and may
982 * be \c NULL is \p ad_len is \c 0.
983 * \param ad_len The length of \p ad.
984 * \param input The buffer holding the input data. This must be a
985 * readable buffer of at least \p ilen Bytes, and may be
986 * \c NULL if \p ilen is \c 0.
987 * \param ilen The length of the input data.
988 * \param output The buffer for the output data. This must be a
989 * writable buffer of at least \p ilen Bytes, and must
990 * not be \c NULL.
991 * \param olen This will be filled with the actual number of Bytes
992 * written to the \p output buffer. This must point to a
993 * writable object of type \c size_t.
994 * \param tag The buffer for the authentication tag. This must be a
995 * readable buffer of at least \p tag_len Bytes. See note
996 * below regarding restrictions with PSA-based contexts.
997 * \param tag_len The length of the authentication tag. This must match
998 * the constraints imposed by the AEAD cipher used, and in
999 * particular must not be \c 0.
1000 *
1001 * \note If the context is based on PSA (that is, it was set up
1002 * with mbedtls_cipher_setup_psa()), then it is required
1003 * that \c tag == input + len. That is, the tag must be
1004 * appended to the ciphertext as recommended by RFC 5116.
1005 *
1006 * \return \c 0 on success.
1007 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
1008 * parameter-verification failure.
1009 * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
1010 * \return A cipher-specific error code on failure.
1011 */
1012 int MBEDTLS_DEPRECATED mbedtls_cipher_auth_decrypt(
1013 mbedtls_cipher_context_t *ctx,
1014 const unsigned char *iv, size_t iv_len,
1015 const unsigned char *ad, size_t ad_len,
1016 const unsigned char *input, size_t ilen,
1017 unsigned char *output, size_t *olen,
1018 const unsigned char *tag, size_t tag_len);
1019 #undef MBEDTLS_DEPRECATED
1020 #endif /* MBEDTLS_DEPRECATED_REMOVED */
1021 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
1022
1023 #if defined(MBEDTLS_CIPHER_MODE_AEAD) || defined(MBEDTLS_NIST_KW_C)
1024 /**
1025 * \brief The authenticated encryption (AEAD/NIST_KW) function.
1026 *
1027 * \note For AEAD modes, the tag will be appended to the
1028 * ciphertext, as recommended by RFC 5116.
1029 * (NIST_KW doesn't have a separate tag.)
1030 *
1031 * \param ctx The generic cipher context. This must be initialized and
1032 * bound to a key, with an AEAD algorithm or NIST_KW.
1033 * \param iv The nonce to use. This must be a readable buffer of
1034 * at least \p iv_len Bytes and may be \c NULL if \p
1035 * iv_len is \c 0.
1036 * \param iv_len The length of the nonce. For AEAD ciphers, this must
1037 * satisfy the constraints imposed by the cipher used.
1038 * For NIST_KW, this must be \c 0.
1039 * \param ad The additional data to authenticate. This must be a
1040 * readable buffer of at least \p ad_len Bytes, and may
1041 * be \c NULL is \p ad_len is \c 0.
1042 * \param ad_len The length of \p ad. For NIST_KW, this must be \c 0.
1043 * \param input The buffer holding the input data. This must be a
1044 * readable buffer of at least \p ilen Bytes, and may be
1045 * \c NULL if \p ilen is \c 0.
1046 * \param ilen The length of the input data.
1047 * \param output The buffer for the output data. This must be a
1048 * writable buffer of at least \p output_len Bytes, and
1049 * must not be \c NULL.
1050 * \param output_len The length of the \p output buffer in Bytes. For AEAD
1051 * ciphers, this must be at least \p ilen + \p tag_len.
1052 * For NIST_KW, this must be at least \p ilen + 8
1053 * (rounded up to a multiple of 8 if KWP is used);
1054 * \p ilen + 15 is always a safe value.
1055 * \param olen This will be filled with the actual number of Bytes
1056 * written to the \p output buffer. This must point to a
1057 * writable object of type \c size_t.
1058 * \param tag_len The desired length of the authentication tag. For AEAD
1059 * ciphers, this must match the constraints imposed by
1060 * the cipher used, and in particular must not be \c 0.
1061 * For NIST_KW, this must be \c 0.
1062 *
1063 * \return \c 0 on success.
1064 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
1065 * parameter-verification failure.
1066 * \return A cipher-specific error code on failure.
1067 */
1068 int mbedtls_cipher_auth_encrypt_ext(mbedtls_cipher_context_t *ctx,
1069 const unsigned char *iv, size_t iv_len,
1070 const unsigned char *ad, size_t ad_len,
1071 const unsigned char *input, size_t ilen,
1072 unsigned char *output, size_t output_len,
1073 size_t *olen, size_t tag_len);
1074
1075 /**
1076 * \brief The authenticated encryption (AEAD/NIST_KW) function.
1077 *
1078 * \note If the data is not authentic, then the output buffer
1079 * is zeroed out to prevent the unauthentic plaintext being
1080 * used, making this interface safer.
1081 *
1082 * \note For AEAD modes, the tag must be appended to the
1083 * ciphertext, as recommended by RFC 5116.
1084 * (NIST_KW doesn't have a separate tag.)
1085 *
1086 * \param ctx The generic cipher context. This must be initialized and
1087 * bound to a key, with an AEAD algorithm or NIST_KW.
1088 * \param iv The nonce to use. This must be a readable buffer of
1089 * at least \p iv_len Bytes and may be \c NULL if \p
1090 * iv_len is \c 0.
1091 * \param iv_len The length of the nonce. For AEAD ciphers, this must
1092 * satisfy the constraints imposed by the cipher used.
1093 * For NIST_KW, this must be \c 0.
1094 * \param ad The additional data to authenticate. This must be a
1095 * readable buffer of at least \p ad_len Bytes, and may
1096 * be \c NULL is \p ad_len is \c 0.
1097 * \param ad_len The length of \p ad. For NIST_KW, this must be \c 0.
1098 * \param input The buffer holding the input data. This must be a
1099 * readable buffer of at least \p ilen Bytes, and may be
1100 * \c NULL if \p ilen is \c 0.
1101 * \param ilen The length of the input data. For AEAD ciphers this
1102 * must be at least \p tag_len. For NIST_KW this must be
1103 * at least \c 8.
1104 * \param output The buffer for the output data. This must be a
1105 * writable buffer of at least \p output_len Bytes, and
1106 * may be \c NULL if \p output_len is \c 0.
1107 * \param output_len The length of the \p output buffer in Bytes. For AEAD
1108 * ciphers, this must be at least \p ilen - \p tag_len.
1109 * For NIST_KW, this must be at least \p ilen - 8.
1110 * \param olen This will be filled with the actual number of Bytes
1111 * written to the \p output buffer. This must point to a
1112 * writable object of type \c size_t.
1113 * \param tag_len The actual length of the authentication tag. For AEAD
1114 * ciphers, this must match the constraints imposed by
1115 * the cipher used, and in particular must not be \c 0.
1116 * For NIST_KW, this must be \c 0.
1117 *
1118 * \return \c 0 on success.
1119 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on
1120 * parameter-verification failure.
1121 * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic.
1122 * \return A cipher-specific error code on failure.
1123 */
1124 int mbedtls_cipher_auth_decrypt_ext(mbedtls_cipher_context_t *ctx,
1125 const unsigned char *iv, size_t iv_len,
1126 const unsigned char *ad, size_t ad_len,
1127 const unsigned char *input, size_t ilen,
1128 unsigned char *output, size_t output_len,
1129 size_t *olen, size_t tag_len);
1130 #endif /* MBEDTLS_CIPHER_MODE_AEAD || MBEDTLS_NIST_KW_C */
1131 #ifdef __cplusplus
1132 }
1133 #endif
1134
1135 #endif /* MBEDTLS_CIPHER_H */
1136