chiark - git - mdw - secnet/blob - sha3.h

   1 /* -*-c-*-
   2  *
   3  * The SHA3 algorithm family
   4  *
   5  * (c) 2017 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of secnet.
  11  * See README for full list of copyright holders.
  12  *
  13  * secnet is free software; you can redistribute it and/or modify it
  14  * under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version d of the License, or
  16  * (at your option) any later version.
  17  *
  18  * secnet is distributed in the hope that it will be useful, but
  19  * WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21  * General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * version 3 along with secnet; if not, see
  25  * https://www.gnu.org/licenses/gpl.html.
  26  *
  27  * This file was originally part of Catacomb, but has been automatically
  28  * modified for incorporation into secnet: see `import-catacomb-crypto'
  29  * for details.
  30  *
  31  * Catacomb is free software; you can redistribute it and/or modify
  32  * it under the terms of the GNU Library General Public License as
  33  * published by the Free Software Foundation; either version 2 of the
  34  * License, or (at your option) any later version.
  35  *
  36  * Catacomb is distributed in the hope that it will be useful,
  37  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  38  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  39  * GNU Library General Public License for more details.
  40  *
  41  * You should have received a copy of the GNU Library General Public
  42  * License along with Catacomb; if not, write to the Free
  43  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  44  * MA 02111-1307, USA.
  45  */
  46
  47 #ifndef CATACOMB_SHA3_H
  48 #define CATACOMB_SHA3_H
  49
  50 #ifdef __cplusplus
  51   extern "C" {
  52 #endif
  53
  54 /*----- Notes on the SHA3 algorithm family --------------------------------*
  55  *
  56  * The winner of the SHA3 competition was Keccak, designed by Guido Bertoni,
  57  * Joan Daemen, Michaël Peeters, and Gilles Van Assche.  The algorithm uses
  58  * their `sponge construction', based on a fixed attempt to instantiate an
  59  * `ideal permutation'.  The construction is rather versatile, and NIST has
  60  * standardized a number of algorithms based on it.
  61  *
  62  * The basic offerings are the drop-in replacements for the SHA2 family.
  63  * These are slower than is ideal, because of the decision to provide O(2^n)
  64  * resistance to second-preimage attacks for the n-bit hash function, which
  65  * means that, effectively, the capacity parameter is set unnecessarily
  66  * large.  (There was a major fuss when NIST tried to change this in a draft
  67  * of te standard.)  All of the obvious hash modes, e.g., HMAC, MGF, can be
  68  * applied to the SHA3 hash functions, though I can't really recommend this:
  69  * there's almost certainly a better way of doing whatever it is.
  70  *
  71  * Other members of the family are: SHAKE and cSHAKE, `extendable-output
  72  * funnctions' which can be used directly in place of MGFs; and KMAC, a
  73  * message authentication code with arbitrary-length key, message, and tag,
  74  * which can therefore be used as a key-derivation function.  The cSHAKE
  75  * construction, on which KMAC is based, introduces a personalization string
  76  * which can be used for domain separation.
  77  */
  78
  79 /*----- Header files ------------------------------------------------------*/
  80
  81 #include "fake-mLib-bits.h"
  82
  83 #ifndef CATACOMB_KECCAK1600_H
  84 #  include "keccak1600.h"
  85 #endif
  86
  87 /*----- The SHA3 hash function family -------------------------------------*/
  88
  89 typedef struct sha3_ctx {
  90   keccak1600_state s;
  91   unsigned r, w, n;
  92   octet buf[200];
  93 } sha3_ctx;
  94 #define sha3_224_ctx sha3_ctx
  95 #define sha3_256_ctx sha3_ctx
  96 #define sha3_384_ctx sha3_ctx
  97 #define sha3_512_ctx sha3_ctx
  98
  99 #define SHA3_224_HASHSZ 28
 100 #define SHA3_256_HASHSZ 32
 101 #define SHA3_384_HASHSZ 48
 102 #define SHA3_512_HASHSZ 64
 103
 104 #define SHA3_224_BUFSZ 144
 105 #define SHA3_256_BUFSZ 136
 106 #define SHA3_384_BUFSZ 104
 107 #define SHA3_512_BUFSZ 72
 108
 109 #define SHA3_STATESZ (sizeof(sha3_ctx))
 110 #define SHA3_224_STATESZ SHA3_STATESZ
 111 #define SHA3_256_STATESZ SHA3_STATESZ
 112 #define SHA3_384_STATESZ SHA3_STATESZ
 113 #define SHA3_512_STATESZ SHA3_STATESZ
 114
 115 /* --- @sha3_{224,256,384,512}_init@ --- *
 116  *
 117  * Arguments:   @sha3_ctx *ctx@ = pointer to context block to initialize
 118  *
 119  * Returns:     ---
 120  *
 121  * Use:         Initializes a SHA3 hashing context for use.
 122  */
 123
 124 extern void sha3_224_init(sha3_ctx */*ctx*/);
 125 extern void sha3_256_init(sha3_ctx */*ctx*/);
 126 extern void sha3_384_init(sha3_ctx */*ctx*/);
 127 extern void sha3_512_init(sha3_ctx */*ctx*/);
 128
 129 /* --- @sha3_hash@ --- *
 130  *
 131  * Arguments:   @sha3_ctx *ctx@ = pointer to context bock
 132  *              @const void *p@ = pointer to data to hash
 133  *              @size_t sz@ = size of buffer to hash
 134  *
 135  * Returns:     ---
 136  *
 137  * Use:         Hashes a buffer of data.  The buffer may be of any size and
 138  *              alignment.
 139  */
 140
 141 #define sha3_224_hash sha3_hash
 142 #define sha3_256_hash sha3_hash
 143 #define sha3_384_hash sha3_hash
 144 #define sha3_512_hash sha3_hash
 145
 146 extern void sha3_hash(sha3_ctx */*ctx*/, const void */*p*/, size_t /*sz*/);
 147
 148 /* --- @sha3_done@ --- *
 149  *
 150  * Arguments:   @sha3_ctx *ctx@ = pointer to context block
 151  *              @void *hash@ = pointer to output buffer
 152  *
 153  * Returns:     ---
 154  *
 155  * Use:         Returns the hash of the data read so far.
 156  */
 157
 158 #define sha3_224_done sha3_done
 159 #define sha3_256_done sha3_done
 160 #define sha3_384_done sha3_done
 161 #define sha3_512_done sha3_done
 162
 163 extern void sha3_done(sha3_ctx */*ctx*/, void */*hash*/);
 164
 165 /*----- The cSHAKE XOF algorithm ------------------------------------------*/
 166
 167 typedef struct shake_ctx {
 168   sha3_ctx h;
 169   unsigned st, op;
 170 } shake_ctx;
 171 #define shake128_ctx shake_ctx
 172 #define shake256_ctx shake_ctx
 173
 174 #define SHAKE128_KEYSZ 16
 175 #define SHAKE256_KEYSZ 32
 176
 177 #define SHAKE128_HASHSZ 32              /* Somewhat arbitrary... */
 178 #define SHAKE256_HASHSZ 64
 179
 180 /* --- @cshake{128,256}_init@ --- *
 181  *
 182  * Arguments:   @shake_ctx *ctx@ = pointer to context to initialize
 183  *              @const void *func@ = NIST-allocated function name
 184  *              @size_t fsz@ = length of function name
 185  *              @const void *perso@ = user personalization string
 186  *              @size_t psz@ = length of personalization string
 187  *
 188  * Returns:     ---
 189  *
 190  * Use:         Initializes a cSHAKE context.  The context is initially in
 191  *              the `absorbing' state: feed it data with @shake_hash@.
 192  */
 193
 194 extern void cshake128_init(shake_ctx */*ctx*/,
 195                            const void */*func*/, size_t /*fsz*/,
 196                            const void */*perso*/, size_t /*psz*/);
 197
 198 extern void cshake256_init(shake_ctx */*ctx*/,
 199                            const void */*func*/, size_t /*fsz*/,
 200                            const void */*perso*/, size_t /*psz*/);
 201
 202 /* --- @shake{128,256}_init@ --- *
 203  *
 204  * Arguments:   @sha3_ctx *ctx@ = pointer to context to initialize
 205  *
 206  * Returns:     ---
 207  *
 208  * Use:         Initializes a SHAKE context.  The context is initially in
 209  *              the `absorbing' state: feed it data with @shake_hash@.
 210  */
 211
 212 extern void shake128_init(shake_ctx */*ctx*/);
 213 extern void shake256_init(shake_ctx */*ctx*/);
 214
 215 /* --- @shake_hash@ --- *
 216  *
 217  * Arguments:   @shake_ctx *ctx@ = context to update
 218  *              @const void *p@ = input buffer
 219  *              @size_t sz@ = size of input
 220  *
 221  * Returns:     ---
 222  *
 223  * Use:         Feeds input data into a SHAKE context.  The context must be
 224  *              in `absorbing' state.
 225  */
 226
 227 extern void shake_hash(shake_ctx */*ctx*/, const void */*p*/, size_t /*sz*/);
 228
 229 /* --- @shake_xof@ --- *
 230  *
 231  * Arguments:   @shake_ctx *ctx@ = context to update
 232  *
 233  * Returns:     ---
 234  *
 235  * Use:         Switches the context into `squeezing' state.  Use @shake_get@
 236  *              or @shake_mask@ to extract data.
 237  */
 238
 239 extern void shake_xof(shake_ctx */*ctx*/);
 240
 241 /* --- @shake_get@ --- *
 242  *
 243  * Arguments:   @shake_ctx *ctx@ = context to update
 244  *              @void *p@ = output buffer
 245  *              @size_t sz@ = size of output
 246  *
 247  * Returns:     ---
 248  *
 249  * Use:         Extracts output from a SHAKE context.  The context must be
 250  *              in `squeezing' state.
 251  */
 252
 253 extern void shake_get(shake_ctx */*ctx*/, void */*p*/, size_t /*sz*/);
 254
 255 /* --- @shake_done@ --- *
 256  *
 257  * Arguments:   @shake_ctx *ctx@ = context to update
 258  *              @void *h@ = where to write the hash
 259  *              @size_t hsz@ = size of the hash to make
 260  *
 261  * Returns:     ---
 262  *
 263  * Use:         Switches the context into `squeezing' state.  Use @shake_get@
 264  *              or @shake_mask@ to extract data.
 265  */
 266
 267 extern void shake_done(shake_ctx */*ctx*/, void */*h*/, size_t /*hsz*/);
 268
 269 /*----- That's all, folks -------------------------------------------------*/
 270
 271 #ifdef __cplusplus
 272   }
 273 #endif
 274
 275 #endif