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