internal-gift128.h 7.92 KB
Newer Older
Rhys Weatherley committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
/*
 * Copyright (C) 2020 Southern Storm Software, Pty Ltd.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#ifndef LW_INTERNAL_GIFT128_H
#define LW_INTERNAL_GIFT128_H

/**
 * \file internal-gift128.h
 * \brief GIFT-128 block cipher.
 *
 * There are three versions of GIFT-128 in use within the second round
 * submissions to the NIST lightweight cryptography competition.
 *
 * The most efficient version for 32-bit software implementation is the
 * GIFT-128-b bit-sliced version from GIFT-COFB and SUNDAE-GIFT.
 *
 * The second is the nibble-based version from HYENA.  We implement the
 * HYENA version as a wrapper around the bit-sliced version.
 *
 * The third version is a variant on the HYENA nibble-based version that
 * includes a 4-bit tweak value for domain separation.  It is used by
 * the ESTATE submission to NIST.
 *
 * Technically there is a fourth version of GIFT-128 which is the one that
 * appeared in the original GIFT-128 paper.  It is almost the same as the
 * HYENA version except that the byte ordering is big-endian instead of
 * HYENA's little-endian.  The original version of GIFT-128 doesn't appear
 * in any of the NIST submissions so we don't bother with it in this library.
 *
 * References: https://eprint.iacr.org/2017/622.pdf,
 * https://giftcipher.github.io/gift/
 */

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \brief Size of a GIFT-128 block in bytes.
 */
#define GIFT128_BLOCK_SIZE 16

/**
 * \brief Number of round keys for the fixsliced representation of GIFT-128.
 */
#define GIFT128_ROUND_KEYS 80

/**
 * \brief Structure of the key schedule for GIFT-128 (bit-sliced).
 */
typedef struct
{
    /** Pre-computed round keys in the fixsliced form */
    uint32_t k[GIFT128_ROUND_KEYS];

} gift128b_key_schedule_t;

/**
 * \brief Initializes the key schedule for GIFT-128 (bit-sliced).
 *
 * \param ks Points to the key schedule to initialize.
 * \param key Points to the key data.
 * \param key_len Length of the key data, which must be 16.
 *
 * \return Non-zero on success or zero if there is something wrong
 * with the parameters.
 */
int gift128b_init
    (gift128b_key_schedule_t *ks, const unsigned char *key, size_t key_len);

/**
 * \brief Encrypts a 128-bit block with GIFT-128 (bit-sliced).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place encryption.
 */
void gift128b_encrypt
    (const gift128b_key_schedule_t *ks, unsigned char *output,
     const unsigned char *input);

/**
 * \brief Encrypts a 128-bit block with GIFT-128 (bit-sliced and pre-loaded).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place encryption.
 *
 * This version assumes that the input has already been pre-loaded from
 * big-endian into host byte order in the supplied word array.  The output
 * is delivered in the same way.
 */
void gift128b_encrypt_preloaded
    (const gift128b_key_schedule_t *ks, uint32_t output[4],
     const uint32_t input[4]);

/**
 * \brief Decrypts a 128-bit block with GIFT-128 (bit-sliced).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place decryption.
 */
void gift128b_decrypt
    (const gift128b_key_schedule_t *ks, unsigned char *output,
     const unsigned char *input);

/**
 * \brief Structure of the key schedule for GIFT-128 (nibble-based).
 */
typedef gift128b_key_schedule_t gift128n_key_schedule_t;

/**
 * \brief Initializes the key schedule for GIFT-128 (nibble-based).
 *
 * \param ks Points to the key schedule to initialize.
 * \param key Points to the key data.
 * \param key_len Length of the key data, which must be 16.
 *
 * \return Non-zero on success or zero if there is something wrong
 * with the parameters.
 */
int gift128n_init
    (gift128n_key_schedule_t *ks, const unsigned char *key, size_t key_len);

/**
 * \brief Encrypts a 128-bit block with GIFT-128 (nibble-based).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place encryption.
 */
void gift128n_encrypt
    (const gift128n_key_schedule_t *ks, unsigned char *output,
     const unsigned char *input);

/**
 * \brief Decrypts a 128-bit block with GIFT-128 (nibble-based).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place decryption.
 */
void gift128n_decrypt
    (const gift128n_key_schedule_t *ks, unsigned char *output,
     const unsigned char *input);

/**
 * \brief Encrypts a 128-bit block with TweGIFT-128 (tweakable variant).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 * \param tweak 4-bit tweak value.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place encryption.
 *
 * This variant of GIFT-128 is used by the ESTATE submission to the
 * NIST Lightweight Cryptography Competition.  A 4-bit tweak is added to
 * some of the rounds to provide domain separation.  If the tweak is
 * zero, then this function is identical to gift128n_encrypt().
 */
void gift128t_encrypt
    (const gift128n_key_schedule_t *ks, unsigned char *output,
     const unsigned char *input, unsigned char tweak);

/**
 * \brief Decrypts a 128-bit block with TweGIFT-128 (tweakable variant).
 *
 * \param ks Points to the GIFT-128 key schedule.
 * \param output Output buffer which must be at least 16 bytes in length.
 * \param input Input buffer which must be at least 16 bytes in length.
 * \param tweak 4-bit tweak value.
 *
 * The \a input and \a output buffers can be the same buffer for
 * in-place encryption.
 *
 * This variant of GIFT-128 is used by the ESTATE submission to the
 * NIST Lightweight Cryptography Competition.  A 4-bit tweak is added to
 * some of the rounds to provide domain separation.  If the tweak is
 * zero, then this function is identical to gift128n_encrypt().
 */
void gift128t_decrypt
    (const gift128n_key_schedule_t *ks, unsigned char *output,
     const unsigned char *input, unsigned char tweak);

#ifdef __cplusplus
}
#endif

#endif