EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-08-27 09:37:30
0001 /** 0002 * \file cipher.h 0003 * 0004 * \brief This file contains an abstraction interface for use with the cipher 0005 * primitives provided by the library. It provides a common interface to all of 0006 * the available cipher operations. 0007 * 0008 * \author Adriaan de Jong <dejong@fox-it.com> 0009 */ 0010 /* 0011 * Copyright The Mbed TLS Contributors 0012 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 0013 */ 0014 0015 #ifndef MBEDTLS_CIPHER_H 0016 #define MBEDTLS_CIPHER_H 0017 #include "mbedtls/private_access.h" 0018 0019 #include "mbedtls/build_info.h" 0020 0021 #include <stddef.h> 0022 #include "mbedtls/platform_util.h" 0023 0024 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C) 0025 #define MBEDTLS_CIPHER_MODE_AEAD 0026 #endif 0027 0028 #if defined(MBEDTLS_CIPHER_MODE_CBC) 0029 #define MBEDTLS_CIPHER_MODE_WITH_PADDING 0030 #endif 0031 0032 #if defined(MBEDTLS_CIPHER_NULL_CIPHER) || \ 0033 defined(MBEDTLS_CHACHA20_C) 0034 #define MBEDTLS_CIPHER_MODE_STREAM 0035 #endif 0036 0037 /** The selected feature is not available. */ 0038 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080 0039 /** Bad input parameters. */ 0040 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100 0041 /** Failed to allocate memory. */ 0042 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180 0043 /** Input data contains invalid padding and is rejected. */ 0044 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200 0045 /** Decryption of block requires a full block. */ 0046 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280 0047 /** Authentication failed (for AEAD modes). */ 0048 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300 0049 /** The context is invalid. For example, because it was freed. */ 0050 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380 0051 0052 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01 /**< Cipher accepts IVs of variable length. */ 0053 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02 /**< Cipher accepts keys of variable length. */ 0054 0055 #ifdef __cplusplus 0056 extern "C" { 0057 #endif 0058 0059 /** 0060 * \brief Supported cipher types. 0061 * 0062 * \warning DES/3DES are considered weak ciphers and their use 0063 * constitutes a security risk. We recommend considering stronger 0064 * ciphers instead. 0065 */ 0066 typedef enum { 0067 MBEDTLS_CIPHER_ID_NONE = 0, /**< Placeholder to mark the end of cipher ID lists. */ 0068 MBEDTLS_CIPHER_ID_NULL, /**< The identity cipher, treated as a stream cipher. */ 0069 MBEDTLS_CIPHER_ID_AES, /**< The AES cipher. */ 0070 MBEDTLS_CIPHER_ID_DES, /**< The DES cipher. \warning DES is considered weak. */ 0071 MBEDTLS_CIPHER_ID_3DES, /**< The Triple DES cipher. \warning 3DES is considered weak. */ 0072 MBEDTLS_CIPHER_ID_CAMELLIA, /**< The Camellia cipher. */ 0073 MBEDTLS_CIPHER_ID_ARIA, /**< The Aria cipher. */ 0074 MBEDTLS_CIPHER_ID_CHACHA20, /**< The ChaCha20 cipher. */ 0075 } mbedtls_cipher_id_t; 0076 0077 /** 0078 * \brief Supported {cipher type, cipher mode} pairs. 0079 * 0080 * \warning DES/3DES are considered weak ciphers and their use 0081 * constitutes a security risk. We recommend considering stronger 0082 * ciphers instead. 0083 */ 0084 typedef enum { 0085 MBEDTLS_CIPHER_NONE = 0, /**< Placeholder to mark the end of cipher-pair lists. */ 0086 MBEDTLS_CIPHER_NULL, /**< The identity stream cipher. */ 0087 MBEDTLS_CIPHER_AES_128_ECB, /**< AES cipher with 128-bit ECB mode. */ 0088 MBEDTLS_CIPHER_AES_192_ECB, /**< AES cipher with 192-bit ECB mode. */ 0089 MBEDTLS_CIPHER_AES_256_ECB, /**< AES cipher with 256-bit ECB mode. */ 0090 MBEDTLS_CIPHER_AES_128_CBC, /**< AES cipher with 128-bit CBC mode. */ 0091 MBEDTLS_CIPHER_AES_192_CBC, /**< AES cipher with 192-bit CBC mode. */ 0092 MBEDTLS_CIPHER_AES_256_CBC, /**< AES cipher with 256-bit CBC mode. */ 0093 MBEDTLS_CIPHER_AES_128_CFB128, /**< AES cipher with 128-bit CFB128 mode. */ 0094 MBEDTLS_CIPHER_AES_192_CFB128, /**< AES cipher with 192-bit CFB128 mode. */ 0095 MBEDTLS_CIPHER_AES_256_CFB128, /**< AES cipher with 256-bit CFB128 mode. */ 0096 MBEDTLS_CIPHER_AES_128_CTR, /**< AES cipher with 128-bit CTR mode. */ 0097 MBEDTLS_CIPHER_AES_192_CTR, /**< AES cipher with 192-bit CTR mode. */ 0098 MBEDTLS_CIPHER_AES_256_CTR, /**< AES cipher with 256-bit CTR mode. */ 0099 MBEDTLS_CIPHER_AES_128_GCM, /**< AES cipher with 128-bit GCM mode. */ 0100 MBEDTLS_CIPHER_AES_192_GCM, /**< AES cipher with 192-bit GCM mode. */ 0101 MBEDTLS_CIPHER_AES_256_GCM, /**< AES cipher with 256-bit GCM mode. */ 0102 MBEDTLS_CIPHER_CAMELLIA_128_ECB, /**< Camellia cipher with 128-bit ECB mode. */ 0103 MBEDTLS_CIPHER_CAMELLIA_192_ECB, /**< Camellia cipher with 192-bit ECB mode. */ 0104 MBEDTLS_CIPHER_CAMELLIA_256_ECB, /**< Camellia cipher with 256-bit ECB mode. */ 0105 MBEDTLS_CIPHER_CAMELLIA_128_CBC, /**< Camellia cipher with 128-bit CBC mode. */ 0106 MBEDTLS_CIPHER_CAMELLIA_192_CBC, /**< Camellia cipher with 192-bit CBC mode. */ 0107 MBEDTLS_CIPHER_CAMELLIA_256_CBC, /**< Camellia cipher with 256-bit CBC mode. */ 0108 MBEDTLS_CIPHER_CAMELLIA_128_CFB128, /**< Camellia cipher with 128-bit CFB128 mode. */ 0109 MBEDTLS_CIPHER_CAMELLIA_192_CFB128, /**< Camellia cipher with 192-bit CFB128 mode. */ 0110 MBEDTLS_CIPHER_CAMELLIA_256_CFB128, /**< Camellia cipher with 256-bit CFB128 mode. */ 0111 MBEDTLS_CIPHER_CAMELLIA_128_CTR, /**< Camellia cipher with 128-bit CTR mode. */ 0112 MBEDTLS_CIPHER_CAMELLIA_192_CTR, /**< Camellia cipher with 192-bit CTR mode. */ 0113 MBEDTLS_CIPHER_CAMELLIA_256_CTR, /**< Camellia cipher with 256-bit CTR mode. */ 0114 MBEDTLS_CIPHER_CAMELLIA_128_GCM, /**< Camellia cipher with 128-bit GCM mode. */ 0115 MBEDTLS_CIPHER_CAMELLIA_192_GCM, /**< Camellia cipher with 192-bit GCM mode. */ 0116 MBEDTLS_CIPHER_CAMELLIA_256_GCM, /**< Camellia cipher with 256-bit GCM mode. */ 0117 MBEDTLS_CIPHER_DES_ECB, /**< DES cipher with ECB mode. \warning DES is considered weak. */ 0118 MBEDTLS_CIPHER_DES_CBC, /**< DES cipher with CBC mode. \warning DES is considered weak. */ 0119 MBEDTLS_CIPHER_DES_EDE_ECB, /**< DES cipher with EDE ECB mode. \warning 3DES is considered weak. */ 0120 MBEDTLS_CIPHER_DES_EDE_CBC, /**< DES cipher with EDE CBC mode. \warning 3DES is considered weak. */ 0121 MBEDTLS_CIPHER_DES_EDE3_ECB, /**< DES cipher with EDE3 ECB mode. \warning 3DES is considered weak. */ 0122 MBEDTLS_CIPHER_DES_EDE3_CBC, /**< DES cipher with EDE3 CBC mode. \warning 3DES is considered weak. */ 0123 MBEDTLS_CIPHER_AES_128_CCM, /**< AES cipher with 128-bit CCM mode. */ 0124 MBEDTLS_CIPHER_AES_192_CCM, /**< AES cipher with 192-bit CCM mode. */ 0125 MBEDTLS_CIPHER_AES_256_CCM, /**< AES cipher with 256-bit CCM mode. */ 0126 MBEDTLS_CIPHER_AES_128_CCM_STAR_NO_TAG, /**< AES cipher with 128-bit CCM_STAR_NO_TAG mode. */ 0127 MBEDTLS_CIPHER_AES_192_CCM_STAR_NO_TAG, /**< AES cipher with 192-bit CCM_STAR_NO_TAG mode. */ 0128 MBEDTLS_CIPHER_AES_256_CCM_STAR_NO_TAG, /**< AES cipher with 256-bit CCM_STAR_NO_TAG mode. */ 0129 MBEDTLS_CIPHER_CAMELLIA_128_CCM, /**< Camellia cipher with 128-bit CCM mode. */ 0130 MBEDTLS_CIPHER_CAMELLIA_192_CCM, /**< Camellia cipher with 192-bit CCM mode. */ 0131 MBEDTLS_CIPHER_CAMELLIA_256_CCM, /**< Camellia cipher with 256-bit CCM mode. */ 0132 MBEDTLS_CIPHER_CAMELLIA_128_CCM_STAR_NO_TAG, /**< Camellia cipher with 128-bit CCM_STAR_NO_TAG mode. */ 0133 MBEDTLS_CIPHER_CAMELLIA_192_CCM_STAR_NO_TAG, /**< Camellia cipher with 192-bit CCM_STAR_NO_TAG mode. */ 0134 MBEDTLS_CIPHER_CAMELLIA_256_CCM_STAR_NO_TAG, /**< Camellia cipher with 256-bit CCM_STAR_NO_TAG mode. */ 0135 MBEDTLS_CIPHER_ARIA_128_ECB, /**< Aria cipher with 128-bit key and ECB mode. */ 0136 MBEDTLS_CIPHER_ARIA_192_ECB, /**< Aria cipher with 192-bit key and ECB mode. */ 0137 MBEDTLS_CIPHER_ARIA_256_ECB, /**< Aria cipher with 256-bit key and ECB mode. */ 0138 MBEDTLS_CIPHER_ARIA_128_CBC, /**< Aria cipher with 128-bit key and CBC mode. */ 0139 MBEDTLS_CIPHER_ARIA_192_CBC, /**< Aria cipher with 192-bit key and CBC mode. */ 0140 MBEDTLS_CIPHER_ARIA_256_CBC, /**< Aria cipher with 256-bit key and CBC mode. */ 0141 MBEDTLS_CIPHER_ARIA_128_CFB128, /**< Aria cipher with 128-bit key and CFB-128 mode. */ 0142 MBEDTLS_CIPHER_ARIA_192_CFB128, /**< Aria cipher with 192-bit key and CFB-128 mode. */ 0143 MBEDTLS_CIPHER_ARIA_256_CFB128, /**< Aria cipher with 256-bit key and CFB-128 mode. */ 0144 MBEDTLS_CIPHER_ARIA_128_CTR, /**< Aria cipher with 128-bit key and CTR mode. */ 0145 MBEDTLS_CIPHER_ARIA_192_CTR, /**< Aria cipher with 192-bit key and CTR mode. */ 0146 MBEDTLS_CIPHER_ARIA_256_CTR, /**< Aria cipher with 256-bit key and CTR mode. */ 0147 MBEDTLS_CIPHER_ARIA_128_GCM, /**< Aria cipher with 128-bit key and GCM mode. */ 0148 MBEDTLS_CIPHER_ARIA_192_GCM, /**< Aria cipher with 192-bit key and GCM mode. */ 0149 MBEDTLS_CIPHER_ARIA_256_GCM, /**< Aria cipher with 256-bit key and GCM mode. */ 0150 MBEDTLS_CIPHER_ARIA_128_CCM, /**< Aria cipher with 128-bit key and CCM mode. */ 0151 MBEDTLS_CIPHER_ARIA_192_CCM, /**< Aria cipher with 192-bit key and CCM mode. */ 0152 MBEDTLS_CIPHER_ARIA_256_CCM, /**< Aria cipher with 256-bit key and CCM mode. */ 0153 MBEDTLS_CIPHER_ARIA_128_CCM_STAR_NO_TAG, /**< Aria cipher with 128-bit key and CCM_STAR_NO_TAG mode. */ 0154 MBEDTLS_CIPHER_ARIA_192_CCM_STAR_NO_TAG, /**< Aria cipher with 192-bit key and CCM_STAR_NO_TAG mode. */ 0155 MBEDTLS_CIPHER_ARIA_256_CCM_STAR_NO_TAG, /**< Aria cipher with 256-bit key and CCM_STAR_NO_TAG mode. */ 0156 MBEDTLS_CIPHER_AES_128_OFB, /**< AES 128-bit cipher in OFB mode. */ 0157 MBEDTLS_CIPHER_AES_192_OFB, /**< AES 192-bit cipher in OFB mode. */ 0158 MBEDTLS_CIPHER_AES_256_OFB, /**< AES 256-bit cipher in OFB mode. */ 0159 MBEDTLS_CIPHER_AES_128_XTS, /**< AES 128-bit cipher in XTS block mode. */ 0160 MBEDTLS_CIPHER_AES_256_XTS, /**< AES 256-bit cipher in XTS block mode. */ 0161 MBEDTLS_CIPHER_CHACHA20, /**< ChaCha20 stream cipher. */ 0162 MBEDTLS_CIPHER_CHACHA20_POLY1305, /**< ChaCha20-Poly1305 AEAD cipher. */ 0163 MBEDTLS_CIPHER_AES_128_KW, /**< AES cipher with 128-bit NIST KW mode. */ 0164 MBEDTLS_CIPHER_AES_192_KW, /**< AES cipher with 192-bit NIST KW mode. */ 0165 MBEDTLS_CIPHER_AES_256_KW, /**< AES cipher with 256-bit NIST KW mode. */ 0166 MBEDTLS_CIPHER_AES_128_KWP, /**< AES cipher with 128-bit NIST KWP mode. */ 0167 MBEDTLS_CIPHER_AES_192_KWP, /**< AES cipher with 192-bit NIST KWP mode. */ 0168 MBEDTLS_CIPHER_AES_256_KWP, /**< AES cipher with 256-bit NIST KWP mode. */ 0169 } mbedtls_cipher_type_t; 0170 0171 /** Supported cipher modes. */ 0172 typedef enum { 0173 MBEDTLS_MODE_NONE = 0, /**< None. */ 0174 MBEDTLS_MODE_ECB, /**< The ECB cipher mode. */ 0175 MBEDTLS_MODE_CBC, /**< The CBC cipher mode. */ 0176 MBEDTLS_MODE_CFB, /**< The CFB cipher mode. */ 0177 MBEDTLS_MODE_OFB, /**< The OFB cipher mode. */ 0178 MBEDTLS_MODE_CTR, /**< The CTR cipher mode. */ 0179 MBEDTLS_MODE_GCM, /**< The GCM cipher mode. */ 0180 MBEDTLS_MODE_STREAM, /**< The stream cipher mode. */ 0181 MBEDTLS_MODE_CCM, /**< The CCM cipher mode. */ 0182 MBEDTLS_MODE_CCM_STAR_NO_TAG, /**< The CCM*-no-tag cipher mode. */ 0183 MBEDTLS_MODE_XTS, /**< The XTS cipher mode. */ 0184 MBEDTLS_MODE_CHACHAPOLY, /**< The ChaCha-Poly cipher mode. */ 0185 MBEDTLS_MODE_KW, /**< The SP800-38F KW mode */ 0186 MBEDTLS_MODE_KWP, /**< The SP800-38F KWP mode */ 0187 } mbedtls_cipher_mode_t; 0188 0189 /** Supported cipher padding types. */ 0190 typedef enum { 0191 MBEDTLS_PADDING_PKCS7 = 0, /**< PKCS7 padding (default). */ 0192 MBEDTLS_PADDING_ONE_AND_ZEROS, /**< ISO/IEC 7816-4 padding. */ 0193 MBEDTLS_PADDING_ZEROS_AND_LEN, /**< ANSI X.923 padding. */ 0194 MBEDTLS_PADDING_ZEROS, /**< Zero padding (not reversible). */ 0195 MBEDTLS_PADDING_NONE, /**< Never pad (full blocks only). */ 0196 } mbedtls_cipher_padding_t; 0197 0198 /** Type of operation. */ 0199 typedef enum { 0200 MBEDTLS_OPERATION_NONE = -1, 0201 MBEDTLS_DECRYPT = 0, 0202 MBEDTLS_ENCRYPT, 0203 } mbedtls_operation_t; 0204 0205 enum { 0206 /** Undefined key length. */ 0207 MBEDTLS_KEY_LENGTH_NONE = 0, 0208 /** Key length, in bits (including parity), for DES keys. \warning DES is considered weak. */ 0209 MBEDTLS_KEY_LENGTH_DES = 64, 0210 /** Key length in bits, including parity, for DES in two-key EDE. \warning 3DES is considered weak. */ 0211 MBEDTLS_KEY_LENGTH_DES_EDE = 128, 0212 /** Key length in bits, including parity, for DES in three-key EDE. \warning 3DES is considered weak. */ 0213 MBEDTLS_KEY_LENGTH_DES_EDE3 = 192, 0214 }; 0215 0216 /** Maximum length of any IV, in Bytes. */ 0217 /* This should ideally be derived automatically from list of ciphers. 0218 * This should be kept in sync with MBEDTLS_SSL_MAX_IV_LENGTH defined 0219 * in library/ssl_misc.h. */ 0220 #define MBEDTLS_MAX_IV_LENGTH 16 0221 0222 /** Maximum block size of any cipher, in Bytes. */ 0223 /* This should ideally be derived automatically from list of ciphers. 0224 * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined 0225 * in library/ssl_misc.h. */ 0226 #define MBEDTLS_MAX_BLOCK_LENGTH 16 0227 0228 /** Maximum key length, in Bytes. */ 0229 /* This should ideally be derived automatically from list of ciphers. 0230 * For now, only check whether XTS is enabled which uses 64 Byte keys, 0231 * and use 32 Bytes as an upper bound for the maximum key length otherwise. 0232 * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined 0233 * in library/ssl_misc.h, which however deliberately ignores the case of XTS 0234 * since the latter isn't used in SSL/TLS. */ 0235 #if defined(MBEDTLS_CIPHER_MODE_XTS) 0236 #define MBEDTLS_MAX_KEY_LENGTH 64 0237 #else 0238 #define MBEDTLS_MAX_KEY_LENGTH 32 0239 #endif /* MBEDTLS_CIPHER_MODE_XTS */ 0240 0241 /** 0242 * Base cipher information (opaque struct). 0243 */ 0244 typedef struct mbedtls_cipher_base_t mbedtls_cipher_base_t; 0245 0246 /** 0247 * CMAC context (opaque struct). 0248 */ 0249 typedef struct mbedtls_cmac_context_t mbedtls_cmac_context_t; 0250 0251 /** 0252 * Cipher information. Allows calling cipher functions 0253 * in a generic way. 0254 * 0255 * \note The library does not support custom cipher info structures, 0256 * only built-in structures returned by the functions 0257 * mbedtls_cipher_info_from_string(), 0258 * mbedtls_cipher_info_from_type(), 0259 * mbedtls_cipher_info_from_values(), 0260 * mbedtls_cipher_info_from_psa(). 0261 * 0262 * \note Some fields store a value that has been right-shifted to save 0263 * code-size, so should not be used directly. The accessor 0264 * functions adjust for this and return the "natural" value. 0265 */ 0266 typedef struct mbedtls_cipher_info_t { 0267 /** Name of the cipher. */ 0268 const char *MBEDTLS_PRIVATE(name); 0269 0270 /** The block size, in bytes. */ 0271 unsigned int MBEDTLS_PRIVATE(block_size) : 5; 0272 0273 /** IV or nonce size, in bytes (right shifted by #MBEDTLS_IV_SIZE_SHIFT). 0274 * For ciphers that accept variable IV sizes, 0275 * this is the recommended size. 0276 */ 0277 unsigned int MBEDTLS_PRIVATE(iv_size) : 3; 0278 0279 /** The cipher key length, in bits (right shifted by #MBEDTLS_KEY_BITLEN_SHIFT). 0280 * This is the default length for variable sized ciphers. 0281 * Includes parity bits for ciphers like DES. 0282 */ 0283 unsigned int MBEDTLS_PRIVATE(key_bitlen) : 4; 0284 0285 /** The cipher mode (as per mbedtls_cipher_mode_t). 0286 * For example, MBEDTLS_MODE_CBC. 0287 */ 0288 unsigned int MBEDTLS_PRIVATE(mode) : 4; 0289 0290 /** Full cipher identifier (as per mbedtls_cipher_type_t). 0291 * For example, MBEDTLS_CIPHER_AES_256_CBC. 0292 * 0293 * This could be 7 bits, but 8 bits retains byte alignment for the 0294 * next field, which reduces code size to access that field. 0295 */ 0296 unsigned int MBEDTLS_PRIVATE(type) : 8; 0297 0298 /** Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and 0299 * MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating whether the 0300 * cipher supports variable IV or variable key sizes, respectively. 0301 */ 0302 unsigned int MBEDTLS_PRIVATE(flags) : 2; 0303 0304 /** Index to LUT for base cipher information and functions. */ 0305 unsigned int MBEDTLS_PRIVATE(base_idx) : 5; 0306 0307 } mbedtls_cipher_info_t; 0308 0309 /* For internal use only. 0310 * These are used to more compactly represent the fields above. */ 0311 #define MBEDTLS_KEY_BITLEN_SHIFT 6 0312 #define MBEDTLS_IV_SIZE_SHIFT 2 0313 /** 0314 * Generic cipher context. 0315 */ 0316 typedef struct mbedtls_cipher_context_t { 0317 /** Information about the associated cipher. */ 0318 const mbedtls_cipher_info_t *MBEDTLS_PRIVATE(cipher_info); 0319 0320 /** Key length to use. */ 0321 int MBEDTLS_PRIVATE(key_bitlen); 0322 0323 /** Operation that the key of the context has been 0324 * initialized for. 0325 */ 0326 mbedtls_operation_t MBEDTLS_PRIVATE(operation); 0327 0328 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) 0329 /** Padding functions to use, if relevant for 0330 * the specific cipher mode. 0331 */ 0332 void(*MBEDTLS_PRIVATE(add_padding))(unsigned char *output, size_t olen, size_t data_len); 0333 int(*MBEDTLS_PRIVATE(get_padding))(unsigned char *input, size_t ilen, size_t *data_len); 0334 #endif 0335 0336 /** Buffer for input that has not been processed yet. */ 0337 unsigned char MBEDTLS_PRIVATE(unprocessed_data)[MBEDTLS_MAX_BLOCK_LENGTH]; 0338 0339 /** Number of Bytes that have not been processed yet. */ 0340 size_t MBEDTLS_PRIVATE(unprocessed_len); 0341 0342 /** Current IV or NONCE_COUNTER for CTR-mode, data unit (or sector) number 0343 * for XTS-mode. */ 0344 unsigned char MBEDTLS_PRIVATE(iv)[MBEDTLS_MAX_IV_LENGTH]; 0345 0346 /** IV size in Bytes, for ciphers with variable-length IVs. */ 0347 size_t MBEDTLS_PRIVATE(iv_size); 0348 0349 /** The cipher-specific context. */ 0350 void *MBEDTLS_PRIVATE(cipher_ctx); 0351 0352 #if defined(MBEDTLS_CMAC_C) 0353 /** CMAC-specific context. */ 0354 mbedtls_cmac_context_t *MBEDTLS_PRIVATE(cmac_ctx); 0355 #endif 0356 0357 #if defined(MBEDTLS_USE_PSA_CRYPTO) && !defined(MBEDTLS_DEPRECATED_REMOVED) 0358 /** Indicates whether the cipher operations should be performed 0359 * by Mbed TLS' own crypto library or an external implementation 0360 * of the PSA Crypto API. 0361 * This is unset if the cipher context was established through 0362 * mbedtls_cipher_setup(), and set if it was established through 0363 * mbedtls_cipher_setup_psa(). 0364 */ 0365 unsigned char MBEDTLS_PRIVATE(psa_enabled); 0366 #endif /* MBEDTLS_USE_PSA_CRYPTO && !MBEDTLS_DEPRECATED_REMOVED */ 0367 0368 } mbedtls_cipher_context_t; 0369 0370 /** 0371 * \brief This function retrieves the list of ciphers supported 0372 * by the generic cipher module. 0373 * 0374 * For any cipher identifier in the returned list, you can 0375 * obtain the corresponding generic cipher information structure 0376 * via mbedtls_cipher_info_from_type(), which can then be used 0377 * to prepare a cipher context via mbedtls_cipher_setup(). 0378 * 0379 * 0380 * \return A statically-allocated array of cipher identifiers 0381 * of type cipher_type_t. The last entry is zero. 0382 */ 0383 const int *mbedtls_cipher_list(void); 0384 0385 /** 0386 * \brief This function retrieves the cipher-information 0387 * structure associated with the given cipher name. 0388 * 0389 * \param cipher_name Name of the cipher to search for. This must not be 0390 * \c NULL. 0391 * 0392 * \return The cipher information structure associated with the 0393 * given \p cipher_name. 0394 * \return \c NULL if the associated cipher information is not found. 0395 */ 0396 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string(const char *cipher_name); 0397 0398 /** 0399 * \brief This function retrieves the cipher-information 0400 * structure associated with the given cipher type. 0401 * 0402 * \param cipher_type Type of the cipher to search for. 0403 * 0404 * \return The cipher information structure associated with the 0405 * given \p cipher_type. 0406 * \return \c NULL if the associated cipher information is not found. 0407 */ 0408 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type(const mbedtls_cipher_type_t cipher_type); 0409 0410 /** 0411 * \brief This function retrieves the cipher-information 0412 * structure associated with the given cipher ID, 0413 * key size and mode. 0414 * 0415 * \param cipher_id The ID of the cipher to search for. For example, 0416 * #MBEDTLS_CIPHER_ID_AES. 0417 * \param key_bitlen The length of the key in bits. 0418 * \param mode The cipher mode. For example, #MBEDTLS_MODE_CBC. 0419 * 0420 * \return The cipher information structure associated with the 0421 * given \p cipher_id. 0422 * \return \c NULL if the associated cipher information is not found. 0423 */ 0424 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values(const mbedtls_cipher_id_t cipher_id, 0425 int key_bitlen, 0426 const mbedtls_cipher_mode_t mode); 0427 0428 /** 0429 * \brief Retrieve the identifier for a cipher info structure. 0430 * 0431 * \param[in] info The cipher info structure to query. 0432 * This may be \c NULL. 0433 * 0434 * \return The full cipher identifier (\c MBEDTLS_CIPHER_xxx). 0435 * \return #MBEDTLS_CIPHER_NONE if \p info is \c NULL. 0436 */ 0437 static inline mbedtls_cipher_type_t mbedtls_cipher_info_get_type( 0438 const mbedtls_cipher_info_t *info) 0439 { 0440 if (info == NULL) { 0441 return MBEDTLS_CIPHER_NONE; 0442 } else { 0443 return (mbedtls_cipher_type_t) info->MBEDTLS_PRIVATE(type); 0444 } 0445 } 0446 0447 /** 0448 * \brief Retrieve the operation mode for a cipher info structure. 0449 * 0450 * \param[in] info The cipher info structure to query. 0451 * This may be \c NULL. 0452 * 0453 * \return The cipher mode (\c MBEDTLS_MODE_xxx). 0454 * \return #MBEDTLS_MODE_NONE if \p info is \c NULL. 0455 */ 0456 static inline mbedtls_cipher_mode_t mbedtls_cipher_info_get_mode( 0457 const mbedtls_cipher_info_t *info) 0458 { 0459 if (info == NULL) { 0460 return MBEDTLS_MODE_NONE; 0461 } else { 0462 return (mbedtls_cipher_mode_t) info->MBEDTLS_PRIVATE(mode); 0463 } 0464 } 0465 0466 /** 0467 * \brief Retrieve the key size for a cipher info structure. 0468 * 0469 * \param[in] info The cipher info structure to query. 0470 * This may be \c NULL. 0471 * 0472 * \return The key length in bits. 0473 * For variable-sized ciphers, this is the default length. 0474 * For DES, this includes the parity bits. 0475 * \return \c 0 if \p info is \c NULL. 0476 */ 0477 static inline size_t mbedtls_cipher_info_get_key_bitlen( 0478 const mbedtls_cipher_info_t *info) 0479 { 0480 if (info == NULL) { 0481 return 0; 0482 } else { 0483 return ((size_t) info->MBEDTLS_PRIVATE(key_bitlen)) << MBEDTLS_KEY_BITLEN_SHIFT; 0484 } 0485 } 0486 0487 /** 0488 * \brief Retrieve the human-readable name for a 0489 * cipher info structure. 0490 * 0491 * \param[in] info The cipher info structure to query. 0492 * This may be \c NULL. 0493 * 0494 * \return The cipher name, which is a human readable string, 0495 * with static storage duration. 0496 * \return \c NULL if \p info is \c NULL. 0497 */ 0498 static inline const char *mbedtls_cipher_info_get_name( 0499 const mbedtls_cipher_info_t *info) 0500 { 0501 if (info == NULL) { 0502 return NULL; 0503 } else { 0504 return info->MBEDTLS_PRIVATE(name); 0505 } 0506 } 0507 0508 /** 0509 * \brief This function returns the size of the IV or nonce 0510 * for the cipher info structure, in bytes. 0511 * 0512 * \param info The cipher info structure. This may be \c NULL. 0513 * 0514 * \return The recommended IV size. 0515 * \return \c 0 for ciphers not using an IV or a nonce. 0516 * \return \c 0 if \p info is \c NULL. 0517 */ 0518 static inline size_t mbedtls_cipher_info_get_iv_size( 0519 const mbedtls_cipher_info_t *info) 0520 { 0521 if (info == NULL) { 0522 return 0; 0523 } 0524 0525 return ((size_t) info->MBEDTLS_PRIVATE(iv_size)) << MBEDTLS_IV_SIZE_SHIFT; 0526 } 0527 0528 /** 0529 * \brief This function returns the block size of the given 0530 * cipher info structure in bytes. 0531 * 0532 * \param info The cipher info structure. This may be \c NULL. 0533 * 0534 * \return The block size of the cipher. 0535 * \return \c 1 if the cipher is a stream cipher. 0536 * \return \c 0 if \p info is \c NULL. 0537 */ 0538 static inline size_t mbedtls_cipher_info_get_block_size( 0539 const mbedtls_cipher_info_t *info) 0540 { 0541 if (info == NULL) { 0542 return 0; 0543 } 0544 0545 return (size_t) (info->MBEDTLS_PRIVATE(block_size)); 0546 } 0547 0548 /** 0549 * \brief This function returns a non-zero value if the key length for 0550 * the given cipher is variable. 0551 * 0552 * \param info The cipher info structure. This may be \c NULL. 0553 * 0554 * \return Non-zero if the key length is variable, \c 0 otherwise. 0555 * \return \c 0 if the given pointer is \c NULL. 0556 */ 0557 static inline int mbedtls_cipher_info_has_variable_key_bitlen( 0558 const mbedtls_cipher_info_t *info) 0559 { 0560 if (info == NULL) { 0561 return 0; 0562 } 0563 0564 return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_KEY_LEN; 0565 } 0566 0567 /** 0568 * \brief This function returns a non-zero value if the IV size for 0569 * the given cipher is variable. 0570 * 0571 * \param info The cipher info structure. This may be \c NULL. 0572 * 0573 * \return Non-zero if the IV size is variable, \c 0 otherwise. 0574 * \return \c 0 if the given pointer is \c NULL. 0575 */ 0576 static inline int mbedtls_cipher_info_has_variable_iv_size( 0577 const mbedtls_cipher_info_t *info) 0578 { 0579 if (info == NULL) { 0580 return 0; 0581 } 0582 0583 return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_IV_LEN; 0584 } 0585 0586 /** 0587 * \brief This function initializes a \p ctx as NONE. 0588 * 0589 * \param ctx The context to be initialized. This must not be \c NULL. 0590 */ 0591 void mbedtls_cipher_init(mbedtls_cipher_context_t *ctx); 0592 0593 /** 0594 * \brief This function frees and clears the cipher-specific 0595 * context of \p ctx. Freeing \p ctx itself remains the 0596 * responsibility of the caller. 0597 * 0598 * \param ctx The context to be freed. If this is \c NULL, the 0599 * function has no effect, otherwise this must point to an 0600 * initialized context. 0601 */ 0602 void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx); 0603 0604 0605 /** 0606 * \brief This function prepares a cipher context for 0607 * use with the given cipher primitive. 0608 * 0609 * \note After calling this function, you should call 0610 * mbedtls_cipher_setkey() and, if the mode uses padding, 0611 * mbedtls_cipher_set_padding_mode(), then for each 0612 * message to encrypt or decrypt with this key, either: 0613 * - mbedtls_cipher_crypt() for one-shot processing with 0614 * non-AEAD modes; 0615 * - mbedtls_cipher_auth_encrypt_ext() or 0616 * mbedtls_cipher_auth_decrypt_ext() for one-shot 0617 * processing with AEAD modes or NIST_KW; 0618 * - for multi-part processing, see the documentation of 0619 * mbedtls_cipher_reset(). 0620 * 0621 * \param ctx The context to prepare. This must be initialized by 0622 * a call to mbedtls_cipher_init() first. 0623 * \param cipher_info The cipher to use. 0624 * 0625 * \return \c 0 on success. 0626 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0627 * parameter-verification failure. 0628 * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the 0629 * cipher-specific context fails. 0630 */ 0631 int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx, 0632 const mbedtls_cipher_info_t *cipher_info); 0633 0634 #if defined(MBEDTLS_USE_PSA_CRYPTO) 0635 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 0636 /** 0637 * \brief This function initializes a cipher context for 0638 * PSA-based use with the given cipher primitive. 0639 * 0640 * \deprecated This function is deprecated and will be removed in a 0641 * future version of the library. 0642 * Please use psa_aead_xxx() / psa_cipher_xxx() directly 0643 * instead. 0644 * 0645 * \note See #MBEDTLS_USE_PSA_CRYPTO for information on PSA. 0646 * 0647 * \param ctx The context to initialize. May not be \c NULL. 0648 * \param cipher_info The cipher to use. 0649 * \param taglen For AEAD ciphers, the length in bytes of the 0650 * authentication tag to use. Subsequent uses of 0651 * mbedtls_cipher_auth_encrypt_ext() or 0652 * mbedtls_cipher_auth_decrypt_ext() must provide 0653 * the same tag length. 0654 * For non-AEAD ciphers, the value must be \c 0. 0655 * 0656 * \return \c 0 on success. 0657 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0658 * parameter-verification failure. 0659 * \return #MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the 0660 * cipher-specific context fails. 0661 */ 0662 int MBEDTLS_DEPRECATED mbedtls_cipher_setup_psa(mbedtls_cipher_context_t *ctx, 0663 const mbedtls_cipher_info_t *cipher_info, 0664 size_t taglen); 0665 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 0666 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 0667 0668 /** 0669 * \brief This function returns the block size of the given cipher 0670 * in bytes. 0671 * 0672 * \param ctx The context of the cipher. 0673 * 0674 * \return The block size of the underlying cipher. 0675 * \return \c 1 if the cipher is a stream cipher. 0676 * \return \c 0 if \p ctx has not been initialized. 0677 */ 0678 static inline unsigned int mbedtls_cipher_get_block_size( 0679 const mbedtls_cipher_context_t *ctx) 0680 { 0681 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0682 return 0; 0683 } 0684 0685 return (unsigned int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(block_size); 0686 } 0687 0688 /** 0689 * \brief This function returns the mode of operation for 0690 * the cipher. For example, MBEDTLS_MODE_CBC. 0691 * 0692 * \param ctx The context of the cipher. This must be initialized. 0693 * 0694 * \return The mode of operation. 0695 * \return #MBEDTLS_MODE_NONE if \p ctx has not been initialized. 0696 */ 0697 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( 0698 const mbedtls_cipher_context_t *ctx) 0699 { 0700 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0701 return MBEDTLS_MODE_NONE; 0702 } 0703 0704 return (mbedtls_cipher_mode_t) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(mode); 0705 } 0706 0707 /** 0708 * \brief This function returns the size of the IV or nonce 0709 * of the cipher, in Bytes. 0710 * 0711 * \param ctx The context of the cipher. This must be initialized. 0712 * 0713 * \return The recommended IV size if no IV has been set. 0714 * \return \c 0 for ciphers not using an IV or a nonce. 0715 * \return The actual size if an IV has been set. 0716 */ 0717 static inline int mbedtls_cipher_get_iv_size( 0718 const mbedtls_cipher_context_t *ctx) 0719 { 0720 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0721 return 0; 0722 } 0723 0724 if (ctx->MBEDTLS_PRIVATE(iv_size) != 0) { 0725 return (int) ctx->MBEDTLS_PRIVATE(iv_size); 0726 } 0727 0728 return (int) (((int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(iv_size)) << 0729 MBEDTLS_IV_SIZE_SHIFT); 0730 } 0731 0732 /** 0733 * \brief This function returns the type of the given cipher. 0734 * 0735 * \param ctx The context of the cipher. This must be initialized. 0736 * 0737 * \return The type of the cipher. 0738 * \return #MBEDTLS_CIPHER_NONE if \p ctx has not been initialized. 0739 */ 0740 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( 0741 const mbedtls_cipher_context_t *ctx) 0742 { 0743 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0744 return MBEDTLS_CIPHER_NONE; 0745 } 0746 0747 return (mbedtls_cipher_type_t) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(type); 0748 } 0749 0750 /** 0751 * \brief This function returns the name of the given cipher 0752 * as a string. 0753 * 0754 * \param ctx The context of the cipher. This must be initialized. 0755 * 0756 * \return The name of the cipher. 0757 * \return NULL if \p ctx has not been not initialized. 0758 */ 0759 static inline const char *mbedtls_cipher_get_name( 0760 const mbedtls_cipher_context_t *ctx) 0761 { 0762 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0763 return 0; 0764 } 0765 0766 return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(name); 0767 } 0768 0769 /** 0770 * \brief This function returns the key length of the cipher. 0771 * 0772 * \param ctx The context of the cipher. This must be initialized. 0773 * 0774 * \return The key length of the cipher in bits. 0775 * \return #MBEDTLS_KEY_LENGTH_NONE if \p ctx has not been 0776 * initialized. 0777 */ 0778 static inline int mbedtls_cipher_get_key_bitlen( 0779 const mbedtls_cipher_context_t *ctx) 0780 { 0781 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0782 return MBEDTLS_KEY_LENGTH_NONE; 0783 } 0784 0785 return (int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(key_bitlen) << 0786 MBEDTLS_KEY_BITLEN_SHIFT; 0787 } 0788 0789 /** 0790 * \brief This function returns the operation of the given cipher. 0791 * 0792 * \param ctx The context of the cipher. This must be initialized. 0793 * 0794 * \return The type of operation: #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. 0795 * \return #MBEDTLS_OPERATION_NONE if \p ctx has not been initialized. 0796 */ 0797 static inline mbedtls_operation_t mbedtls_cipher_get_operation( 0798 const mbedtls_cipher_context_t *ctx) 0799 { 0800 if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) { 0801 return MBEDTLS_OPERATION_NONE; 0802 } 0803 0804 return ctx->MBEDTLS_PRIVATE(operation); 0805 } 0806 0807 /** 0808 * \brief This function sets the key to use with the given context. 0809 * 0810 * \param ctx The generic cipher context. This must be initialized and 0811 * bound to a cipher information structure. 0812 * \param key The key to use. This must be a readable buffer of at 0813 * least \p key_bitlen Bits. 0814 * \param key_bitlen The key length to use, in Bits. 0815 * \param operation The operation that the key will be used for: 0816 * #MBEDTLS_ENCRYPT or #MBEDTLS_DECRYPT. 0817 * 0818 * \return \c 0 on success. 0819 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0820 * parameter-verification failure. 0821 * \return A cipher-specific error code on failure. 0822 */ 0823 int mbedtls_cipher_setkey(mbedtls_cipher_context_t *ctx, 0824 const unsigned char *key, 0825 int key_bitlen, 0826 const mbedtls_operation_t operation); 0827 0828 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING) 0829 /** 0830 * \brief This function sets the padding mode, for cipher modes 0831 * that use padding. 0832 * 0833 * 0834 * \param ctx The generic cipher context. This must be initialized and 0835 * bound to a cipher information structure. 0836 * \param mode The padding mode. 0837 * 0838 * \return \c 0 on success. 0839 * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE 0840 * if the selected padding mode is not supported. 0841 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode 0842 * does not support padding. 0843 */ 0844 int mbedtls_cipher_set_padding_mode(mbedtls_cipher_context_t *ctx, 0845 mbedtls_cipher_padding_t mode); 0846 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */ 0847 0848 /** 0849 * \brief This function sets the initialization vector (IV) 0850 * or nonce. 0851 * 0852 * \note Some ciphers do not use IVs nor nonce. For these 0853 * ciphers, this function has no effect. 0854 * 0855 * \note For #MBEDTLS_CIPHER_CHACHA20, the nonce length must 0856 * be 12, and the initial counter value is 0. 0857 * 0858 * \note For #MBEDTLS_CIPHER_CHACHA20_POLY1305, the nonce length 0859 * must be 12. 0860 * 0861 * \param ctx The generic cipher context. This must be initialized and 0862 * bound to a cipher information structure. 0863 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. This 0864 * must be a readable buffer of at least \p iv_len Bytes. 0865 * \param iv_len The IV length for ciphers with variable-size IV. 0866 * This parameter is discarded by ciphers with fixed-size IV. 0867 * 0868 * \return \c 0 on success. 0869 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0870 * parameter-verification failure. 0871 */ 0872 int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, 0873 const unsigned char *iv, 0874 size_t iv_len); 0875 0876 /** 0877 * \brief This function resets the cipher state. 0878 * 0879 * \note With non-AEAD ciphers, the order of calls for each message 0880 * is as follows: 0881 * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce. 0882 * 2. mbedtls_cipher_reset() 0883 * 3. mbedtls_cipher_update() one or more times 0884 * 4. mbedtls_cipher_finish() 0885 * . 0886 * This sequence can be repeated to encrypt or decrypt multiple 0887 * messages with the same key. 0888 * 0889 * \note With AEAD ciphers, the order of calls for each message 0890 * is as follows: 0891 * 1. mbedtls_cipher_set_iv() if the mode uses an IV/nonce. 0892 * 2. mbedtls_cipher_reset() 0893 * 3. mbedtls_cipher_update_ad() 0894 * 4. mbedtls_cipher_update() one or more times 0895 * 5. mbedtls_cipher_finish() 0896 * 6. mbedtls_cipher_check_tag() (for decryption) or 0897 * mbedtls_cipher_write_tag() (for encryption). 0898 * . 0899 * This sequence can be repeated to encrypt or decrypt multiple 0900 * messages with the same key. 0901 * 0902 * \param ctx The generic cipher context. This must be bound to a key. 0903 * 0904 * \return \c 0 on success. 0905 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0906 * parameter-verification failure. 0907 */ 0908 int mbedtls_cipher_reset(mbedtls_cipher_context_t *ctx); 0909 0910 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C) 0911 /** 0912 * \brief This function adds additional data for AEAD ciphers. 0913 * Currently supported with GCM and ChaCha20+Poly1305. 0914 * 0915 * \param ctx The generic cipher context. This must be initialized. 0916 * \param ad The additional data to use. This must be a readable 0917 * buffer of at least \p ad_len Bytes. 0918 * \param ad_len The length of \p ad in Bytes. 0919 * 0920 * \return \c 0 on success. 0921 * \return A specific error code on failure. 0922 */ 0923 int mbedtls_cipher_update_ad(mbedtls_cipher_context_t *ctx, 0924 const unsigned char *ad, size_t ad_len); 0925 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */ 0926 0927 /** 0928 * \brief The generic cipher update function. It encrypts or 0929 * decrypts using the given cipher context. Writes as 0930 * many block-sized blocks of data as possible to output. 0931 * Any data that cannot be written immediately is either 0932 * added to the next block, or flushed when 0933 * mbedtls_cipher_finish() is called. 0934 * Exception: For MBEDTLS_MODE_ECB, expects a single block 0935 * in size. For example, 16 Bytes for AES. 0936 * 0937 * \param ctx The generic cipher context. This must be initialized and 0938 * bound to a key. 0939 * \param input The buffer holding the input data. This must be a 0940 * readable buffer of at least \p ilen Bytes. 0941 * \param ilen The length of the input data. 0942 * \param output The buffer for the output data. This must be able to 0943 * hold at least `ilen + block_size`. This must not be the 0944 * same buffer as \p input. 0945 * \param olen The length of the output data, to be updated with the 0946 * actual number of Bytes written. This must not be 0947 * \c NULL. 0948 * 0949 * \return \c 0 on success. 0950 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0951 * parameter-verification failure. 0952 * \return #MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an 0953 * unsupported mode for a cipher. 0954 * \return A cipher-specific error code on failure. 0955 */ 0956 int mbedtls_cipher_update(mbedtls_cipher_context_t *ctx, 0957 const unsigned char *input, 0958 size_t ilen, unsigned char *output, 0959 size_t *olen); 0960 0961 /** 0962 * \brief The generic cipher finalization function. If data still 0963 * needs to be flushed from an incomplete block, the data 0964 * contained in it is padded to the size of 0965 * the last block, and written to the \p output buffer. 0966 * 0967 * \param ctx The generic cipher context. This must be initialized and 0968 * bound to a key. 0969 * \param output The buffer to write data to. This needs to be a writable 0970 * buffer of at least block_size Bytes. 0971 * \param olen The length of the data written to the \p output buffer. 0972 * This may not be \c NULL. 0973 * 0974 * \return \c 0 on success. 0975 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 0976 * parameter-verification failure. 0977 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption 0978 * expecting a full block but not receiving one. 0979 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding 0980 * while decrypting. 0981 * \return A cipher-specific error code on failure. 0982 */ 0983 int mbedtls_cipher_finish(mbedtls_cipher_context_t *ctx, 0984 unsigned char *output, size_t *olen); 0985 0986 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C) 0987 /** 0988 * \brief This function writes a tag for AEAD ciphers. 0989 * Currently supported with GCM and ChaCha20+Poly1305. 0990 * This must be called after mbedtls_cipher_finish(). 0991 * 0992 * \param ctx The generic cipher context. This must be initialized, 0993 * bound to a key, and have just completed a cipher 0994 * operation through mbedtls_cipher_finish() the tag for 0995 * which should be written. 0996 * \param tag The buffer to write the tag to. This must be a writable 0997 * buffer of at least \p tag_len Bytes. 0998 * \param tag_len The length of the tag to write. 0999 * 1000 * \return \c 0 on success. 1001 * \return A specific error code on failure. 1002 */ 1003 int mbedtls_cipher_write_tag(mbedtls_cipher_context_t *ctx, 1004 unsigned char *tag, size_t tag_len); 1005 1006 /** 1007 * \brief This function checks the tag for AEAD ciphers. 1008 * Currently supported with GCM and ChaCha20+Poly1305. 1009 * This must be called after mbedtls_cipher_finish(). 1010 * 1011 * \param ctx The generic cipher context. This must be initialized. 1012 * \param tag The buffer holding the tag. This must be a readable 1013 * buffer of at least \p tag_len Bytes. 1014 * \param tag_len The length of the tag to check. 1015 * 1016 * \return \c 0 on success. 1017 * \return A specific error code on failure. 1018 */ 1019 int mbedtls_cipher_check_tag(mbedtls_cipher_context_t *ctx, 1020 const unsigned char *tag, size_t tag_len); 1021 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */ 1022 1023 /** 1024 * \brief The generic all-in-one encryption/decryption function, 1025 * for all ciphers except AEAD constructs. 1026 * 1027 * \param ctx The generic cipher context. This must be initialized. 1028 * \param iv The IV to use, or NONCE_COUNTER for CTR-mode ciphers. 1029 * This must be a readable buffer of at least \p iv_len 1030 * Bytes. 1031 * \param iv_len The IV length for ciphers with variable-size IV. 1032 * This parameter is discarded by ciphers with fixed-size 1033 * IV. 1034 * \param input The buffer holding the input data. This must be a 1035 * readable buffer of at least \p ilen Bytes. 1036 * \param ilen The length of the input data in Bytes. 1037 * \param output The buffer for the output data. This must be able to 1038 * hold at least `ilen + block_size`. This must not be the 1039 * same buffer as \p input. 1040 * \param olen The length of the output data, to be updated with the 1041 * actual number of Bytes written. This must not be 1042 * \c NULL. 1043 * 1044 * \note Some ciphers do not use IVs nor nonce. For these 1045 * ciphers, use \p iv = NULL and \p iv_len = 0. 1046 * 1047 * \return \c 0 on success. 1048 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 1049 * parameter-verification failure. 1050 * \return #MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED on decryption 1051 * expecting a full block but not receiving one. 1052 * \return #MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding 1053 * while decrypting. 1054 * \return A cipher-specific error code on failure. 1055 */ 1056 int mbedtls_cipher_crypt(mbedtls_cipher_context_t *ctx, 1057 const unsigned char *iv, size_t iv_len, 1058 const unsigned char *input, size_t ilen, 1059 unsigned char *output, size_t *olen); 1060 1061 #if defined(MBEDTLS_CIPHER_MODE_AEAD) || defined(MBEDTLS_NIST_KW_C) 1062 /** 1063 * \brief The authenticated encryption (AEAD/NIST_KW) function. 1064 * 1065 * \note For AEAD modes, the tag will be appended to the 1066 * ciphertext, as recommended by RFC 5116. 1067 * (NIST_KW doesn't have a separate tag.) 1068 * 1069 * \param ctx The generic cipher context. This must be initialized and 1070 * bound to a key, with an AEAD algorithm or NIST_KW. 1071 * \param iv The nonce to use. This must be a readable buffer of 1072 * at least \p iv_len Bytes and may be \c NULL if \p 1073 * iv_len is \c 0. 1074 * \param iv_len The length of the nonce. For AEAD ciphers, this must 1075 * satisfy the constraints imposed by the cipher used. 1076 * For NIST_KW, this must be \c 0. 1077 * \param ad The additional data to authenticate. This must be a 1078 * readable buffer of at least \p ad_len Bytes, and may 1079 * be \c NULL is \p ad_len is \c 0. 1080 * \param ad_len The length of \p ad. For NIST_KW, this must be \c 0. 1081 * \param input The buffer holding the input data. This must be a 1082 * readable buffer of at least \p ilen Bytes, and may be 1083 * \c NULL if \p ilen is \c 0. 1084 * \param ilen The length of the input data. 1085 * \param output The buffer for the output data. This must be a 1086 * writable buffer of at least \p output_len Bytes, and 1087 * must not be \c NULL. 1088 * \param output_len The length of the \p output buffer in Bytes. For AEAD 1089 * ciphers, this must be at least \p ilen + \p tag_len. 1090 * For NIST_KW, this must be at least \p ilen + 8 1091 * (rounded up to a multiple of 8 if KWP is used); 1092 * \p ilen + 15 is always a safe value. 1093 * \param olen This will be filled with the actual number of Bytes 1094 * written to the \p output buffer. This must point to a 1095 * writable object of type \c size_t. 1096 * \param tag_len The desired length of the authentication tag. For AEAD 1097 * ciphers, this must match the constraints imposed by 1098 * the cipher used, and in particular must not be \c 0. 1099 * For NIST_KW, this must be \c 0. 1100 * 1101 * \return \c 0 on success. 1102 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 1103 * parameter-verification failure. 1104 * \return A cipher-specific error code on failure. 1105 */ 1106 int mbedtls_cipher_auth_encrypt_ext(mbedtls_cipher_context_t *ctx, 1107 const unsigned char *iv, size_t iv_len, 1108 const unsigned char *ad, size_t ad_len, 1109 const unsigned char *input, size_t ilen, 1110 unsigned char *output, size_t output_len, 1111 size_t *olen, size_t tag_len); 1112 1113 /** 1114 * \brief The authenticated encryption (AEAD/NIST_KW) function. 1115 * 1116 * \note If the data is not authentic, then the output buffer 1117 * is zeroed out to prevent the unauthentic plaintext being 1118 * used, making this interface safer. 1119 * 1120 * \note For AEAD modes, the tag must be appended to the 1121 * ciphertext, as recommended by RFC 5116. 1122 * (NIST_KW doesn't have a separate tag.) 1123 * 1124 * \param ctx The generic cipher context. This must be initialized and 1125 * bound to a key, with an AEAD algorithm or NIST_KW. 1126 * \param iv The nonce to use. This must be a readable buffer of 1127 * at least \p iv_len Bytes and may be \c NULL if \p 1128 * iv_len is \c 0. 1129 * \param iv_len The length of the nonce. For AEAD ciphers, this must 1130 * satisfy the constraints imposed by the cipher used. 1131 * For NIST_KW, this must be \c 0. 1132 * \param ad The additional data to authenticate. This must be a 1133 * readable buffer of at least \p ad_len Bytes, and may 1134 * be \c NULL is \p ad_len is \c 0. 1135 * \param ad_len The length of \p ad. For NIST_KW, this must be \c 0. 1136 * \param input The buffer holding the input data. This must be a 1137 * readable buffer of at least \p ilen Bytes, and may be 1138 * \c NULL if \p ilen is \c 0. 1139 * \param ilen The length of the input data. For AEAD ciphers this 1140 * must be at least \p tag_len. For NIST_KW this must be 1141 * at least \c 8. 1142 * \param output The buffer for the output data. This must be a 1143 * writable buffer of at least \p output_len Bytes, and 1144 * may be \c NULL if \p output_len is \c 0. 1145 * \param output_len The length of the \p output buffer in Bytes. For AEAD 1146 * ciphers, this must be at least \p ilen - \p tag_len. 1147 * For NIST_KW, this must be at least \p ilen - 8. 1148 * \param olen This will be filled with the actual number of Bytes 1149 * written to the \p output buffer. This must point to a 1150 * writable object of type \c size_t. 1151 * \param tag_len The actual length of the authentication tag. For AEAD 1152 * ciphers, this must match the constraints imposed by 1153 * the cipher used, and in particular must not be \c 0. 1154 * For NIST_KW, this must be \c 0. 1155 * 1156 * \return \c 0 on success. 1157 * \return #MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on 1158 * parameter-verification failure. 1159 * \return #MBEDTLS_ERR_CIPHER_AUTH_FAILED if data is not authentic. 1160 * \return A cipher-specific error code on failure. 1161 */ 1162 int mbedtls_cipher_auth_decrypt_ext(mbedtls_cipher_context_t *ctx, 1163 const unsigned char *iv, size_t iv_len, 1164 const unsigned char *ad, size_t ad_len, 1165 const unsigned char *input, size_t ilen, 1166 unsigned char *output, size_t output_len, 1167 size_t *olen, size_t tag_len); 1168 #endif /* MBEDTLS_CIPHER_MODE_AEAD || MBEDTLS_NIST_KW_C */ 1169 #ifdef __cplusplus 1170 } 1171 #endif 1172 1173 #endif /* MBEDTLS_CIPHER_H */
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|