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 "mbedtls/config.h"
00035 #else
00036 #include MBEDTLS_CONFIG_FILE
00037 #endif
00038 
00039 #include <stddef.h>
00040 #include <stdint.h>
00041 
00042 #include "mbedtls/platform_util.h"
00043 
00044 #define MBEDTLS_ARIA_ENCRYPT     1 /**< ARIA encryption. */
00045 #define MBEDTLS_ARIA_DECRYPT     0 /**< ARIA decryption. */
00046 
00047 #define MBEDTLS_ARIA_BLOCKSIZE   16 /**< ARIA block size in bytes. */
00048 #define MBEDTLS_ARIA_MAX_ROUNDS  16 /**< Maxiumum number of rounds in ARIA. */
00049 #define MBEDTLS_ARIA_MAX_KEYSIZE 32 /**< Maximum size of an ARIA key in bytes. */
00050 
00051 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
00052 #define MBEDTLS_ERR_ARIA_INVALID_KEY_LENGTH   MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( -0x005C )
00053 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
00054 #define MBEDTLS_ERR_ARIA_BAD_INPUT_DATA -0x005C /**< Bad input data. */
00055 
00056 #define MBEDTLS_ERR_ARIA_INVALID_INPUT_LENGTH -0x005E /**< Invalid data input length. */
00057 
00058 /* MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE is deprecated and should not be used.
00059  */
00060 #define MBEDTLS_ERR_ARIA_FEATURE_UNAVAILABLE  -0x005A  /**< Feature not available. For example, an unsupported ARIA key size. */
00061 
00062 /* MBEDTLS_ERR_ARIA_HW_ACCEL_FAILED is deprecated and should not be used. */
00063 #define MBEDTLS_ERR_ARIA_HW_ACCEL_FAILED      -0x0058  /**< ARIA hardware accelerator failed. */
00064 
00065 #if !defined(MBEDTLS_ARIA_ALT)
00066 // Regular implementation
00067 //
00068 
00069 #ifdef __cplusplus
00070 extern "C" {
00071 #endif
00072 
00073 /**
00074  * \brief The ARIA context-type definition.
00075  */
00076 typedef struct mbedtls_aria_context
00077 {
00078     unsigned char nr ;           /*!< The number of rounds (12, 14 or 16) */
00079     /*! The ARIA round keys. */
00080     uint32_t rk [MBEDTLS_ARIA_MAX_ROUNDS + 1][MBEDTLS_ARIA_BLOCKSIZE / 4];
00081 }
00082 mbedtls_aria_context;
00083 
00084 #else  /* MBEDTLS_ARIA_ALT */
00085 #include "aria_alt.h"
00086 #endif /* MBEDTLS_ARIA_ALT */
00087 
00088 /**
00089  * \brief          This function initializes the specified ARIA context.
00090  *
00091  *                 It must be the first API called before using
00092  *                 the context.
00093  *
00094  * \param ctx      The ARIA context to initialize. This must not be \c NULL.
00095  */
00096 void mbedtls_aria_init( mbedtls_aria_context *ctx );
00097 
00098 /**
00099  * \brief          This function releases and clears the specified ARIA context.
00100  *
00101  * \param ctx      The ARIA context to clear. This may be \c NULL, in which
00102  *                 case this function returns immediately. If it is not \c NULL,
00103  *                 it must point to an initialized ARIA context.
00104  */
00105 void mbedtls_aria_free( mbedtls_aria_context *ctx );
00106 
00107 /**
00108  * \brief          This function sets the encryption key.
00109  *
00110  * \param ctx      The ARIA context to which the key should be bound.
00111  *                 This must be initialized.
00112  * \param key      The encryption key. This must be a readable buffer
00113  *                 of size \p keybits Bits.
00114  * \param keybits  The size of \p key in Bits. Valid options are:
00115  *                 <ul><li>128 bits</li>
00116  *                 <li>192 bits</li>
00117  *                 <li>256 bits</li></ul>
00118  *
00119  * \return         \c 0 on success.
00120  * \return         A negative error code on failure.
00121  */
00122 int mbedtls_aria_setkey_enc( mbedtls_aria_context *ctx,
00123                              const unsigned char *key,
00124                              unsigned int keybits );
00125 
00126 /**
00127  * \brief          This function sets the decryption key.
00128  *
00129  * \param ctx      The ARIA context to which the key should be bound.
00130  *                 This must be initialized.
00131  * \param key      The decryption key. This must be a readable buffer
00132  *                 of size \p keybits Bits.
00133  * \param keybits  The size of data passed. Valid options are:
00134  *                 <ul><li>128 bits</li>
00135  *                 <li>192 bits</li>
00136  *                 <li>256 bits</li></ul>
00137  *
00138  * \return         \c 0 on success.
00139  * \return         A negative error code on failure.
00140  */
00141 int mbedtls_aria_setkey_dec( mbedtls_aria_context *ctx,
00142                              const unsigned char *key,
00143                              unsigned int keybits );
00144 
00145 /**
00146  * \brief          This function performs an ARIA single-block encryption or
00147  *                 decryption operation.
00148  *
00149  *                 It performs encryption or decryption (depending on whether
00150  *                 the key was set for encryption on decryption) on the input
00151  *                 data buffer defined in the \p input parameter.
00152  *
00153  *                 mbedtls_aria_init(), and either mbedtls_aria_setkey_enc() or
00154  *                 mbedtls_aria_setkey_dec() must be called before the first
00155  *                 call to this API with the same context.
00156  *
00157  * \param ctx      The ARIA context to use for encryption or decryption.
00158  *                 This must be initialized and bound to a key.
00159  * \param input    The 16-Byte buffer holding the input data.
00160  * \param output   The 16-Byte buffer holding the output data.
00161 
00162  * \return         \c 0 on success.
00163  * \return         A negative error code on failure.
00164  */
00165 int mbedtls_aria_crypt_ecb( mbedtls_aria_context *ctx,
00166                             const unsigned char input[MBEDTLS_ARIA_BLOCKSIZE],
00167                             unsigned char output[MBEDTLS_ARIA_BLOCKSIZE] );
00168 
00169 #if defined(MBEDTLS_CIPHER_MODE_CBC)
00170 /**
00171  * \brief  This function performs an ARIA-CBC encryption or decryption operation
00172  *         on full blocks.
00173  *
00174  *         It performs the operation defined in the \p mode
00175  *         parameter (encrypt/decrypt), on the input data buffer defined in
00176  *         the \p input parameter.
00177  *
00178  *         It can be called as many times as needed, until all the input
00179  *         data is processed. mbedtls_aria_init(), and either
00180  *         mbedtls_aria_setkey_enc() or mbedtls_aria_setkey_dec() must be called
00181  *         before the first call to this API with the same context.
00182  *
00183  * \note   This function operates on aligned blocks, that is, the input size
00184  *         must be a multiple of the ARIA block size of 16 Bytes.
00185  *
00186  * \note   Upon exit, the content of the IV is updated so that you can
00187  *         call the same function again on the next
00188  *         block(s) of data and get the same result as if it was
00189  *         encrypted in one call. This allows a "streaming" usage.
00190  *         If you need to retain the contents of the IV, you should
00191  *         either save it manually or use the cipher module instead.
00192  *
00193  *
00194  * \param ctx      The ARIA context to use for encryption or decryption.
00195  *                 This must be initialized and bound to a key.
00196  * \param mode     The mode of operation. This must be either
00197  *                 #MBEDTLS_ARIA_ENCRYPT for encryption, or
00198  *                 #MBEDTLS_ARIA_DECRYPT for decryption.
00199  * \param length   The length of the input data in Bytes. This must be a
00200  *                 multiple of the block size (16 Bytes).
00201  * \param iv       Initialization vector (updated after use).
00202  *                 This must be a readable buffer of size 16 Bytes.
00203  * \param input    The buffer holding the input data. This must
00204  *                 be a readable buffer of length \p length Bytes.
00205  * \param output   The buffer holding the output data. This must
00206  *                 be a writable buffer of length \p length Bytes.
00207  *
00208  * \return         \c 0 on success.
00209  * \return         A negative error code on failure.
00210  */
00211 int mbedtls_aria_crypt_cbc( mbedtls_aria_context *ctx,
00212                             int mode,
00213                             size_t length,
00214                             unsigned char iv[MBEDTLS_ARIA_BLOCKSIZE],
00215                             const unsigned char *input,
00216                             unsigned char *output );
00217 #endif /* MBEDTLS_CIPHER_MODE_CBC */
00218 
00219 #if defined(MBEDTLS_CIPHER_MODE_CFB)
00220 /**
00221  * \brief This function performs an ARIA-CFB128 encryption or decryption
00222  *        operation.
00223  *
00224  *        It performs the operation defined in the \p mode
00225  *        parameter (encrypt or decrypt), on the input data buffer
00226  *        defined in the \p input parameter.
00227  *
00228  *        For CFB, you must set up the context with mbedtls_aria_setkey_enc(),
00229  *        regardless of whether you are performing an encryption or decryption
00230  *        operation, that is, regardless of the \p mode parameter. This is
00231  *        because CFB mode uses the same key schedule for encryption and
00232  *        decryption.
00233  *
00234  * \note  Upon exit, the content of the IV is updated so that you can
00235  *        call the same function again on the next
00236  *        block(s) of data and get the same result as if it was
00237  *        encrypted in one call. This allows a "streaming" usage.
00238  *        If you need to retain the contents of the
00239  *        IV, you must either save it manually or use the cipher
00240  *        module instead.
00241  *
00242  *
00243  * \param ctx      The ARIA context to use for encryption or decryption.
00244  *                 This must be initialized and bound to a key.
00245  * \param mode     The mode of operation. This must be either
00246  *                 #MBEDTLS_ARIA_ENCRYPT for encryption, or
00247  *                 #MBEDTLS_ARIA_DECRYPT for decryption.
00248  * \param length   The length of the input data \p input in Bytes.
00249  * \param iv_off   The offset in IV (updated after use).
00250  *                 This must not be larger than 15.
00251  * \param iv       The initialization vector (updated after use).
00252  *                 This must be a readable buffer of size 16 Bytes.
00253  * \param input    The buffer holding the input data. This must
00254  *                 be a readable buffer of length \p length Bytes.
00255  * \param output   The buffer holding the output data. This must
00256  *                 be a writable buffer of length \p length Bytes.
00257  *
00258  * \return         \c 0 on success.
00259  * \return         A negative error code on failure.
00260  */
00261 int mbedtls_aria_crypt_cfb128( mbedtls_aria_context *ctx,
00262                                int mode,
00263                                size_t length,
00264                                size_t *iv_off,
00265                                unsigned char iv[MBEDTLS_ARIA_BLOCKSIZE],
00266                                const unsigned char *input,
00267                                unsigned char *output );
00268 #endif /* MBEDTLS_CIPHER_MODE_CFB */
00269 
00270 #if defined(MBEDTLS_CIPHER_MODE_CTR)
00271 /**
00272  * \brief      This function performs an ARIA-CTR encryption or decryption
00273  *             operation.
00274  *
00275  *             This function performs the operation defined in the \p mode
00276  *             parameter (encrypt/decrypt), on the input data buffer
00277  *             defined in the \p input parameter.
00278  *
00279  *             Due to the nature of CTR, you must use the same key schedule
00280  *             for both encryption and decryption operations. Therefore, you
00281  *             must use the context initialized with mbedtls_aria_setkey_enc()
00282  *             for both #MBEDTLS_ARIA_ENCRYPT and #MBEDTLS_ARIA_DECRYPT.
00283  *
00284  * \warning    You must never reuse a nonce value with the same key. Doing so
00285  *             would void the encryption for the two messages encrypted with
00286  *             the same nonce and key.
00287  *
00288  *             There are two common strategies for managing nonces with CTR:
00289  *
00290  *             1. You can handle everything as a single message processed over
00291  *             successive calls to this function. In that case, you want to
00292  *             set \p nonce_counter and \p nc_off to 0 for the first call, and
00293  *             then preserve the values of \p nonce_counter, \p nc_off and \p
00294  *             stream_block across calls to this function as they will be
00295  *             updated by this function.
00296  *
00297  *             With this strategy, you must not encrypt more than 2**128
00298  *             blocks of data with the same key.
00299  *
00300  *             2. You can encrypt separate messages by dividing the \p
00301  *             nonce_counter buffer in two areas: the first one used for a
00302  *             per-message nonce, handled by yourself, and the second one
00303  *             updated by this function internally.
00304  *
00305  *             For example, you might reserve the first 12 bytes for the
00306  *             per-message nonce, and the last 4 bytes for internal use. In that
00307  *             case, before calling this function on a new message you need to
00308  *             set the first 12 bytes of \p nonce_counter to your chosen nonce
00309  *             value, the last 4 to 0, and \p nc_off to 0 (which will cause \p
00310  *             stream_block to be ignored). That way, you can encrypt at most
00311  *             2**96 messages of up to 2**32 blocks each with the same key.
00312  *
00313  *             The per-message nonce (or information sufficient to reconstruct
00314  *             it) needs to be communicated with the ciphertext and must be unique.
00315  *             The recommended way to ensure uniqueness is to use a message
00316  *             counter. An alternative is to generate random nonces, but this
00317  *             limits the number of messages that can be securely encrypted:
00318  *             for example, with 96-bit random nonces, you should not encrypt
00319  *             more than 2**32 messages with the same key.
00320  *
00321  *             Note that for both stategies, sizes are measured in blocks and
00322  *             that an ARIA block is 16 bytes.
00323  *
00324  * \warning    Upon return, \p stream_block contains sensitive data. Its
00325  *             content must not be written to insecure storage and should be
00326  *             securely discarded as soon as it's no longer needed.
00327  *
00328  * \param ctx              The ARIA context to use for encryption or decryption.
00329  *                         This must be initialized and bound to a key.
00330  * \param length           The length of the input data \p input in Bytes.
00331  * \param nc_off           The offset in Bytes in the current \p stream_block,
00332  *                         for resuming within the current cipher stream. The
00333  *                         offset pointer should be \c 0 at the start of a
00334  *                         stream. This must not be larger than \c 15 Bytes.
00335  * \param nonce_counter    The 128-bit nonce and counter. This must point to
00336  *                         a read/write buffer of length \c 16 bytes.
00337  * \param stream_block     The saved stream block for resuming. This must
00338  *                         point to a read/write buffer of length \c 16 bytes.
00339  *                         This is overwritten by the function.
00340  * \param input            The buffer holding the input data. This must
00341  *                         be a readable buffer of length \p length Bytes.
00342  * \param output           The buffer holding the output data. This must
00343  *                         be a writable buffer of length \p length Bytes.
00344  *
00345  * \return                 \c 0 on success.
00346  * \return                 A negative error code on failure.
00347  */
00348 int mbedtls_aria_crypt_ctr( mbedtls_aria_context *ctx,
00349                             size_t length,
00350                             size_t *nc_off,
00351                             unsigned char nonce_counter[MBEDTLS_ARIA_BLOCKSIZE],
00352                             unsigned char stream_block[MBEDTLS_ARIA_BLOCKSIZE],
00353                             const unsigned char *input,
00354                             unsigned char *output );
00355 #endif /* MBEDTLS_CIPHER_MODE_CTR */
00356 
00357 #if defined(MBEDTLS_SELF_TEST)
00358 /**
00359  * \brief          Checkup routine.
00360  *
00361  * \return         \c 0 on success, or \c 1 on failure.
00362  */
00363 int mbedtls_aria_self_test( int verbose );
00364 #endif /* MBEDTLS_SELF_TEST */
00365 
00366 #ifdef __cplusplus
00367 }
00368 #endif
00369 
00370 #endif /* aria.h */