camellia.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326
  1. /**
  2. * \file camellia.h
  3. *
  4. * \brief Camellia block cipher
  5. */
  6. /*
  7. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. *
  22. * This file is part of mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_CAMELLIA_H
  25. #define MBEDTLS_CAMELLIA_H
  26. #if !defined(MBEDTLS_CONFIG_FILE)
  27. #include "config.h"
  28. #else
  29. #include MBEDTLS_CONFIG_FILE
  30. #endif
  31. #include <stddef.h>
  32. #include <stdint.h>
  33. #include "platform_util.h"
  34. #define MBEDTLS_CAMELLIA_ENCRYPT 1
  35. #define MBEDTLS_CAMELLIA_DECRYPT 0
  36. #if !defined(MBEDTLS_DEPRECATED_REMOVED)
  37. #define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x0024 )
  38. #endif /* !MBEDTLS_DEPRECATED_REMOVED */
  39. #define MBEDTLS_ERR_CAMELLIA_BAD_INPUT_DATA -0x0024 /**< Bad input data. */
  40. #define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH -0x0026 /**< Invalid data input length. */
  41. /* MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED is deprecated and should not be used.
  42. */
  43. #define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED -0x0027 /**< Camellia hardware accelerator failed. */
  44. #ifdef __cplusplus
  45. extern "C" {
  46. #endif
  47. #if !defined(MBEDTLS_CAMELLIA_ALT)
  48. // Regular implementation
  49. //
  50. /**
  51. * \brief CAMELLIA context structure
  52. */
  53. typedef struct mbedtls_camellia_context
  54. {
  55. int nr; /*!< number of rounds */
  56. uint32_t rk[68]; /*!< CAMELLIA round keys */
  57. }
  58. mbedtls_camellia_context;
  59. #else /* MBEDTLS_CAMELLIA_ALT */
  60. #include "camellia_alt.h"
  61. #endif /* MBEDTLS_CAMELLIA_ALT */
  62. /**
  63. * \brief Initialize a CAMELLIA context.
  64. *
  65. * \param ctx The CAMELLIA context to be initialized.
  66. * This must not be \c NULL.
  67. */
  68. void mbedtls_camellia_init( mbedtls_camellia_context *ctx );
  69. /**
  70. * \brief Clear a CAMELLIA context.
  71. *
  72. * \param ctx The CAMELLIA context to be cleared. This may be \c NULL,
  73. * in which case this function returns immediately. If it is not
  74. * \c NULL, it must be initialized.
  75. */
  76. void mbedtls_camellia_free( mbedtls_camellia_context *ctx );
  77. /**
  78. * \brief Perform a CAMELLIA key schedule operation for encryption.
  79. *
  80. * \param ctx The CAMELLIA context to use. This must be initialized.
  81. * \param key The encryption key to use. This must be a readable buffer
  82. * of size \p keybits Bits.
  83. * \param keybits The length of \p key in Bits. This must be either \c 128,
  84. * \c 192 or \c 256.
  85. *
  86. * \return \c 0 if successful.
  87. * \return A negative error code on failure.
  88. */
  89. int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx,
  90. const unsigned char *key,
  91. unsigned int keybits );
  92. /**
  93. * \brief Perform a CAMELLIA key schedule operation for decryption.
  94. *
  95. * \param ctx The CAMELLIA context to use. This must be initialized.
  96. * \param key The decryption key. This must be a readable buffer
  97. * of size \p keybits Bits.
  98. * \param keybits The length of \p key in Bits. This must be either \c 128,
  99. * \c 192 or \c 256.
  100. *
  101. * \return \c 0 if successful.
  102. * \return A negative error code on failure.
  103. */
  104. int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx,
  105. const unsigned char *key,
  106. unsigned int keybits );
  107. /**
  108. * \brief Perform a CAMELLIA-ECB block encryption/decryption operation.
  109. *
  110. * \param ctx The CAMELLIA context to use. This must be initialized
  111. * and bound to a key.
  112. * \param mode The mode of operation. This must be either
  113. * #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  114. * \param input The input block. This must be a readable buffer
  115. * of size \c 16 Bytes.
  116. * \param output The output block. This must be a writable buffer
  117. * of size \c 16 Bytes.
  118. *
  119. * \return \c 0 if successful.
  120. * \return A negative error code on failure.
  121. */
  122. int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
  123. int mode,
  124. const unsigned char input[16],
  125. unsigned char output[16] );
  126. #if defined(MBEDTLS_CIPHER_MODE_CBC)
  127. /**
  128. * \brief Perform a CAMELLIA-CBC buffer encryption/decryption operation.
  129. *
  130. * \note Upon exit, the content of the IV is updated so that you can
  131. * call the function same function again on the following
  132. * block(s) of data and get the same result as if it was
  133. * encrypted in one call. This allows a "streaming" usage.
  134. * If on the other hand you need to retain the contents of the
  135. * IV, you should either save it manually or use the cipher
  136. * module instead.
  137. *
  138. * \param ctx The CAMELLIA context to use. This must be initialized
  139. * and bound to a key.
  140. * \param mode The mode of operation. This must be either
  141. * #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  142. * \param length The length in Bytes of the input data \p input.
  143. * This must be a multiple of \c 16 Bytes.
  144. * \param iv The initialization vector. This must be a read/write buffer
  145. * of length \c 16 Bytes. It is updated to allow streaming
  146. * use as explained above.
  147. * \param input The buffer holding the input data. This must point to a
  148. * readable buffer of length \p length Bytes.
  149. * \param output The buffer holding the output data. This must point to a
  150. * writable buffer of length \p length Bytes.
  151. *
  152. * \return \c 0 if successful.
  153. * \return A negative error code on failure.
  154. */
  155. int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
  156. int mode,
  157. size_t length,
  158. unsigned char iv[16],
  159. const unsigned char *input,
  160. unsigned char *output );
  161. #endif /* MBEDTLS_CIPHER_MODE_CBC */
  162. #if defined(MBEDTLS_CIPHER_MODE_CFB)
  163. /**
  164. * \brief Perform a CAMELLIA-CFB128 buffer encryption/decryption
  165. * operation.
  166. *
  167. * \note Due to the nature of CFB mode, you should use the same
  168. * key for both encryption and decryption. In particular, calls
  169. * to this function should be preceded by a key-schedule via
  170. * mbedtls_camellia_setkey_enc() regardless of whether \p mode
  171. * is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  172. *
  173. * \note Upon exit, the content of the IV is updated so that you can
  174. * call the function same function again on the following
  175. * block(s) of data and get the same result as if it was
  176. * encrypted in one call. This allows a "streaming" usage.
  177. * If on the other hand you need to retain the contents of the
  178. * IV, you should either save it manually or use the cipher
  179. * module instead.
  180. *
  181. * \param ctx The CAMELLIA context to use. This must be initialized
  182. * and bound to a key.
  183. * \param mode The mode of operation. This must be either
  184. * #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  185. * \param length The length of the input data \p input. Any value is allowed.
  186. * \param iv_off The current offset in the IV. This must be smaller
  187. * than \c 16 Bytes. It is updated after this call to allow
  188. * the aforementioned streaming usage.
  189. * \param iv The initialization vector. This must be a read/write buffer
  190. * of length \c 16 Bytes. It is updated after this call to
  191. * allow the aforementioned streaming usage.
  192. * \param input The buffer holding the input data. This must be a readable
  193. * buffer of size \p length Bytes.
  194. * \param output The buffer to hold the output data. This must be a writable
  195. * buffer of length \p length Bytes.
  196. *
  197. * \return \c 0 if successful.
  198. * \return A negative error code on failure.
  199. */
  200. int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
  201. int mode,
  202. size_t length,
  203. size_t *iv_off,
  204. unsigned char iv[16],
  205. const unsigned char *input,
  206. unsigned char *output );
  207. #endif /* MBEDTLS_CIPHER_MODE_CFB */
  208. #if defined(MBEDTLS_CIPHER_MODE_CTR)
  209. /**
  210. * \brief Perform a CAMELLIA-CTR buffer encryption/decryption operation.
  211. *
  212. * *note Due to the nature of CTR mode, you should use the same
  213. * key for both encryption and decryption. In particular, calls
  214. * to this function should be preceded by a key-schedule via
  215. * mbedtls_camellia_setkey_enc() regardless of whether \p mode
  216. * is #MBEDTLS_CAMELLIA_ENCRYPT or #MBEDTLS_CAMELLIA_DECRYPT.
  217. *
  218. * \warning You must never reuse a nonce value with the same key. Doing so
  219. * would void the encryption for the two messages encrypted with
  220. * the same nonce and key.
  221. *
  222. * There are two common strategies for managing nonces with CTR:
  223. *
  224. * 1. You can handle everything as a single message processed over
  225. * successive calls to this function. In that case, you want to
  226. * set \p nonce_counter and \p nc_off to 0 for the first call, and
  227. * then preserve the values of \p nonce_counter, \p nc_off and \p
  228. * stream_block across calls to this function as they will be
  229. * updated by this function.
  230. *
  231. * With this strategy, you must not encrypt more than 2**128
  232. * blocks of data with the same key.
  233. *
  234. * 2. You can encrypt separate messages by dividing the \p
  235. * nonce_counter buffer in two areas: the first one used for a
  236. * per-message nonce, handled by yourself, and the second one
  237. * updated by this function internally.
  238. *
  239. * For example, you might reserve the first \c 12 Bytes for the
  240. * per-message nonce, and the last \c 4 Bytes for internal use.
  241. * In that case, before calling this function on a new message you
  242. * need to set the first \c 12 Bytes of \p nonce_counter to your
  243. * chosen nonce value, the last four to \c 0, and \p nc_off to \c 0
  244. * (which will cause \p stream_block to be ignored). That way, you
  245. * can encrypt at most \c 2**96 messages of up to \c 2**32 blocks
  246. * each with the same key.
  247. *
  248. * The per-message nonce (or information sufficient to reconstruct
  249. * it) needs to be communicated with the ciphertext and must be
  250. * unique. The recommended way to ensure uniqueness is to use a
  251. * message counter. An alternative is to generate random nonces,
  252. * but this limits the number of messages that can be securely
  253. * encrypted: for example, with 96-bit random nonces, you should
  254. * not encrypt more than 2**32 messages with the same key.
  255. *
  256. * Note that for both stategies, sizes are measured in blocks and
  257. * that a CAMELLIA block is \c 16 Bytes.
  258. *
  259. * \warning Upon return, \p stream_block contains sensitive data. Its
  260. * content must not be written to insecure storage and should be
  261. * securely discarded as soon as it's no longer needed.
  262. *
  263. * \param ctx The CAMELLIA context to use. This must be initialized
  264. * and bound to a key.
  265. * \param length The length of the input data \p input in Bytes.
  266. * Any value is allowed.
  267. * \param nc_off The offset in the current \p stream_block (for resuming
  268. * within current cipher stream). The offset pointer to
  269. * should be \c 0 at the start of a stream. It is updated
  270. * at the end of this call.
  271. * \param nonce_counter The 128-bit nonce and counter. This must be a read/write
  272. * buffer of length \c 16 Bytes.
  273. * \param stream_block The saved stream-block for resuming. This must be a
  274. * read/write buffer of length \c 16 Bytes.
  275. * \param input The input data stream. This must be a readable buffer of
  276. * size \p length Bytes.
  277. * \param output The output data stream. This must be a writable buffer
  278. * of size \p length Bytes.
  279. *
  280. * \return \c 0 if successful.
  281. * \return A negative error code on failure.
  282. */
  283. int mbedtls_camellia_crypt_ctr( mbedtls_camellia_context *ctx,
  284. size_t length,
  285. size_t *nc_off,
  286. unsigned char nonce_counter[16],
  287. unsigned char stream_block[16],
  288. const unsigned char *input,
  289. unsigned char *output );
  290. #endif /* MBEDTLS_CIPHER_MODE_CTR */
  291. #if defined(MBEDTLS_SELF_TEST)
  292. /**
  293. * \brief Checkup routine
  294. *
  295. * \return 0 if successful, or 1 if the test failed
  296. */
  297. int mbedtls_camellia_self_test( int verbose );
  298. #endif /* MBEDTLS_SELF_TEST */
  299. #ifdef __cplusplus
  300. }
  301. #endif
  302. #endif /* camellia.h */