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