aria.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370
  1. /**
  2. * \file aria.h
  3. *
  4. * \brief ARIA block cipher
  5. *
  6. * The ARIA algorithm is a symmetric block cipher that can encrypt and
  7. * decrypt information. It is defined by the Korean Agency for
  8. * Technology and Standards (KATS) in <em>KS X 1213:2004</em> (in
  9. * Korean, but see http://210.104.33.10/ARIA/index-e.html in English)
  10. * and also described by the IETF in <em>RFC 5794</em>.
  11. */
  12. /* Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
  13. * SPDX-License-Identifier: Apache-2.0
  14. *
  15. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  16. * not use this file except in compliance with the License.
  17. * You may obtain a copy of the License at
  18. *
  19. * http://www.apache.org/licenses/LICENSE-2.0
  20. *
  21. * Unless required by applicable law or agreed to in writing, software
  22. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  23. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  24. * See the License for the specific language governing permissions and
  25. * limitations under the License.
  26. *
  27. * This file is part of mbed TLS (https://tls.mbed.org)
  28. */
  29. #ifndef MBEDTLS_ARIA_H
  30. #define MBEDTLS_ARIA_H
  31. #if !defined(MBEDTLS_CONFIG_FILE)
  32. #include "config.h"
  33. #else
  34. #include MBEDTLS_CONFIG_FILE
  35. #endif
  36. #include <stddef.h>
  37. #include <stdint.h>
  38. #include "platform_util.h"
  39. #define MBEDTLS_ARIA_ENCRYPT 1 /**< ARIA encryption. */
  40. #define MBEDTLS_ARIA_DECRYPT 0 /**< ARIA decryption. */
  41. #define MBEDTLS_ARIA_BLOCKSIZE 16 /**< ARIA block size in bytes. */
  42. #define MBEDTLS_ARIA_MAX_ROUNDS 16 /**< Maxiumum number of rounds in ARIA. */
  43. #define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
  44. #if !defined(MBEDTLS_DEPRECATED_REMOVED)
  45. #define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x005C )
  46. #endif /* !MBEDTLS_DEPRECATED_REMOVED */
  47. #define MBEDTLS_ERR_ARIA_BAD_INPUT_DATA -0x005C /**< Bad input data. */
  48. #define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E /**< Invalid data input length. */
  49. /* MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE is deprecated and should not be used.
  50. */
  51. #define MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE -0x005A /**< Feature not available. For example, an unsupported ARIA key size. */
  52. /* MBEDTLS_ERR_ARIA_HW_ACCEL_FAILED is deprecated and should not be used. */
  53. #define MBEDTLS_ERR_ARIA_HW_ACCEL_FAILED -0x0058 /**< ARIA hardware accelerator failed. */
  54. #if !defined(MBEDTLS_ARIA_ALT)
  55. // Regular implementation
  56. //
  57. #ifdef __cplusplus
  58. extern "C" {
  59. #endif
  60. /**
  61. * \brief The ARIA context-type definition.
  62. */
  63. typedef struct mbedtls_aria_context
  64. {
  65. unsigned char nr; /*!< The number of rounds (12, 14 or 16) */
  66. /*! The ARIA round keys. */
  67. uint32_t rk[MBEDTLS_ARIA_MAX_ROUNDS + 1][MBEDTLS_ARIA_BLOCKSIZE / 4];
  68. }
  69. mbedtls_aria_context;
  70. #else /* MBEDTLS_ARIA_ALT */
  71. #include "aria_alt.h"
  72. #endif /* MBEDTLS_ARIA_ALT */
  73. /**
  74. * \brief This function initializes the specified ARIA context.
  75. *
  76. * It must be the first API called before using
  77. * the context.
  78. *
  79. * \param ctx The ARIA context to initialize. This must not be \c NULL.
  80. */
  81. void mbedtls_aria_init( mbedtls_aria_context *ctx );
  82. /**
  83. * \brief This function releases and clears the specified ARIA context.
  84. *
  85. * \param ctx The ARIA context to clear. This may be \c NULL, in which
  86. * case this function returns immediately. If it is not \c NULL,
  87. * it must point to an initialized ARIA context.
  88. */
  89. void mbedtls_aria_free( mbedtls_aria_context *ctx );
  90. /**
  91. * \brief This function sets the encryption key.
  92. *
  93. * \param ctx The ARIA context to which the key should be bound.
  94. * This must be initialized.
  95. * \param key The encryption key. This must be a readable buffer
  96. * of size \p keybits Bits.
  97. * \param keybits The size of \p key 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.
  103. * \return A negative error code on failure.
  104. */
  105. int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx,
  106. const unsigned char *key,
  107. unsigned int keybits );
  108. /**
  109. * \brief This function sets the decryption key.
  110. *
  111. * \param ctx The ARIA context to which the key should be bound.
  112. * This must be initialized.
  113. * \param key The decryption key. This must be a readable buffer
  114. * of size \p keybits Bits.
  115. * \param keybits The size of data passed. Valid options are:
  116. * <ul><li>128 bits</li>
  117. * <li>192 bits</li>
  118. * <li>256 bits</li></ul>
  119. *
  120. * \return \c 0 on success.
  121. * \return A negative error code on failure.
  122. */
  123. int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx,
  124. const unsigned char *key,
  125. unsigned int keybits );
  126. /**
  127. * \brief This function performs an ARIA single-block encryption or
  128. * decryption operation.
  129. *
  130. * It performs encryption or decryption (depending on whether
  131. * the key was set for encryption on decryption) on the input
  132. * data buffer defined in the \p input parameter.
  133. *
  134. * mbedtls_aria_init(), and either mbedtls_aria_setkey_enc() or
  135. * mbedtls_aria_setkey_dec() must be called before the first
  136. * call to this API with the same context.
  137. *
  138. * \param ctx The ARIA context to use for encryption or decryption.
  139. * This must be initialized and bound to a key.
  140. * \param input The 16-Byte buffer holding the input data.
  141. * \param output The 16-Byte buffer holding the output data.
  142. * \return \c 0 on success.
  143. * \return A negative error code on failure.
  144. */
  145. int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx,
  146. const unsigned char input[MBEDTLS_ARIA_BLOCKSIZE],
  147. unsigned char output[MBEDTLS_ARIA_BLOCKSIZE] );
  148. #if defined(MBEDTLS_CIPHER_MODE_CBC)
  149. /**
  150. * \brief This function performs an ARIA-CBC encryption or decryption operation
  151. * on full blocks.
  152. *
  153. * It performs the operation defined in the \p mode
  154. * parameter (encrypt/decrypt), on the input data buffer defined in
  155. * the \p input parameter.
  156. *
  157. * It can be called as many times as needed, until all the input
  158. * data is processed. mbedtls_aria_init(), and either
  159. * mbedtls_aria_setkey_enc() or mbedtls_aria_setkey_dec() must be called
  160. * before the first call to this API with the same context.
  161. *
  162. * \note This function operates on aligned blocks, that is, the input size
  163. * must be a multiple of the ARIA block size of 16 Bytes.
  164. *
  165. * \note Upon exit, the content of the IV is updated so that you can
  166. * call the same function again on the next
  167. * block(s) of data and get the same result as if it was
  168. * encrypted in one call. This allows a "streaming" usage.
  169. * If you need to retain the contents of the IV, you should
  170. * either save it manually or use the cipher module instead.
  171. *
  172. *
  173. * \param ctx The ARIA context to use for encryption or decryption.
  174. * This must be initialized and bound to a key.
  175. * \param mode The mode of operation. This must be either
  176. * #MBEDTLS_ARIA_ENCRYPT for encryption, or
  177. * #MBEDTLS_ARIA_DECRYPT for decryption.
  178. * \param length The length of the input data in Bytes. This must be a
  179. * multiple of the block size (16 Bytes).
  180. * \param iv Initialization vector (updated after use).
  181. * This must be a readable buffer of size 16 Bytes.
  182. * \param input The buffer holding the input data. This must
  183. * be a readable buffer of length \p length Bytes.
  184. * \param output The buffer holding the output data. This must
  185. * be a writable buffer of length \p length Bytes.
  186. *
  187. * \return \c 0 on success.
  188. * \return A negative error code on failure.
  189. */
  190. int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx,
  191. int mode,
  192. size_t length,
  193. unsigned char iv[MBEDTLS_ARIA_BLOCKSIZE],
  194. const unsigned char *input,
  195. unsigned char *output );
  196. #endif /* MBEDTLS_CIPHER_MODE_CBC */
  197. #if defined(MBEDTLS_CIPHER_MODE_CFB)
  198. /**
  199. * \brief This function performs an ARIA-CFB128 encryption or decryption
  200. * operation.
  201. *
  202. * It performs the operation defined in the \p mode
  203. * parameter (encrypt or decrypt), on the input data buffer
  204. * defined in the \p input parameter.
  205. *
  206. * For CFB, you must set up the context with mbedtls_aria_setkey_enc(),
  207. * regardless of whether you are performing an encryption or decryption
  208. * operation, that is, regardless of the \p mode parameter. This is
  209. * because CFB mode uses the same key schedule for encryption and
  210. * decryption.
  211. *
  212. * \note Upon exit, the content of the IV is updated so that you can
  213. * call the same function again on the next
  214. * block(s) of data and get the same result as if it was
  215. * encrypted in one call. This allows a "streaming" usage.
  216. * If you need to retain the contents of the
  217. * IV, you must either save it manually or use the cipher
  218. * module instead.
  219. *
  220. *
  221. * \param ctx The ARIA context to use for encryption or decryption.
  222. * This must be initialized and bound to a key.
  223. * \param mode The mode of operation. This must be either
  224. * #MBEDTLS_ARIA_ENCRYPT for encryption, or
  225. * #MBEDTLS_ARIA_DECRYPT for decryption.
  226. * \param length The length of the input data \p input in Bytes.
  227. * \param iv_off The offset in IV (updated after use).
  228. * This must not be larger than 15.
  229. * \param iv The initialization vector (updated after use).
  230. * This must be a readable buffer of size 16 Bytes.
  231. * \param input The buffer holding the input data. This must
  232. * be a readable buffer of length \p length Bytes.
  233. * \param output The buffer holding the output data. This must
  234. * be a writable buffer of length \p length Bytes.
  235. *
  236. * \return \c 0 on success.
  237. * \return A negative error code on failure.
  238. */
  239. int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
  240. int mode,
  241. size_t length,
  242. size_t *iv_off,
  243. unsigned char iv[MBEDTLS_ARIA_BLOCKSIZE],
  244. const unsigned char *input,
  245. unsigned char *output );
  246. #endif /* MBEDTLS_CIPHER_MODE_CFB */
  247. #if defined(MBEDTLS_CIPHER_MODE_CTR)
  248. /**
  249. * \brief This function performs an ARIA-CTR encryption or decryption
  250. * operation.
  251. *
  252. * This function performs the operation defined in the \p mode
  253. * parameter (encrypt/decrypt), on the input data buffer
  254. * defined in the \p input parameter.
  255. *
  256. * Due to the nature of CTR, you must use the same key schedule
  257. * for both encryption and decryption operations. Therefore, you
  258. * must use the context initialized with mbedtls_aria_setkey_enc()
  259. * for both #MBEDTLS_ARIA_ENCRYPT and #MBEDTLS_ARIA_DECRYPT.
  260. *
  261. * \warning You must never reuse a nonce value with the same key. Doing so
  262. * would void the encryption for the two messages encrypted with
  263. * the same nonce and key.
  264. *
  265. * There are two common strategies for managing nonces with CTR:
  266. *
  267. * 1. You can handle everything as a single message processed over
  268. * successive calls to this function. In that case, you want to
  269. * set \p nonce_counter and \p nc_off to 0 for the first call, and
  270. * then preserve the values of \p nonce_counter, \p nc_off and \p
  271. * stream_block across calls to this function as they will be
  272. * updated by this function.
  273. *
  274. * With this strategy, you must not encrypt more than 2**128
  275. * blocks of data with the same key.
  276. *
  277. * 2. You can encrypt separate messages by dividing the \p
  278. * nonce_counter buffer in two areas: the first one used for a
  279. * per-message nonce, handled by yourself, and the second one
  280. * updated by this function internally.
  281. *
  282. * For example, you might reserve the first 12 bytes for the
  283. * per-message nonce, and the last 4 bytes for internal use. In that
  284. * case, before calling this function on a new message you need to
  285. * set the first 12 bytes of \p nonce_counter to your chosen nonce
  286. * value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
  287. * stream_block to be ignored). That way, you can encrypt at most
  288. * 2**96 messages of up to 2**32 blocks each with the same key.
  289. *
  290. * The per-message nonce (or information sufficient to reconstruct
  291. * it) needs to be communicated with the ciphertext and must be unique.
  292. * The recommended way to ensure uniqueness is to use a message
  293. * counter. An alternative is to generate random nonces, but this
  294. * limits the number of messages that can be securely encrypted:
  295. * for example, with 96-bit random nonces, you should not encrypt
  296. * more than 2**32 messages with the same key.
  297. *
  298. * Note that for both stategies, sizes are measured in blocks and
  299. * that an ARIA block is 16 bytes.
  300. *
  301. * \warning Upon return, \p stream_block contains sensitive data. Its
  302. * content must not be written to insecure storage and should be
  303. * securely discarded as soon as it's no longer needed.
  304. *
  305. * \param ctx The ARIA context to use for encryption or decryption.
  306. * This must be initialized and bound to a key.
  307. * \param length The length of the input data \p input in Bytes.
  308. * \param nc_off The offset in Bytes in the current \p stream_block,
  309. * for resuming within the current cipher stream. The
  310. * offset pointer should be \c 0 at the start of a
  311. * stream. This must not be larger than \c 15 Bytes.
  312. * \param nonce_counter The 128-bit nonce and counter. This must point to
  313. * a read/write buffer of length \c 16 bytes.
  314. * \param stream_block The saved stream block for resuming. This must
  315. * point to a read/write buffer of length \c 16 bytes.
  316. * This is overwritten by the function.
  317. * \param input The buffer holding the input data. This must
  318. * be a readable buffer of length \p length Bytes.
  319. * \param output The buffer holding the output data. This must
  320. * be a writable buffer of length \p length Bytes.
  321. *
  322. * \return \c 0 on success.
  323. * \return A negative error code on failure.
  324. */
  325. int mbedtls_aria_crypt_ctr( mbedtls_aria_context *ctx,
  326. size_t length,
  327. size_t *nc_off,
  328. unsigned char nonce_counter[MBEDTLS_ARIA_BLOCKSIZE],
  329. unsigned char stream_block[MBEDTLS_ARIA_BLOCKSIZE],
  330. const unsigned char *input,
  331. unsigned char *output );
  332. #endif /* MBEDTLS_CIPHER_MODE_CTR */
  333. #if defined(MBEDTLS_SELF_TEST)
  334. /**
  335. * \brief Checkup routine.
  336. *
  337. * \return \c 0 on success, or \c 1 on failure.
  338. */
  339. int mbedtls_aria_self_test( int verbose );
  340. #endif /* MBEDTLS_SELF_TEST */
  341. #ifdef __cplusplus
  342. }
  343. #endif
  344. #endif /* aria.h */