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