aria.h

00001 /**
00002  * \file aria.h
00003  *
00004  * \brief ARIA block cipher
00005  *
00006  *        The ARIA algorithm is a symmetric block cipher that can encrypt and
00007  *        decrypt information. It is defined by the Korean Agency for
00008  *        Technology and Standards (KATS) in <em>KS X 1213:2004</em> (in
00009  *        Korean, but see http://210.104.33.10/ARIA/index-e.html in English)
00010  *        and also described by the IETF in <em>RFC 5794</em>.
00011  */
00012 /*  Copyright (C) 2006-2018, ARM Limited, All Rights Reserved
00013  *  SPDX-License-Identifier: Apache-2.0
00014  *
00015  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00016  *  not use this file except in compliance with the License.
00017  *  You may obtain a copy of the License at
00018  *
00019  *  http://www.apache.org/licenses/LICENSE-2.0
00020  *
00021  *  Unless required by applicable law or agreed to in writing, software
00022  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00023  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00024  *  See the License for the specific language governing permissions and
00025  *  limitations under the License.
00026  *
00027  *  This file is part of mbed TLS (https://tls.mbed.org)
00028  */
00029 
00030 #ifndef MBEDTLS_ARIA_H
00031 #define MBEDTLS_ARIA_H
00032 
00033 #if !defined(MBEDTLS_CONFIG_FILE)
00034 #include "config.h"
00035 #else
00036 #include MBEDTLS_CONFIG_FILE
00037 #endif
00038 
00039 #include <stddef.h>
00040 #include <stdint.h>
00041 
00042 #define MBEDTLS_ARIA_ENCRYPT     1 /**< ARIA encryption. */
00043 #define MBEDTLS_ARIA_DECRYPT     0 /**< ARIA decryption. */
00044 
00045 #define MBEDTLS_ARIA_BLOCKSIZE   16 /**< ARIA block size in bytes. */
00046 #define MBEDTLS_ARIA_MAX_ROUNDS  16 /**< Maxiumum number of rounds in ARIA. */
00047 #define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
00048 
00049 #define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH   -0x005C  /**< Invalid key length. */
00050 #define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E  /**< Invalid data input length. */
00051 #define MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE  -0x005A  /**< Feature not available. For example, an unsupported ARIA key size. */
00052 #define MBEDTLS_ERR_ARIA_HW_ACCEL_FAILED      -0x0058  /**< ARIA hardware accelerator failed. */
00053 
00054 #if !defined(MBEDTLS_ARIA_ALT)
00055 // Regular implementation
00056 //
00057 
00058 #ifdef __cplusplus
00059 extern "C" {
00060 #endif
00061 
00062 /**
00063  * \brief The ARIA context-type definition.
00064  */
00065 typedef struct
00066 {
00067     unsigned char nr ;           /*!< The number of rounds (12, 14 or 16) */
00068     /*! The ARIA round keys. */
00069     uint32_t rk[MBEDTLS_ARIA_MAX_ROUNDS + 1][MBEDTLS_ARIA_BLOCKSIZE / 4];
00070 }
00071 mbedtls_aria_context;
00072 
00073 #else  /* MBEDTLS_ARIA_ALT */
00074 #include "aria_alt.h"
00075 #endif /* MBEDTLS_ARIA_ALT */
00076 
00077 /**
00078  * \brief          This function initializes the specified ARIA context.
00079  *
00080  *                 It must be the first API called before using
00081  *                 the context.
00082  *
00083  * \param ctx      The ARIA context to initialize.
00084  */
00085 void mbedtls_aria_init( mbedtls_aria_context *ctx );
00086 
00087 /**
00088  * \brief          This function releases and clears the specified ARIA context.
00089  *
00090  * \param ctx      The ARIA context to clear.
00091  */
00092 void mbedtls_aria_free( mbedtls_aria_context *ctx );
00093 
00094 /**
00095  * \brief          This function sets the encryption key.
00096  *
00097  * \param ctx      The ARIA context to which the key should be bound.
00098  * \param key      The encryption key.
00099  * \param keybits  The size of data passed in bits. Valid options are:
00100  *                 <ul><li>128 bits</li>
00101  *                 <li>192 bits</li>
00102  *                 <li>256 bits</li></ul>
00103  *
00104  * \return         \c 0 on success or #MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH
00105  *                 on failure.
00106  */
00107 int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx,
00108                              const unsigned char *key,
00109                              unsigned int keybits );
00110 
00111 /**
00112  * \brief          This function sets the decryption key.
00113  *
00114  * \param ctx      The ARIA context to which the key should be bound.
00115  * \param key      The decryption key.
00116  * \param keybits  The size of data passed. Valid options are:
00117  *                 <ul><li>128 bits</li>
00118  *                 <li>192 bits</li>
00119  *                 <li>256 bits</li></ul>
00120  *
00121  * \return         \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH on failure.
00122  */
00123 int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx,
00124                              const unsigned char *key,
00125                              unsigned int keybits );
00126 
00127 /**
00128  * \brief          This function performs an ARIA single-block encryption or
00129  *                 decryption operation.
00130  *
00131  *                 It performs encryption or decryption (depending on whether
00132  *                 the key was set for encryption on decryption) on the input
00133  *                 data buffer defined in the \p input parameter.
00134  *
00135  *                 mbedtls_aria_init(), and either mbedtls_aria_setkey_enc() or
00136  *                 mbedtls_aria_setkey_dec() must be called before the first
00137  *                 call to this API with the same context.
00138  *
00139  * \param ctx      The ARIA context to use for encryption or decryption.
00140  * \param input    The 16-Byte buffer holding the input data.
00141  * \param output   The 16-Byte buffer holding the output data.
00142 
00143  * \return         \c 0 on success.
00144  */
00145 int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx,
00146                             const unsigned char input[MBEDTLS_ARIA_BLOCKSIZE],
00147                             unsigned char output[MBEDTLS_ARIA_BLOCKSIZE] );
00148 
00149 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00150 /**
00151  * \brief  This function performs an ARIA-CBC encryption or decryption operation
00152  *         on full blocks.
00153  *
00154  *         It performs the operation defined in the \p mode
00155  *         parameter (encrypt/decrypt), on the input data buffer defined in
00156  *         the \p input parameter.
00157  *
00158  *         It can be called as many times as needed, until all the input
00159  *         data is processed. mbedtls_aria_init(), and either
00160  *         mbedtls_aria_setkey_enc() or mbedtls_aria_setkey_dec() must be called
00161  *         before the first call to this API with the same context.
00162  *
00163  * \note   This function operates on aligned blocks, that is, the input size
00164  *         must be a multiple of the ARIA block size of 16 Bytes.
00165  *
00166  * \note   Upon exit, the content of the IV is updated so that you can
00167  *         call the same function again on the next
00168  *         block(s) of data and get the same result as if it was
00169  *         encrypted in one call. This allows a "streaming" usage.
00170  *         If you need to retain the contents of the IV, you should
00171  *         either save it manually or use the cipher module instead.
00172  *
00173  *
00174  * \param ctx      The ARIA context to use for encryption or decryption.
00175  * \param mode     The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or
00176  *                 #MBEDTLS_ARIA_DECRYPT.
00177  * \param length   The length of the input data in Bytes. This must be a
00178  *                 multiple of the block size (16 Bytes).
00179  * \param iv       Initialization vector (updated after use).
00180  * \param input    The buffer holding the input data.
00181  * \param output   The buffer holding the output data.
00182  *
00183  * \return         \c 0 on success, or #MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH
00184  *                 on failure.
00185  */
00186 int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx,
00187                             int mode,
00188                             size_t length,
00189                             unsigned char iv[MBEDTLS_ARIA_BLOCKSIZE],
00190                             const unsigned char *input,
00191                             unsigned char *output );
00192 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00193 
00194 #if defined(MBEDTLS_CIPHER_MODE_CFB)
00195 /**
00196  * \brief This function performs an ARIA-CFB128 encryption or decryption
00197  *        operation.
00198  *
00199  *        It performs the operation defined in the \p mode
00200  *        parameter (encrypt or decrypt), on the input data buffer
00201  *        defined in the \p input parameter.
00202  *
00203  *        For CFB, you must set up the context with mbedtls_aria_setkey_enc(),
00204  *        regardless of whether you are performing an encryption or decryption
00205  *        operation, that is, regardless of the \p mode parameter. This is
00206  *        because CFB mode uses the same key schedule for encryption and
00207  *        decryption.
00208  *
00209  * \note  Upon exit, the content of the IV is updated so that you can
00210  *        call the same function again on the next
00211  *        block(s) of data and get the same result as if it was
00212  *        encrypted in one call. This allows a "streaming" usage.
00213  *        If you need to retain the contents of the
00214  *        IV, you must either save it manually or use the cipher
00215  *        module instead.
00216  *
00217  *
00218  * \param ctx      The ARIA context to use for encryption or decryption.
00219  * \param mode     The ARIA operation: #MBEDTLS_ARIA_ENCRYPT or
00220  *                 #MBEDTLS_ARIA_DECRYPT.
00221  * \param length   The length of the input data.
00222  * \param iv_off   The offset in IV (updated after use).
00223  * \param iv       The initialization vector (updated after use).
00224  * \param input    The buffer holding the input data.
00225  * \param output   The buffer holding the output data.
00226  *
00227  * \return         \c 0 on success.
00228  */
00229 int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
00230                                int mode,
00231                                size_t length,
00232                                size_t *iv_off,
00233                                unsigned char iv[MBEDTLS_ARIA_BLOCKSIZE],
00234                                const unsigned char *input,
00235                                unsigned char *output );
00236 #endif /* MBEDTLS_CIPHER_MODE_CFB */
00237 
00238 #if defined(MBEDTLS_CIPHER_MODE_CTR)
00239 /**
00240  * \brief      This function performs an ARIA-CTR encryption or decryption
00241  *             operation.
00242  *
00243  *             This function performs the operation defined in the \p mode
00244  *             parameter (encrypt/decrypt), on the input data buffer
00245  *             defined in the \p input parameter.
00246  *
00247  *             Due to the nature of CTR, you must use the same key schedule
00248  *             for both encryption and decryption operations. Therefore, you
00249  *             must use the context initialized with mbedtls_aria_setkey_enc()
00250  *             for both #MBEDTLS_ARIA_ENCRYPT and #MBEDTLS_ARIA_DECRYPT.
00251  *
00252  * \warning    You must never reuse a nonce value with the same key. Doing so
00253  *             would void the encryption for the two messages encrypted with
00254  *             the same nonce and key.
00255  *
00256  *             There are two common strategies for managing nonces with CTR:
00257  *
00258  *             1. You can handle everything as a single message processed over
00259  *             successive calls to this function. In that case, you want to
00260  *             set \p nonce_counter and \p nc_off to 0 for the first call, and
00261  *             then preserve the values of \p nonce_counter, \p nc_off and \p
00262  *             stream_block across calls to this function as they will be
00263  *             updated by this function.
00264  *
00265  *             With this strategy, you must not encrypt more than 2**128
00266  *             blocks of data with the same key.
00267  *
00268  *             2. You can encrypt separate messages by dividing the \p
00269  *             nonce_counter buffer in two areas: the first one used for a
00270  *             per-message nonce, handled by yourself, and the second one
00271  *             updated by this function internally.
00272  *
00273  *             For example, you might reserve the first 12 bytes for the
00274  *             per-message nonce, and the last 4 bytes for internal use. In that
00275  *             case, before calling this function on a new message you need to
00276  *             set the first 12 bytes of \p nonce_counter to your chosen nonce
00277  *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
00278  *             stream_block to be ignored). That way, you can encrypt at most
00279  *             2**96 messages of up to 2**32 blocks each with the same key.
00280  *
00281  *             The per-message nonce (or information sufficient to reconstruct
00282  *             it) needs to be communicated with the ciphertext and must be unique.
00283  *             The recommended way to ensure uniqueness is to use a message
00284  *             counter. An alternative is to generate random nonces, but this
00285  *             limits the number of messages that can be securely encrypted:
00286  *             for example, with 96-bit random nonces, you should not encrypt
00287  *             more than 2**32 messages with the same key.
00288  *
00289  *             Note that for both stategies, sizes are measured in blocks and
00290  *             that an ARIA block is 16 bytes.
00291  *
00292  * \warning    Upon return, \p stream_block contains sensitive data. Its
00293  *             content must not be written to insecure storage and should be
00294  *             securely discarded as soon as it's no longer needed.
00295  *
00296  * \param ctx              The ARIA context to use for encryption or decryption.
00297  * \param length           The length of the input data.
00298  * \param nc_off           The offset in the current \p stream_block, for
00299  *                         resuming within the current cipher stream. The
00300  *                         offset pointer should be 0 at the start of a stream.
00301  * \param nonce_counter    The 128-bit nonce and counter.
00302  * \param stream_block     The saved stream block for resuming. This is
00303  *                         overwritten by the function.
00304  * \param input            The buffer holding the input data.
00305  * \param output           The buffer holding the output data.
00306  *
00307  * \return     \c 0 on success.
00308  */
00309 int mbedtls_aria_crypt_ctr( mbedtls_aria_context *ctx,
00310                             size_t length,
00311                             size_t *nc_off,
00312                             unsigned char nonce_counter[MBEDTLS_ARIA_BLOCKSIZE],
00313                             unsigned char stream_block[MBEDTLS_ARIA_BLOCKSIZE],
00314                             const unsigned char *input,
00315                             unsigned char *output );
00316 #endif /* MBEDTLS_CIPHER_MODE_CTR */
00317 
00318 #if defined(MBEDTLS_SELF_TEST)
00319 /**
00320  * \brief          Checkup routine.
00321  *
00322  * \return         \c 0 on success, or \c 1 on failure.
00323  */
00324 int mbedtls_aria_self_test( int verbose );
00325 #endif /* MBEDTLS_SELF_TEST */
00326 
00327 #ifdef __cplusplus
00328 }
00329 #endif
00330 
00331 #endif /* aria.h */