aes.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417
  1. /**
  2. * \file aes.h
  3. *
  4. * \brief The Advanced Encryption Standard (AES) specifies a FIPS-approved
  5. * cryptographic algorithm that can be used to protect electronic
  6. * data.
  7. *
  8. * The AES algorithm is a symmetric block cipher that can
  9. * encrypt and decrypt information. For more information, see
  10. * <em>FIPS Publication 197: Advanced Encryption Standard</em> and
  11. * <em>ISO/IEC 18033-2:2006: Information technology -- Security
  12. * techniques -- Encryption algorithms -- Part 2: Asymmetric
  13. * ciphers</em>.
  14. */
  15. /* Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved.
  16. * SPDX-License-Identifier: Apache-2.0
  17. *
  18. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  19. * not use this file except in compliance with the License.
  20. * You may obtain a copy of the License at
  21. *
  22. * http://www.apache.org/licenses/LICENSE-2.0
  23. *
  24. * Unless required by applicable law or agreed to in writing, software
  25. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  26. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  27. * See the License for the specific language governing permissions and
  28. * limitations under the License.
  29. *
  30. * This file is part of Mbed TLS (https://tls.mbed.org)
  31. */
  32. #ifndef MBEDTLS_AES_H
  33. #define MBEDTLS_AES_H
  34. #if !defined(MBEDTLS_CONFIG_FILE)
  35. #include "config.h"
  36. #else
  37. #include MBEDTLS_CONFIG_FILE
  38. #endif
  39. #include <stddef.h>
  40. #include <stdint.h>
  41. /* padlock.c and aesni.c rely on these values! */
  42. #define MBEDTLS_AES_ENCRYPT 1 /**< AES encryption. */
  43. #define MBEDTLS_AES_DECRYPT 0 /**< AES decryption. */
  44. /* Error codes in range 0x0020-0x0022 */
  45. #define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH -0x0020 /**< Invalid key length. */
  46. #define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH -0x0022 /**< Invalid data input length. */
  47. /* Error codes in range 0x0023-0x0025 */
  48. #define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE -0x0023 /**< Feature not available. For example, an unsupported AES key size. */
  49. #define MBEDTLS_ERR_AES_HW_ACCEL_FAILED -0x0025 /**< AES hardware accelerator failed. */
  50. #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
  51. !defined(inline) && !defined(__cplusplus)
  52. #define inline __inline
  53. #endif
  54. #if !defined(MBEDTLS_AES_ALT)
  55. // Regular implementation
  56. //
  57. #ifdef __cplusplus
  58. extern "C" {
  59. #endif
  60. /**
  61. * \brief The AES context-type definition.
  62. */
  63. typedef struct
  64. {
  65. int nr; /*!< The number of rounds. */
  66. uint32_t *rk; /*!< AES round keys. */
  67. uint32_t buf[68]; /*!< Unaligned data buffer. This buffer can
  68. hold 32 extra Bytes, which can be used for
  69. one of the following purposes:
  70. <ul><li>Alignment if VIA padlock is
  71. used.</li>
  72. <li>Simplifying key expansion in the 256-bit
  73. case by generating an extra round key.
  74. </li></ul> */
  75. }
  76. mbedtls_aes_context;
  77. /**
  78. * \brief This function initializes the specified AES context.
  79. *
  80. * It must be the first API called before using
  81. * the context.
  82. *
  83. * \param ctx The AES context to initialize.
  84. */
  85. void mbedtls_aes_init( mbedtls_aes_context *ctx );
  86. /**
  87. * \brief This function releases and clears the specified AES context.
  88. *
  89. * \param ctx The AES context to clear.
  90. */
  91. void mbedtls_aes_free( mbedtls_aes_context *ctx );
  92. /**
  93. * \brief This function sets the encryption key.
  94. *
  95. * \param ctx The AES context to which the key should be bound.
  96. * \param key The encryption key.
  97. * \param keybits The size of data passed in bits. Valid options are:
  98. * <ul><li>128 bits</li>
  99. * <li>192 bits</li>
  100. * <li>256 bits</li></ul>
  101. *
  102. * \return \c 0 on success or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH
  103. * on failure.
  104. */
  105. int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
  106. unsigned int keybits );
  107. /**
  108. * \brief This function sets the decryption key.
  109. *
  110. * \param ctx The AES context to which the key should be bound.
  111. * \param key The decryption key.
  112. * \param keybits The size of data passed. Valid options are:
  113. * <ul><li>128 bits</li>
  114. * <li>192 bits</li>
  115. * <li>256 bits</li></ul>
  116. *
  117. * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.
  118. */
  119. int mbedtls_aes_setkey_dec( mbedtls_aes_context *ctx, const unsigned char *key,
  120. unsigned int keybits );
  121. /**
  122. * \brief This function performs an AES single-block encryption or
  123. * decryption operation.
  124. *
  125. * It performs the operation defined in the \p mode parameter
  126. * (encrypt or decrypt), on the input data buffer defined in
  127. * the \p input parameter.
  128. *
  129. * mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or
  130. * mbedtls_aes_setkey_dec() must be called before the first
  131. * call to this API with the same context.
  132. *
  133. * \param ctx The AES context to use for encryption or decryption.
  134. * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
  135. * #MBEDTLS_AES_DECRYPT.
  136. * \param input The 16-Byte buffer holding the input data.
  137. * \param output The 16-Byte buffer holding the output data.
  138. * \return \c 0 on success.
  139. */
  140. int mbedtls_aes_crypt_ecb( mbedtls_aes_context *ctx,
  141. int mode,
  142. const unsigned char input[16],
  143. unsigned char output[16] );
  144. #if defined(MBEDTLS_CIPHER_MODE_CBC)
  145. /**
  146. * \brief This function performs an AES-CBC encryption or decryption operation
  147. * on full blocks.
  148. *
  149. * It performs the operation defined in the \p mode
  150. * parameter (encrypt/decrypt), on the input data buffer defined in
  151. * the \p input parameter.
  152. *
  153. * It can be called as many times as needed, until all the input
  154. * data is processed. mbedtls_aes_init(), and either
  155. * mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called
  156. * before the first call to this API with the same context.
  157. *
  158. * \note This function operates on aligned blocks, that is, the input size
  159. * must be a multiple of the AES block size of 16 Bytes.
  160. *
  161. * \note Upon exit, the content of the IV is updated so that you can
  162. * call the same function again on the next
  163. * block(s) of data and get the same result as if it was
  164. * encrypted in one call. This allows a "streaming" usage.
  165. * If you need to retain the contents of the IV, you should
  166. * either save it manually or use the cipher module instead.
  167. *
  168. *
  169. * \param ctx The AES context to use for encryption or decryption.
  170. * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
  171. * #MBEDTLS_AES_DECRYPT.
  172. * \param length The length of the input data in Bytes. This must be a
  173. * multiple of the block size (16 Bytes).
  174. * \param iv Initialization vector (updated after use).
  175. * \param input The buffer holding the input data.
  176. * \param output The buffer holding the output data.
  177. *
  178. * \return \c 0 on success, or #MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH
  179. * on failure.
  180. */
  181. int mbedtls_aes_crypt_cbc( mbedtls_aes_context *ctx,
  182. int mode,
  183. size_t length,
  184. unsigned char iv[16],
  185. const unsigned char *input,
  186. unsigned char *output );
  187. #endif /* MBEDTLS_CIPHER_MODE_CBC */
  188. #if defined(MBEDTLS_CIPHER_MODE_CFB)
  189. /**
  190. * \brief This function performs an AES-CFB128 encryption or decryption
  191. * operation.
  192. *
  193. * It performs the operation defined in the \p mode
  194. * parameter (encrypt or decrypt), on the input data buffer
  195. * defined in the \p input parameter.
  196. *
  197. * For CFB, you must set up the context with mbedtls_aes_setkey_enc(),
  198. * regardless of whether you are performing an encryption or decryption
  199. * operation, that is, regardless of the \p mode parameter. This is
  200. * because CFB mode uses the same key schedule for encryption and
  201. * decryption.
  202. *
  203. * \note Upon exit, the content of the IV is updated so that you can
  204. * call the same function again on the next
  205. * block(s) of data and get the same result as if it was
  206. * encrypted in one call. This allows a "streaming" usage.
  207. * If you need to retain the contents of the
  208. * IV, you must either save it manually or use the cipher
  209. * module instead.
  210. *
  211. *
  212. * \param ctx The AES context to use for encryption or decryption.
  213. * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
  214. * #MBEDTLS_AES_DECRYPT.
  215. * \param length The length of the input data.
  216. * \param iv_off The offset in IV (updated after use).
  217. * \param iv The initialization vector (updated after use).
  218. * \param input The buffer holding the input data.
  219. * \param output The buffer holding the output data.
  220. *
  221. * \return \c 0 on success.
  222. */
  223. int mbedtls_aes_crypt_cfb128( mbedtls_aes_context *ctx,
  224. int mode,
  225. size_t length,
  226. size_t *iv_off,
  227. unsigned char iv[16],
  228. const unsigned char *input,
  229. unsigned char *output );
  230. /**
  231. * \brief This function performs an AES-CFB8 encryption or decryption
  232. * operation.
  233. *
  234. * It performs the operation defined in the \p mode
  235. * parameter (encrypt/decrypt), on the input data buffer defined
  236. * in the \p input parameter.
  237. *
  238. * Due to the nature of CFB, you must use the same key schedule for
  239. * both encryption and decryption operations. Therefore, you must
  240. * use the context initialized with mbedtls_aes_setkey_enc() for
  241. * both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
  242. *
  243. * \note Upon exit, the content of the IV is updated so that you can
  244. * call the same function again on the next
  245. * block(s) of data and get the same result as if it was
  246. * encrypted in one call. This allows a "streaming" usage.
  247. * If you need to retain the contents of the
  248. * IV, you should either save it manually or use the cipher
  249. * module instead.
  250. *
  251. *
  252. * \param ctx The AES context to use for encryption or decryption.
  253. * \param mode The AES operation: #MBEDTLS_AES_ENCRYPT or
  254. * #MBEDTLS_AES_DECRYPT
  255. * \param length The length of the input data.
  256. * \param iv The initialization vector (updated after use).
  257. * \param input The buffer holding the input data.
  258. * \param output The buffer holding the output data.
  259. *
  260. * \return \c 0 on success.
  261. */
  262. int mbedtls_aes_crypt_cfb8( mbedtls_aes_context *ctx,
  263. int mode,
  264. size_t length,
  265. unsigned char iv[16],
  266. const unsigned char *input,
  267. unsigned char *output );
  268. #endif /*MBEDTLS_CIPHER_MODE_CFB */
  269. #if defined(MBEDTLS_CIPHER_MODE_CTR)
  270. /**
  271. * \brief This function performs an AES-CTR encryption or decryption
  272. * operation.
  273. *
  274. * This function performs the operation defined in the \p mode
  275. * parameter (encrypt/decrypt), on the input data buffer
  276. * defined in the \p input parameter.
  277. *
  278. * Due to the nature of CTR, you must use the same key schedule
  279. * for both encryption and decryption operations. Therefore, you
  280. * must use the context initialized with mbedtls_aes_setkey_enc()
  281. * for both #MBEDTLS_AES_ENCRYPT and #MBEDTLS_AES_DECRYPT.
  282. *
  283. * \warning You must keep the maximum use of your counter in mind.
  284. *
  285. * \param ctx The AES context to use for encryption or decryption.
  286. * \param length The length of the input data.
  287. * \param nc_off The offset in the current \p stream_block, for
  288. * resuming within the current cipher stream. The
  289. * offset pointer should be 0 at the start of a stream.
  290. * \param nonce_counter The 128-bit nonce and counter.
  291. * \param stream_block The saved stream block for resuming. This is
  292. * overwritten by the function.
  293. * \param input The buffer holding the input data.
  294. * \param output The buffer holding the output data.
  295. *
  296. * \return \c 0 on success.
  297. */
  298. int mbedtls_aes_crypt_ctr( mbedtls_aes_context *ctx,
  299. size_t length,
  300. size_t *nc_off,
  301. unsigned char nonce_counter[16],
  302. unsigned char stream_block[16],
  303. const unsigned char *input,
  304. unsigned char *output );
  305. #endif /* MBEDTLS_CIPHER_MODE_CTR */
  306. /**
  307. * \brief Internal AES block encryption function. This is only
  308. * exposed to allow overriding it using
  309. * \c MBEDTLS_AES_ENCRYPT_ALT.
  310. *
  311. * \param ctx The AES context to use for encryption.
  312. * \param input The plaintext block.
  313. * \param output The output (ciphertext) block.
  314. *
  315. * \return \c 0 on success.
  316. */
  317. int mbedtls_internal_aes_encrypt( mbedtls_aes_context *ctx,
  318. const unsigned char input[16],
  319. unsigned char output[16] );
  320. /**
  321. * \brief Internal AES block decryption function. This is only
  322. * exposed to allow overriding it using see
  323. * \c MBEDTLS_AES_DECRYPT_ALT.
  324. *
  325. * \param ctx The AES context to use for decryption.
  326. * \param input The ciphertext block.
  327. * \param output The output (plaintext) block.
  328. *
  329. * \return \c 0 on success.
  330. */
  331. int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
  332. const unsigned char input[16],
  333. unsigned char output[16] );
  334. #if !defined(MBEDTLS_DEPRECATED_REMOVED)
  335. #if defined(MBEDTLS_DEPRECATED_WARNING)
  336. #define MBEDTLS_DEPRECATED __attribute__((deprecated))
  337. #else
  338. #define MBEDTLS_DEPRECATED
  339. #endif
  340. /**
  341. * \brief Deprecated internal AES block encryption function
  342. * without return value.
  343. *
  344. * \deprecated Superseded by mbedtls_aes_encrypt_ext() in 2.5.0.
  345. *
  346. * \param ctx The AES context to use for encryption.
  347. * \param input Plaintext block.
  348. * \param output Output (ciphertext) block.
  349. */
  350. MBEDTLS_DEPRECATED void mbedtls_aes_encrypt( mbedtls_aes_context *ctx,
  351. const unsigned char input[16],
  352. unsigned char output[16] );
  353. /**
  354. * \brief Deprecated internal AES block decryption function
  355. * without return value.
  356. *
  357. * \deprecated Superseded by mbedtls_aes_decrypt_ext() in 2.5.0.
  358. *
  359. * \param ctx The AES context to use for decryption.
  360. * \param input Ciphertext block.
  361. * \param output Output (plaintext) block.
  362. */
  363. MBEDTLS_DEPRECATED void mbedtls_aes_decrypt( mbedtls_aes_context *ctx,
  364. const unsigned char input[16],
  365. unsigned char output[16] );
  366. #undef MBEDTLS_DEPRECATED
  367. #endif /* !MBEDTLS_DEPRECATED_REMOVED */
  368. #ifdef __cplusplus
  369. }
  370. #endif
  371. #else /* MBEDTLS_AES_ALT */
  372. #include "aes_alt.h"
  373. #endif /* MBEDTLS_AES_ALT */
  374. #ifdef __cplusplus
  375. extern "C" {
  376. #endif
  377. /**
  378. * \brief Checkup routine.
  379. *
  380. * \return \c 0 on success, or \c 1 on failure.
  381. */
  382. int mbedtls_aes_self_test( int verbose );
  383. #ifdef __cplusplus
  384. }
  385. #endif
  386. #endif /* aes.h */