cipher.h 38 KB

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