camellia.h

00001 /**
00002  * \file camellia.h
00003  *
00004  * \brief Camellia block cipher
00005  */
00006 /*
00007  *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
00008  *  SPDX-License-Identifier: Apache-2.0
00009  *
00010  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00011  *  not use this file except in compliance with the License.
00012  *  You may obtain a copy of the License at
00013  *
00014  *  http://www.apache.org/licenses/LICENSE-2.0
00015  *
00016  *  Unless required by applicable law or agreed to in writing, software
00017  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00018  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00019  *  See the License for the specific language governing permissions and
00020  *  limitations under the License.
00021  *
00022  *  This file is part of mbed TLS (https://tls.mbed.org)
00023  */
00024 #ifndef MBEDTLS_CAMELLIA_H
00025 #define MBEDTLS_CAMELLIA_H
00026 
00027 #if !defined(MBEDTLS_CONFIG_FILE)
00028 #include "config.h"
00029 #else
00030 #include MBEDTLS_CONFIG_FILE
00031 #endif
00032 
00033 #include <stddef.h>
00034 #include <stdint.h>
00035 
00036 #define MBEDTLS_CAMELLIA_ENCRYPT     1
00037 #define MBEDTLS_CAMELLIA_DECRYPT     0
00038 
00039 #define MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH           -0x0024  /**< Invalid key length. */
00040 #define MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH         -0x0026  /**< Invalid data input length. */
00041 #define MBEDTLS_ERR_CAMELLIA_HW_ACCEL_FAILED              -0x0027  /**< Camellia hardware accelerator failed. */
00042 
00043 #ifdef __cplusplus
00044 extern "C" {
00045 #endif
00046 
00047 #if !defined(MBEDTLS_CAMELLIA_ALT)
00048 // Regular implementation
00049 //
00050 
00051 /**
00052  * \brief          CAMELLIA context structure
00053  */
00054 typedef struct mbedtls_camellia_context
00055 {
00056     int nr ;                     /*!<  number of rounds  */
00057     uint32_t rk [68];            /*!<  CAMELLIA round keys    */
00058 }
00059 mbedtls_camellia_context;
00060 
00061 #else  /* MBEDTLS_CAMELLIA_ALT */
00062 #include "camellia_alt.h"
00063 #endif /* MBEDTLS_CAMELLIA_ALT */
00064 
00065 /**
00066  * \brief          Initialize CAMELLIA context
00067  *
00068  * \param ctx      CAMELLIA context to be initialized
00069  */
00070 void mbedtls_camellia_init( mbedtls_camellia_context *ctx );
00071 
00072 /**
00073  * \brief          Clear CAMELLIA context
00074  *
00075  * \param ctx      CAMELLIA context to be cleared
00076  */
00077 void mbedtls_camellia_free( mbedtls_camellia_context *ctx );
00078 
00079 /**
00080  * \brief          CAMELLIA key schedule (encryption)
00081  *
00082  * \param ctx      CAMELLIA context to be initialized
00083  * \param key      encryption key
00084  * \param keybits  must be 128, 192 or 256
00085  *
00086  * \return         0 if successful, or MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH
00087  */
00088 int mbedtls_camellia_setkey_enc( mbedtls_camellia_context *ctx, const unsigned char *key,
00089                          unsigned int keybits );
00090 
00091 /**
00092  * \brief          CAMELLIA key schedule (decryption)
00093  *
00094  * \param ctx      CAMELLIA context to be initialized
00095  * \param key      decryption key
00096  * \param keybits  must be 128, 192 or 256
00097  *
00098  * \return         0 if successful, or MBEDTLS_ERR_CAMELLIA_INVALID_KEY_LENGTH
00099  */
00100 int mbedtls_camellia_setkey_dec( mbedtls_camellia_context *ctx, const unsigned char *key,
00101                          unsigned int keybits );
00102 
00103 /**
00104  * \brief          CAMELLIA-ECB block encryption/decryption
00105  *
00106  * \param ctx      CAMELLIA context
00107  * \param mode     MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
00108  * \param input    16-byte input block
00109  * \param output   16-byte output block
00110  *
00111  * \return         0 if successful
00112  */
00113 int mbedtls_camellia_crypt_ecb( mbedtls_camellia_context *ctx,
00114                     int mode,
00115                     const unsigned char input[16],
00116                     unsigned char output[16] );
00117 
00118 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00119 /**
00120  * \brief          CAMELLIA-CBC buffer encryption/decryption
00121  *                 Length should be a multiple of the block
00122  *                 size (16 bytes)
00123  *
00124  * \note           Upon exit, the content of the IV is updated so that you can
00125  *                 call the function same function again on the following
00126  *                 block(s) of data and get the same result as if it was
00127  *                 encrypted in one call. This allows a "streaming" usage.
00128  *                 If on the other hand you need to retain the contents of the
00129  *                 IV, you should either save it manually or use the cipher
00130  *                 module instead.
00131  *
00132  * \param ctx      CAMELLIA context
00133  * \param mode     MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
00134  * \param length   length of the input data
00135  * \param iv       initialization vector (updated after use)
00136  * \param input    buffer holding the input data
00137  * \param output   buffer holding the output data
00138  *
00139  * \return         0 if successful, or
00140  *                 MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
00141  */
00142 int mbedtls_camellia_crypt_cbc( mbedtls_camellia_context *ctx,
00143                     int mode,
00144                     size_t length,
00145                     unsigned char iv[16],
00146                     const unsigned char *input,
00147                     unsigned char *output );
00148 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00149 
00150 #if defined(MBEDTLS_CIPHER_MODE_CFB)
00151 /**
00152  * \brief          CAMELLIA-CFB128 buffer encryption/decryption
00153  *
00154  * Note: Due to the nature of CFB you should use the same key schedule for
00155  * both encryption and decryption. So a context initialized with
00156  * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and CAMELLIE_DECRYPT.
00157  *
00158  * \note           Upon exit, the content of the IV is updated so that you can
00159  *                 call the function same function again on the following
00160  *                 block(s) of data and get the same result as if it was
00161  *                 encrypted in one call. This allows a "streaming" usage.
00162  *                 If on the other hand you need to retain the contents of the
00163  *                 IV, you should either save it manually or use the cipher
00164  *                 module instead.
00165  *
00166  * \param ctx      CAMELLIA context
00167  * \param mode     MBEDTLS_CAMELLIA_ENCRYPT or MBEDTLS_CAMELLIA_DECRYPT
00168  * \param length   length of the input data
00169  * \param iv_off   offset in IV (updated after use)
00170  * \param iv       initialization vector (updated after use)
00171  * \param input    buffer holding the input data
00172  * \param output   buffer holding the output data
00173  *
00174  * \return         0 if successful, or
00175  *                 MBEDTLS_ERR_CAMELLIA_INVALID_INPUT_LENGTH
00176  */
00177 int mbedtls_camellia_crypt_cfb128( mbedtls_camellia_context *ctx,
00178                        int mode,
00179                        size_t length,
00180                        size_t *iv_off,
00181                        unsigned char iv[16],
00182                        const unsigned char *input,
00183                        unsigned char *output );
00184 #endif /* MBEDTLS_CIPHER_MODE_CFB */
00185 
00186 #if defined(MBEDTLS_CIPHER_MODE_CTR)
00187 /**
00188  * \brief               CAMELLIA-CTR buffer encryption/decryption
00189  *
00190  * Note: Due to the nature of CTR you should use the same key schedule for
00191  * both encryption and decryption. So a context initialized with
00192  * mbedtls_camellia_setkey_enc() for both MBEDTLS_CAMELLIA_ENCRYPT and MBEDTLS_CAMELLIA_DECRYPT.
00193  *
00194  * \warning    You must never reuse a nonce value with the same key. Doing so
00195  *             would void the encryption for the two messages encrypted with
00196  *             the same nonce and key.
00197  *
00198  *             There are two common strategies for managing nonces with CTR:
00199  *
00200  *             1. You can handle everything as a single message processed over
00201  *             successive calls to this function. In that case, you want to
00202  *             set \p nonce_counter and \p nc_off to 0 for the first call, and
00203  *             then preserve the values of \p nonce_counter, \p nc_off and \p
00204  *             stream_block across calls to this function as they will be
00205  *             updated by this function.
00206  *
00207  *             With this strategy, you must not encrypt more than 2**128
00208  *             blocks of data with the same key.
00209  *
00210  *             2. You can encrypt separate messages by dividing the \p
00211  *             nonce_counter buffer in two areas: the first one used for a
00212  *             per-message nonce, handled by yourself, and the second one
00213  *             updated by this function internally.
00214  *
00215  *             For example, you might reserve the first 12 bytes for the
00216  *             per-message nonce, and the last 4 bytes for internal use. In that
00217  *             case, before calling this function on a new message you need to
00218  *             set the first 12 bytes of \p nonce_counter to your chosen nonce
00219  *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
00220  *             stream_block to be ignored). That way, you can encrypt at most
00221  *             2**96 messages of up to 2**32 blocks each with the same key.
00222  *
00223  *             The per-message nonce (or information sufficient to reconstruct
00224  *             it) needs to be communicated with the ciphertext and must be unique.
00225  *             The recommended way to ensure uniqueness is to use a message
00226  *             counter. An alternative is to generate random nonces, but this
00227  *             limits the number of messages that can be securely encrypted:
00228  *             for example, with 96-bit random nonces, you should not encrypt
00229  *             more than 2**32 messages with the same key.
00230  *
00231  *             Note that for both stategies, sizes are measured in blocks and
00232  *             that a CAMELLIA block is 16 bytes.
00233  *
00234  * \warning    Upon return, \p stream_block contains sensitive data. Its
00235  *             content must not be written to insecure storage and should be
00236  *             securely discarded as soon as it's no longer needed.
00237  *
00238  * \param ctx           CAMELLIA context
00239  * \param length        The length of the data
00240  * \param nc_off        The offset in the current stream_block (for resuming
00241  *                      within current cipher stream). The offset pointer to
00242  *                      should be 0 at the start of a stream.
00243  * \param nonce_counter The 128-bit nonce and counter.
00244  * \param stream_block  The saved stream-block for resuming. Is overwritten
00245  *                      by the function.
00246  * \param input         The input data stream
00247  * \param output        The output data stream
00248  *
00249  * \return         0 if successful
00250  */
00251 int mbedtls_camellia_crypt_ctr( mbedtls_camellia_context *ctx,
00252                        size_t length,
00253                        size_t *nc_off,
00254                        unsigned char nonce_counter[16],
00255                        unsigned char stream_block[16],
00256                        const unsigned char *input,
00257                        unsigned char *output );
00258 #endif /* MBEDTLS_CIPHER_MODE_CTR */
00259 
00260 /**
00261  * \brief          Checkup routine
00262  *
00263  * \return         0 if successful, or 1 if the test failed
00264  */
00265 int mbedtls_camellia_self_test( int verbose );
00266 
00267 #ifdef __cplusplus
00268 }
00269 #endif
00270 
00271 #endif /* camellia.h */