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

   1 /* -*-c-*-
   2  *
   3  * Arithmetic in the Goldilocks field GF(2^448 - 2^224 - 1)
   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_FGOLDI_H
  48 #define CATACOMB_FGOLDI_H
  49
  50 #ifdef __cplusplus
  51   extern "C" {
  52 #endif
  53
  54 /*----- Header files ------------------------------------------------------*/
  55
  56 #include "fake-mLib-bits.h"
  57
  58 #ifndef CATACOMB_QFARITH_H
  59 #  include "qfarith.h"
  60 #endif
  61
  62 /*----- Data structures ---------------------------------------------------*/
  63
  64 typedef union {
  65   int32 p28[16];
  66 } fgoldi;
  67
  68 /*----- Functions provided ------------------------------------------------*/
  69
  70 /* --- @fgoldi_load@ --- *
  71  *
  72  * Arguments:   @fgoldi *z@ = where to store the result
  73  *              @const octet xv[56]@ = source to read
  74  *
  75  * Returns:     ---
  76  *
  77  * Use:         Reads an element of %$\gf{2^{448} - 2^{224} - 19}$% in
  78  *              external representation from @xv@ and stores it in @z@.
  79  *
  80  *              External representation is little-endian base-256.  Some
  81  *              elements have multiple encodings, which are not produced by
  82  *              correct software; use of noncanonical encodings is not an
  83  *              error, and toleration of them is considered a performance
  84  *              feature.
  85  */
  86
  87 extern void fgoldi_load(fgoldi */*z*/, const octet /*xv*/[56]);
  88
  89 /* --- @fgoldi_store@ --- *
  90  *
  91  * Arguments:   @octet zv[56]@ = where to write the result
  92  *              @const fgoldi *x@ = the field element to write
  93  *
  94  * Returns:     ---
  95  *
  96  * Use:         Stores a field element in the given octet vector in external
  97  *              representation.  A canonical encoding is always stored.
  98  */
  99
 100 extern void fgoldi_store(octet /*zv*/[56], const fgoldi */*x*/);
 101
 102 /* --- @fgoldi_set@ --- *
 103  *
 104  * Arguments:   @fgoldi *z@ = where to write the result
 105  *              @int a@ = a small-ish constant
 106  *
 107  * Returns:     ---
 108  *
 109  * Use:         Sets @z@ to equal @a@.
 110  */
 111
 112 extern void fgoldi_set(fgoldi */*x*/, int /*a*/);
 113
 114 /* --- @fgoldi_add@ --- *
 115  *
 116  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 117  *              @const fgoldi *x, *y@ = two operands
 118  *
 119  * Returns:     ---
 120  *
 121  * Use:         Set @z@ to the sum %$x + y$%.
 122  */
 123
 124 extern void fgoldi_add(fgoldi */*z*/,
 125                        const fgoldi */*x*/, const fgoldi */*y*/);
 126
 127 /* --- @fgoldi_sub@ --- *
 128  *
 129  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 130  *              @const fgoldi *x, *y@ = two operands
 131  *
 132  * Returns:     ---
 133  *
 134  * Use:         Set @z@ to the difference %$x - y$%.
 135  */
 136
 137 extern void fgoldi_sub(fgoldi */*z*/,
 138                        const fgoldi */*x*/, const fgoldi */*y*/);
 139
 140 /* --- @fgoldi_condswap@ --- *
 141  *
 142  * Arguments:   @fgoldi *x, *y@ = two operands
 143  *              @uint32 m@ = a mask
 144  *
 145  * Returns:     ---
 146  *
 147  * Use:         If @m@ is zero, do nothing; if @m@ is all-bits-set, then
 148  *              exchange @x@ and @y@.  If @m@ has some other value, then
 149  *              scramble @x@ and @y@ in an unhelpful way.
 150  */
 151
 152 extern void fgoldi_condswap(fgoldi */*x*/, fgoldi */*y*/, uint32 /*m*/);
 153
 154 /* --- @fgoldi_mulconst@ --- *
 155  *
 156  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@)
 157  *              @const fgoldi *x@ = an operand
 158  *              @long a@ = a small-ish constant; %$|a| < 2^{20}$%.
 159  *
 160  * Returns:     ---
 161  *
 162  * Use:         Set @z@ to the product %$a x$%.
 163  */
 164
 165 extern void fgoldi_mulconst(fgoldi */*z*/, const fgoldi */*x*/, long /*a*/);
 166
 167 /* --- @fgoldi_mul@ --- *
 168  *
 169  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 170  *              @const fgoldi *x, *y@ = two operands
 171  *
 172  * Returns:     ---
 173  *
 174  * Use:         Set @z@ to the product %$x y$%.
 175  */
 176
 177 extern void fgoldi_mul(fgoldi */*z*/,
 178                        const fgoldi */*x*/, const fgoldi */*y*/);
 179
 180 /* --- @fgoldi_sqr@ --- *
 181  *
 182  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 183  *              @const fgoldi *x@ = an operand
 184  *
 185  * Returns:     ---
 186  *
 187  * Use:         Set @z@ to the square %$x^2$%.
 188  */
 189
 190 extern void fgoldi_sqr(fgoldi */*z*/, const fgoldi */*x*/);
 191
 192 /* --- @fgoldi_inv@ --- *
 193  *
 194  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@)
 195  *              @const fgoldi *x@ = an operand
 196  *
 197  * Returns:     ---
 198  *
 199  * Use:         Stores in @z@ the multiplicative inverse %$x^{-1}$%.  If
 200  *              %$x = 0$% then @z@ is set to zero.  This is considered a
 201  *              feature.
 202  */
 203
 204 extern void fgoldi_inv(fgoldi */*z*/, const fgoldi */*x*/);
 205
 206 /*----- That's all, folks -------------------------------------------------*/
 207
 208 #ifdef __cplusplus
 209   }
 210 #endif
 211
 212 #endif