chiark - git - mdw - catacomb/blob - symm/keccak1600.h

   1 /* -*-c-*-
   2  *
   3  * The Keccak-p[1600, n] permutation
   4  *
   5  * (c) 2017 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Catacomb.
  11  *
  12  * Catacomb is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with Catacomb; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef CATACOMB_KECCAK1600_H
  29 #define CATACOMB_KECCAK1600_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Notes on the Keccak-p[1600, n] permutation ------------------------*
  36  *
  37  * Keccak, by Guido Bertoni, Joan Daemen, Michaël Peeters, and Gilles Van
  38  * Assche, was the winning submission in NIST's competition to design a new
  39  * hash function, and is now the basis of the SHA3 standard.
  40  *
  41  * The cryptographic primitive, Keccak-p[1600, n], is an unkeyed permutation
  42  * on strings of 1600 bits.  It's used in the authors' `sponge construction',
  43  * which splits a 1600-bit state into an `inner part', whose size is known as
  44  * the `capacity', and an `outer part', whose size is known as the `rate'.
  45  * The security of the construction is determined by the capacity, and its
  46  * performance is determined by the rate.
  47  *
  48  * This file just implements the permutation and some accessors for the state
  49  * (which may be represented internally in a strange way, for performance
  50  * reasons).  Many useful things are defined along with SHA3.
  51  */
  52
  53 /*----- Header files ------------------------------------------------------*/
  54
  55 #include <mLib/bits.h>
  56
  57 /*----- Data structures ---------------------------------------------------*/
  58
  59 /* There are two possible internal representations for a lane in the state.
  60  * Which one is in use isn't specified here.  The context simply allows space
  61  * for either.
  62  */
  63 typedef kludge64 keccak1600_lane_64;
  64 typedef struct { uint32 even, odd; } keccak1600_lane_i32;
  65
  66 typedef union keccak1600_state {
  67   keccak1600_lane_64 s64[25];
  68   keccak1600_lane_i32 si32[25];
  69 } keccak1600_state;
  70
  71 /*----- Functions provided ------------------------------------------------*/
  72
  73 /* --- @keccak1600_p@ --- *
  74  *
  75  * Arguments:   @keccak1600_state *z@ = where to write the output state
  76  *              @conts keccak1600_state *x@ = input state
  77  *              @unsigned n@ = number of rounds to perform
  78  *
  79  * Returns:     ---
  80  *
  81  * Use:         Implements the %$\Keccak[1600, n]$% permutation at the core
  82  *              of Keccak and the SHA-3 standard.
  83  */
  84
  85 extern void keccak1600_p(keccak1600_state */*z*/,
  86                          const keccak1600_state */*x*/, unsigned /*n*/);
  87
  88 /* --- @keccack1600_init@ --- *
  89  *
  90  * Arguments:   @keccak1600_state *s@ = a state to initialize
  91  *
  92  * Returns:     ---
  93  *
  94  * Use:         Initialize @s@ to the root state.
  95  */
  96
  97 extern void keccak1600_init(keccak1600_state */*s*/);
  98
  99 /* --- @keccak1600_mix@ --- *
 100  *
 101  * Arguments:   @keccak1600_state *s@ = a state to update
 102  *              @const kludge64 *p@ = pointer to 64-bit words to mix in
 103  *              @size_t n@ = size of the input, in 64-bit words
 104  *
 105  * Returns:     ---
 106  *
 107  * Use:         Mixes data into a %$\Keccak[r, 1600 - r]$% state.  Note that
 108  *              it's the caller's responsibility to pass in no more than
 109  *              %$r$% bits of data.
 110  */
 111
 112 extern void keccak1600_mix(keccak1600_state */*s*/,
 113                            const kludge64 */*p*/, size_t /*n*/);
 114
 115 /* --- @keccak1600_set@ --- *
 116  *
 117  * Arguments:   @keccak1600_state *s@ = a state to update
 118  *              @const kludge64 *p@ = pointer to 64-bit words to mix in
 119  *              @size_t n@ = size of the input, in 64-bit words
 120  *
 121  * Returns:     ---
 122  *
 123  * Use:         Stores data into a %$\Keccak[r, 1600 - r]$% state.  Note that
 124  *              it's the caller's responsibility to pass in no more than
 125  *              %$r$% bits of data.
 126  *
 127  *              This is not the operation you wanted for ordinary hashing.
 128  *              It's provided for the use of higher-level protocols which use
 129  *              duplexing and other fancy sponge features.
 130  */
 131
 132 extern void keccak1600_set(keccak1600_state */*s*/,
 133                            const kludge64 */*p*/, size_t /*n*/);
 134
 135 /* --- @keccak1600_extract@ --- *
 136  *
 137  * Arguments:   @const keccak1600_state *s@ = a state to extract output from
 138  *              @kludge64 *p@ = pointer to 64-bit words to write
 139  *              @size_t n@ = size of the output, in 64-bit words
 140  *
 141  * Returns:     ---
 142  *
 143  * Use:         Reads output from a %$\Keccak[r, 1600 - r]$% state.  Note
 144  *              that it's the caller's responsibility to extract no more than
 145  *              %$r$% bits of data.
 146  */
 147
 148 extern void keccak1600_extract(const keccak1600_state */*s*/,
 149                                kludge64 */*p*/, size_t /*n*/);
 150
 151 /*----- That's all, folks -------------------------------------------------*/
 152
 153 #ifdef __cplusplus
 154   }
 155 #endif
 156
 157 #endif