cipher.h 28 KB

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