cipher.h 26 KB

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