chiark - git - mdw - secnet/blob - 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 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_KECCAK1600_H
  48 #define CATACOMB_KECCAK1600_H
  49
  50 #ifdef __cplusplus
  51   extern "C" {
  52 #endif
  53
  54 /*----- Notes on the Keccak-p[1600, n] permutation ------------------------*
  55  *
  56  * Keccak, by Guido Bertoni, Joan Daemen, Michaël Peeters, and Gilles Van
  57  * Assche, was the winning submission in NIST's competition to design a new
  58  * hash function, and is now the basis of the SHA3 standard.
  59  *
  60  * The cryptographic primitive, Keccak-p[1600, n], is an unkeyed permutation
  61  * on strings of 1600 bits.  It's used in the authors' `sponge construction',
  62  * which splits a 1600-bit state into an `inner part', whose size is known as
  63  * the `capacity', and an `outer part', whose size is known as the `rate'.
  64  * The security of the construction is determined by the capacity, and its
  65  * performance is determined by the rate.
  66  *
  67  * This file just implements the permutation and some accessors for the state
  68  * (which may be represented internally in a strange way, for performance
  69  * reasons).  Many useful things are defined along with SHA3.
  70  */
  71
  72 /*----- Header files ------------------------------------------------------*/
  73
  74 #include "fake-mLib-bits.h"
  75
  76 /*----- Data structures ---------------------------------------------------*/
  77
  78 /* There are two possible internal representations for a lane in the state.
  79  * Which one is in use isn't specified here.  The context simply allows space
  80  * for either.
  81  */
  82 typedef kludge64 keccak1600_lane_64;
  83 typedef struct { uint32 even, odd; } keccak1600_lane_i32;
  84
  85 typedef union keccak1600_state {
  86   keccak1600_lane_64 s64[25];
  87   keccak1600_lane_i32 si32[25];
  88 } keccak1600_state;
  89
  90 /*----- Functions provided ------------------------------------------------*/
  91
  92 /* --- @keccak1600_p@ --- *
  93  *
  94  * Arguments:   @keccak1600_state *z@ = where to write the output state
  95  *              @conts keccak1600_state *x@ = input state
  96  *              @unsigned n@ = number of rounds to perform
  97  *
  98  * Returns:     ---
  99  *
 100  * Use:         Implements the %$\Keccak[1600, n]$% permutation at the core
 101  *              of Keccak and the SHA-3 standard.
 102  */
 103
 104 extern void keccak1600_p(keccak1600_state */*z*/,
 105                          const keccak1600_state */*x*/, unsigned /*n*/);
 106
 107 /* --- @keccack1600_init@ --- *
 108  *
 109  * Arguments:   @keccak1600_state *s@ = a state to initialize
 110  *
 111  * Returns:     ---
 112  *
 113  * Use:         Initialize @s@ to the root state.
 114  */
 115
 116 extern void keccak1600_init(keccak1600_state */*s*/);
 117
 118 /* --- @keccak1600_mix@ --- *
 119  *
 120  * Arguments:   @keccak1600_state *s@ = a state to update
 121  *              @const kludge64 *p@ = pointer to 64-bit words to mix in
 122  *              @size_t n@ = size of the input, in 64-bit words
 123  *
 124  * Returns:     ---
 125  *
 126  * Use:         Mixes data into a %$\Keccak[r, 1600 - r]$% state.  Note that
 127  *              it's the caller's responsibility to pass in no more than
 128  *              %$r$% bits of data.
 129  */
 130
 131 extern void keccak1600_mix(keccak1600_state */*s*/,
 132                            const kludge64 */*p*/, size_t /*n*/);
 133
 134 /* --- @keccak1600_extract@ --- *
 135  *
 136  * Arguments:   @const keccak1600_state *s@ = a state to extract output from
 137  *              @kludge64 *p@ = pointer to 64-bit words to write
 138  *              @size_t n@ = size of the output, in 64-bit words
 139  *
 140  * Returns:     ---
 141  *
 142  * Use:         Reads output from a %$\Keccak[r, 1600 - r]$% state.  Note
 143  *              that it's the caller's responsibility to extract no more than
 144  *              %$r$% bits of data.
 145  */
 146
 147 extern void keccak1600_extract(const keccak1600_state */*s*/,
 148                                kludge64 */*p*/, size_t /*n*/);
 149
 150 /*----- That's all, folks -------------------------------------------------*/
 151
 152 #ifdef __cplusplus
 153   }
 154 #endif
 155
 156 #endif