4 * \brief Generic cipher wrapper.
6 * \author Adriaan de Jong <dejong@fox-it.com>
8 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
9 * SPDX-License-Identifier: GPL-2.0
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License along
22 * with this program; if not, write to the Free Software Foundation, Inc.,
23 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
25 * This file is part of mbed TLS (https://tls.mbed.org)
28 #ifndef MBEDTLS_CIPHER_H
29 #define MBEDTLS_CIPHER_H
31 #if !defined(MBEDTLS_CONFIG_FILE)
34 #include MBEDTLS_CONFIG_FILE
39 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C)
40 #define MBEDTLS_CIPHER_MODE_AEAD
43 #if defined(MBEDTLS_CIPHER_MODE_CBC)
44 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
47 #if defined(MBEDTLS_ARC4_C)
48 #define MBEDTLS_CIPHER_MODE_STREAM
51 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
52 !defined(inline) && !defined(__cplusplus)
53 #define inline __inline
56 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 /**< The selected feature is not available. */
57 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 /**< Bad input parameters to function. */
58 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 /**< Failed to allocate memory. */
59 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 /**< Input data contains invalid padding and is rejected. */
60 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 /**< Decryption of block requires a full block. */
61 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 /**< Authentication failed (for AEAD modes). */
62 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 /**< The context is invalid, eg because it was free()ed. */
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 */
72 MBEDTLS_CIPHER_ID_NONE
= 0,
73 MBEDTLS_CIPHER_ID_NULL
,
74 MBEDTLS_CIPHER_ID_AES
,
75 MBEDTLS_CIPHER_ID_DES
,
76 MBEDTLS_CIPHER_ID_3DES
,
77 MBEDTLS_CIPHER_ID_CAMELLIA
,
78 MBEDTLS_CIPHER_ID_BLOWFISH
,
79 MBEDTLS_CIPHER_ID_ARC4
,
80 } mbedtls_cipher_id_t
;
83 MBEDTLS_CIPHER_NONE
= 0,
85 MBEDTLS_CIPHER_AES_128_ECB
,
86 MBEDTLS_CIPHER_AES_192_ECB
,
87 MBEDTLS_CIPHER_AES_256_ECB
,
88 MBEDTLS_CIPHER_AES_128_CBC
,
89 MBEDTLS_CIPHER_AES_192_CBC
,
90 MBEDTLS_CIPHER_AES_256_CBC
,
91 MBEDTLS_CIPHER_AES_128_CFB128
,
92 MBEDTLS_CIPHER_AES_192_CFB128
,
93 MBEDTLS_CIPHER_AES_256_CFB128
,
94 MBEDTLS_CIPHER_AES_128_CTR
,
95 MBEDTLS_CIPHER_AES_192_CTR
,
96 MBEDTLS_CIPHER_AES_256_CTR
,
97 MBEDTLS_CIPHER_AES_128_GCM
,
98 MBEDTLS_CIPHER_AES_192_GCM
,
99 MBEDTLS_CIPHER_AES_256_GCM
,
100 MBEDTLS_CIPHER_CAMELLIA_128_ECB
,
101 MBEDTLS_CIPHER_CAMELLIA_192_ECB
,
102 MBEDTLS_CIPHER_CAMELLIA_256_ECB
,
103 MBEDTLS_CIPHER_CAMELLIA_128_CBC
,
104 MBEDTLS_CIPHER_CAMELLIA_192_CBC
,
105 MBEDTLS_CIPHER_CAMELLIA_256_CBC
,
106 MBEDTLS_CIPHER_CAMELLIA_128_CFB128
,
107 MBEDTLS_CIPHER_CAMELLIA_192_CFB128
,
108 MBEDTLS_CIPHER_CAMELLIA_256_CFB128
,
109 MBEDTLS_CIPHER_CAMELLIA_128_CTR
,
110 MBEDTLS_CIPHER_CAMELLIA_192_CTR
,
111 MBEDTLS_CIPHER_CAMELLIA_256_CTR
,
112 MBEDTLS_CIPHER_CAMELLIA_128_GCM
,
113 MBEDTLS_CIPHER_CAMELLIA_192_GCM
,
114 MBEDTLS_CIPHER_CAMELLIA_256_GCM
,
115 MBEDTLS_CIPHER_DES_ECB
,
116 MBEDTLS_CIPHER_DES_CBC
,
117 MBEDTLS_CIPHER_DES_EDE_ECB
,
118 MBEDTLS_CIPHER_DES_EDE_CBC
,
119 MBEDTLS_CIPHER_DES_EDE3_ECB
,
120 MBEDTLS_CIPHER_DES_EDE3_CBC
,
121 MBEDTLS_CIPHER_BLOWFISH_ECB
,
122 MBEDTLS_CIPHER_BLOWFISH_CBC
,
123 MBEDTLS_CIPHER_BLOWFISH_CFB64
,
124 MBEDTLS_CIPHER_BLOWFISH_CTR
,
125 MBEDTLS_CIPHER_ARC4_128
,
126 MBEDTLS_CIPHER_AES_128_CCM
,
127 MBEDTLS_CIPHER_AES_192_CCM
,
128 MBEDTLS_CIPHER_AES_256_CCM
,
129 MBEDTLS_CIPHER_CAMELLIA_128_CCM
,
130 MBEDTLS_CIPHER_CAMELLIA_192_CCM
,
131 MBEDTLS_CIPHER_CAMELLIA_256_CCM
,
132 } mbedtls_cipher_type_t
;
135 MBEDTLS_MODE_NONE
= 0,
139 MBEDTLS_MODE_OFB
, /* Unused! */
144 } mbedtls_cipher_mode_t
;
147 MBEDTLS_PADDING_PKCS7
= 0, /**< PKCS7 padding (default) */
148 MBEDTLS_PADDING_ONE_AND_ZEROS
, /**< ISO/IEC 7816-4 padding */
149 MBEDTLS_PADDING_ZEROS_AND_LEN
, /**< ANSI X.923 padding */
150 MBEDTLS_PADDING_ZEROS
, /**< zero padding (not reversible!) */
151 MBEDTLS_PADDING_NONE
, /**< never pad (full blocks only) */
152 } mbedtls_cipher_padding_t
;
155 MBEDTLS_OPERATION_NONE
= -1,
158 } mbedtls_operation_t
;
161 /** Undefined key length */
162 MBEDTLS_KEY_LENGTH_NONE
= 0,
163 /** Key length, in bits (including parity), for DES keys */
164 MBEDTLS_KEY_LENGTH_DES
= 64,
165 /** Key length, in bits (including parity), for DES in two key EDE */
166 MBEDTLS_KEY_LENGTH_DES_EDE
= 128,
167 /** Key length, in bits (including parity), for DES in three-key EDE */
168 MBEDTLS_KEY_LENGTH_DES_EDE3
= 192,
171 /** Maximum length of any IV, in bytes */
172 #define MBEDTLS_MAX_IV_LENGTH 16
173 /** Maximum block size of any cipher, in bytes */
174 #define MBEDTLS_MAX_BLOCK_LENGTH 16
177 * Base cipher information (opaque struct).
179 typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t
;
182 * Cipher information. Allows cipher functions to be called in a generic way.
185 /** Full cipher identifier (e.g. MBEDTLS_CIPHER_AES_256_CBC) */
186 mbedtls_cipher_type_t type
;
188 /** Cipher mode (e.g. MBEDTLS_MODE_CBC) */
189 mbedtls_cipher_mode_t mode
;
191 /** Cipher key length, in bits (default length for variable sized ciphers)
192 * (Includes parity bits for ciphers like DES) */
193 unsigned int key_bitlen
;
195 /** Name of the cipher */
198 /** IV/NONCE size, in bytes.
199 * For cipher that accept many sizes: recommended size */
200 unsigned int iv_size
;
202 /** Flags for variable IV size, variable key size, etc. */
205 /** block size, in bytes */
206 unsigned int block_size
;
208 /** Base cipher information and functions */
209 const mbedtls_cipher_base_t
*base
;
211 } mbedtls_cipher_info_t
;
214 * Generic cipher context.
217 /** Information about the associated cipher */
218 const mbedtls_cipher_info_t
*cipher_info
;
220 /** Key length to use */
223 /** Operation that the context's key has been initialised for */
224 mbedtls_operation_t operation
;
226 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
227 /** Padding functions to use, if relevant for cipher mode */
228 void (*add_padding
)( unsigned char *output
, size_t olen
, size_t data_len
);
229 int (*get_padding
)( unsigned char *input
, size_t ilen
, size_t *data_len
);
232 /** Buffer for data that hasn't been encrypted yet */
233 unsigned char unprocessed_data
[MBEDTLS_MAX_BLOCK_LENGTH
];
235 /** Number of bytes that still need processing */
236 size_t unprocessed_len
;
238 /** Current IV or NONCE_COUNTER for CTR-mode */
239 unsigned char iv
[MBEDTLS_MAX_IV_LENGTH
];
241 /** IV size in bytes (for ciphers with variable-length IVs) */
244 /** Cipher-specific context */
246 } mbedtls_cipher_context_t
;
249 * \brief Returns the list of ciphers supported by the generic cipher module.
251 * \return a statically allocated array of ciphers, the last entry
254 const int *mbedtls_cipher_list( void );
257 * \brief Returns the cipher information structure associated
258 * with the given cipher name.
260 * \param cipher_name Name of the cipher to search for.
262 * \return the cipher information structure associated with the
263 * given cipher_name, or NULL if not found.
265 const mbedtls_cipher_info_t
*mbedtls_cipher_info_from_string( const char *cipher_name
);
268 * \brief Returns the cipher information structure associated
269 * with the given cipher type.
271 * \param cipher_type Type of the cipher to search for.
273 * \return the cipher information structure associated with the
274 * given cipher_type, or NULL if not found.
276 const mbedtls_cipher_info_t
*mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type
);
279 * \brief Returns the cipher information structure associated
280 * with the given cipher id, key size and mode.
282 * \param cipher_id Id of the cipher to search for
283 * (e.g. MBEDTLS_CIPHER_ID_AES)
284 * \param key_bitlen Length of the key in bits
285 * \param mode Cipher mode (e.g. MBEDTLS_MODE_CBC)
287 * \return the cipher information structure associated with the
288 * given cipher_type, or NULL if not found.
290 const mbedtls_cipher_info_t
*mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id
,
292 const mbedtls_cipher_mode_t mode
);
295 * \brief Initialize a cipher_context (as NONE)
297 void mbedtls_cipher_init( mbedtls_cipher_context_t
*ctx
);
300 * \brief Free and clear the cipher-specific context of ctx.
301 * Freeing ctx itself remains the responsibility of the
304 void mbedtls_cipher_free( mbedtls_cipher_context_t
*ctx
);
307 * \brief Initialises and fills the cipher context structure with
308 * the appropriate values.
310 * \note Currently also clears structure. In future versions you
311 * will be required to call mbedtls_cipher_init() on the structure
314 * \param ctx context to initialise. May not be NULL.
315 * \param cipher_info cipher to use.
317 * \return 0 on success,
318 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure,
319 * MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the
320 * cipher-specific context failed.
322 int mbedtls_cipher_setup( mbedtls_cipher_context_t
*ctx
, const mbedtls_cipher_info_t
*cipher_info
);
325 * \brief Returns the block size of the given cipher.
327 * \param ctx cipher's context. Must have been initialised.
329 * \return size of the cipher's blocks, or 0 if ctx has not been
332 static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t
*ctx
)
334 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
337 return ctx
->cipher_info
->block_size
;
341 * \brief Returns the mode of operation for the cipher.
342 * (e.g. MBEDTLS_MODE_CBC)
344 * \param ctx cipher's context. Must have been initialised.
346 * \return mode of operation, or MBEDTLS_MODE_NONE if ctx
347 * has not been initialised.
349 static inline mbedtls_cipher_mode_t
mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t
*ctx
)
351 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
352 return MBEDTLS_MODE_NONE
;
354 return ctx
->cipher_info
->mode
;
358 * \brief Returns the size of the cipher's IV/NONCE in bytes.
360 * \param ctx cipher's context. Must have been initialised.
362 * \return If IV has not been set yet: (recommended) IV size
363 * (0 for ciphers not using IV/NONCE).
364 * If IV has already been set: actual size.
366 static inline int mbedtls_cipher_get_iv_size( const mbedtls_cipher_context_t
*ctx
)
368 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
371 if( ctx
->iv_size
!= 0 )
372 return (int) ctx
->iv_size
;
374 return (int) ctx
->cipher_info
->iv_size
;
378 * \brief Returns the type of the given cipher.
380 * \param ctx cipher's context. Must have been initialised.
382 * \return type of the cipher, or MBEDTLS_CIPHER_NONE if ctx has
383 * not been initialised.
385 static inline mbedtls_cipher_type_t
mbedtls_cipher_get_type( const mbedtls_cipher_context_t
*ctx
)
387 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
388 return MBEDTLS_CIPHER_NONE
;
390 return ctx
->cipher_info
->type
;
394 * \brief Returns the name of the given cipher, as a string.
396 * \param ctx cipher's context. Must have been initialised.
398 * \return name of the cipher, or NULL if ctx was not initialised.
400 static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t
*ctx
)
402 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
405 return ctx
->cipher_info
->name
;
409 * \brief Returns the key length of the cipher.
411 * \param ctx cipher's context. Must have been initialised.
413 * \return cipher's key length, in bits, or
414 * MBEDTLS_KEY_LENGTH_NONE if ctx has not been
417 static inline int mbedtls_cipher_get_key_bitlen( const mbedtls_cipher_context_t
*ctx
)
419 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
420 return MBEDTLS_KEY_LENGTH_NONE
;
422 return (int) ctx
->cipher_info
->key_bitlen
;
426 * \brief Returns the operation of the given cipher.
428 * \param ctx cipher's context. Must have been initialised.
430 * \return operation (MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT),
431 * or MBEDTLS_OPERATION_NONE if ctx has not been
434 static inline mbedtls_operation_t
mbedtls_cipher_get_operation( const mbedtls_cipher_context_t
*ctx
)
436 if( NULL
== ctx
|| NULL
== ctx
->cipher_info
)
437 return MBEDTLS_OPERATION_NONE
;
439 return ctx
->operation
;
443 * \brief Set the key to use with the given context.
445 * \param ctx generic cipher context. May not be NULL. Must have been
446 * initialised using cipher_context_from_type or
447 * cipher_context_from_string.
448 * \param key The key to use.
449 * \param key_bitlen key length to use, in bits.
450 * \param operation Operation that the key will be used for, either
451 * MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT.
453 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
454 * parameter verification fails or a cipher specific
457 int mbedtls_cipher_setkey( mbedtls_cipher_context_t
*ctx
, const unsigned char *key
,
458 int key_bitlen
, const mbedtls_operation_t operation
);
460 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
462 * \brief Set padding mode, for cipher modes that use padding.
463 * (Default: PKCS7 padding.)
465 * \param ctx generic cipher context
466 * \param mode padding mode
468 * \returns 0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE
469 * if selected padding mode is not supported, or
470 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode
471 * does not support padding.
473 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t
*ctx
, mbedtls_cipher_padding_t mode
);
474 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
477 * \brief Set the initialization vector (IV) or nonce
479 * \param ctx generic cipher context
480 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
481 * \param iv_len IV length for ciphers with variable-size IV;
482 * discarded by ciphers with fixed-size IV.
484 * \returns 0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
486 * \note Some ciphers don't use IVs nor NONCE. For these
487 * ciphers, this function has no effect.
489 int mbedtls_cipher_set_iv( mbedtls_cipher_context_t
*ctx
,
490 const unsigned char *iv
, size_t iv_len
);
493 * \brief Finish preparation of the given context
495 * \param ctx generic cipher context
497 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
498 * if parameter verification fails.
500 int mbedtls_cipher_reset( mbedtls_cipher_context_t
*ctx
);
502 #if defined(MBEDTLS_GCM_C)
504 * \brief Add additional data (for AEAD ciphers).
505 * Currently only supported with GCM.
506 * Must be called exactly once, after mbedtls_cipher_reset().
508 * \param ctx generic cipher context
509 * \param ad Additional data to use.
510 * \param ad_len Length of ad.
512 * \return 0 on success, or a specific error code.
514 int mbedtls_cipher_update_ad( mbedtls_cipher_context_t
*ctx
,
515 const unsigned char *ad
, size_t ad_len
);
516 #endif /* MBEDTLS_GCM_C */
519 * \brief Generic cipher update function. Encrypts/decrypts
520 * using the given cipher context. Writes as many block
521 * size'd blocks of data as possible to output. Any data
522 * that cannot be written immediately will either be added
523 * to the next block, or flushed when cipher_final is
525 * Exception: for MBEDTLS_MODE_ECB, expects single block
526 * in size (e.g. 16 bytes for AES)
528 * \param ctx generic cipher context
529 * \param input buffer holding the input data
530 * \param ilen length of the input data
531 * \param output buffer for the output data. Should be able to hold at
532 * least ilen + block_size. Cannot be the same buffer as
534 * \param olen length of the output data, will be filled with the
535 * actual number of bytes written.
537 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
538 * parameter verification fails,
539 * MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an
540 * unsupported mode for a cipher or a cipher specific
543 * \note If the underlying cipher is GCM, all calls to this
544 * function, except the last one before mbedtls_cipher_finish(),
545 * must have ilen a multiple of the block size.
547 int mbedtls_cipher_update( mbedtls_cipher_context_t
*ctx
, const unsigned char *input
,
548 size_t ilen
, unsigned char *output
, size_t *olen
);
551 * \brief Generic cipher finalisation function. If data still
552 * needs to be flushed from an incomplete block, data
553 * contained within it will be padded with the size of
554 * the last block, and written to the output buffer.
556 * \param ctx Generic cipher context
557 * \param output buffer to write data to. Needs block_size available.
558 * \param olen length of the data written to the output buffer.
560 * \returns 0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if
561 * parameter verification fails,
562 * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
563 * expected a full block but was not provided one,
564 * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
565 * while decrypting or a cipher specific error code.
567 int mbedtls_cipher_finish( mbedtls_cipher_context_t
*ctx
,
568 unsigned char *output
, size_t *olen
);
570 #if defined(MBEDTLS_GCM_C)
572 * \brief Write tag for AEAD ciphers.
573 * Currently only supported with GCM.
574 * Must be called after mbedtls_cipher_finish().
576 * \param ctx Generic cipher context
577 * \param tag buffer to write the tag
578 * \param tag_len Length of the tag to write
580 * \return 0 on success, or a specific error code.
582 int mbedtls_cipher_write_tag( mbedtls_cipher_context_t
*ctx
,
583 unsigned char *tag
, size_t tag_len
);
586 * \brief Check tag for AEAD ciphers.
587 * Currently only supported with GCM.
588 * Must be called after mbedtls_cipher_finish().
590 * \param ctx Generic cipher context
591 * \param tag Buffer holding the tag
592 * \param tag_len Length of the tag to check
594 * \return 0 on success, or a specific error code.
596 int mbedtls_cipher_check_tag( mbedtls_cipher_context_t
*ctx
,
597 const unsigned char *tag
, size_t tag_len
);
598 #endif /* MBEDTLS_GCM_C */
601 * \brief Generic all-in-one encryption/decryption
602 * (for all ciphers except AEAD constructs).
604 * \param ctx generic cipher context
605 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
606 * \param iv_len IV length for ciphers with variable-size IV;
607 * discarded by ciphers with fixed-size IV.
608 * \param input buffer holding the input data
609 * \param ilen length of the input data
610 * \param output buffer for the output data. Should be able to hold at
611 * least ilen + block_size. Cannot be the same buffer as
613 * \param olen length of the output data, will be filled with the
614 * actual number of bytes written.
616 * \note Some ciphers don't use IVs nor NONCE. For these
617 * ciphers, use iv = NULL and iv_len = 0.
619 * \returns 0 on success, or
620 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
621 * MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption
622 * expected a full block but was not provided one, or
623 * MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding
624 * while decrypting, or
625 * a cipher specific error code.
627 int mbedtls_cipher_crypt( mbedtls_cipher_context_t
*ctx
,
628 const unsigned char *iv
, size_t iv_len
,
629 const unsigned char *input
, size_t ilen
,
630 unsigned char *output
, size_t *olen
);
632 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
634 * \brief Generic autenticated encryption (AEAD ciphers).
636 * \param ctx generic cipher context
637 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
638 * \param iv_len IV length for ciphers with variable-size IV;
639 * discarded by ciphers with fixed-size IV.
640 * \param ad Additional data to authenticate.
641 * \param ad_len Length of ad.
642 * \param input buffer holding the input data
643 * \param ilen length of the input data
644 * \param output buffer for the output data.
645 * Should be able to hold at least ilen.
646 * \param olen length of the output data, will be filled with the
647 * actual number of bytes written.
648 * \param tag buffer for the authentication tag
649 * \param tag_len desired tag length
651 * \returns 0 on success, or
652 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
653 * a cipher specific error code.
655 int mbedtls_cipher_auth_encrypt( mbedtls_cipher_context_t
*ctx
,
656 const unsigned char *iv
, size_t iv_len
,
657 const unsigned char *ad
, size_t ad_len
,
658 const unsigned char *input
, size_t ilen
,
659 unsigned char *output
, size_t *olen
,
660 unsigned char *tag
, size_t tag_len
);
663 * \brief Generic autenticated decryption (AEAD ciphers).
665 * \param ctx generic cipher context
666 * \param iv IV to use (or NONCE_COUNTER for CTR-mode ciphers)
667 * \param iv_len IV length for ciphers with variable-size IV;
668 * discarded by ciphers with fixed-size IV.
669 * \param ad Additional data to be authenticated.
670 * \param ad_len Length of ad.
671 * \param input buffer holding the input data
672 * \param ilen length of the input data
673 * \param output buffer for the output data.
674 * Should be able to hold at least ilen.
675 * \param olen length of the output data, will be filled with the
676 * actual number of bytes written.
677 * \param tag buffer holding the authentication tag
678 * \param tag_len length of the authentication tag
680 * \returns 0 on success, or
681 * MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or
682 * MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic,
683 * or a cipher specific error code.
685 * \note If the data is not authentic, then the output buffer
686 * is zeroed out to prevent the unauthentic plaintext to
687 * be used by mistake, making this interface safer.
689 int mbedtls_cipher_auth_decrypt( mbedtls_cipher_context_t
*ctx
,
690 const unsigned char *iv
, size_t iv_len
,
691 const unsigned char *ad
, size_t ad_len
,
692 const unsigned char *input
, size_t ilen
,
693 unsigned char *output
, size_t *olen
,
694 const unsigned char *tag
, size_t tag_len
);
695 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
701 #endif /* MBEDTLS_CIPHER_H */