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