mdw@git.distorted.org.uk Git - 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   typedef int32 fgoldi_piece;
  69
  70 /*----- Functions provided ------------------------------------------------*/
  71
  72 /* --- @fgoldi_load@ --- *
  73  *
  74  * Arguments:   @fgoldi *z@ = where to store the result
  75  *              @const octet xv[56]@ = source to read
  76  *
  77  * Returns:     ---
  78  *
  79  * Use:         Reads an element of %$\gf{2^{448} - 2^{224} - 19}$% in
  80  *              external representation from @xv@ and stores it in @z@.
  81  *
  82  *              External representation is little-endian base-256.  Some
  83  *              elements have multiple encodings, which are not produced by
  84  *              correct software; use of noncanonical encodings is not an
  85  *              error, and toleration of them is considered a performance
  86  *              feature.
  87  */
  88
  89 extern void fgoldi_load(fgoldi */*z*/, const octet /*xv*/[56]);
  90
  91 /* --- @fgoldi_store@ --- *
  92  *
  93  * Arguments:   @octet zv[56]@ = where to write the result
  94  *              @const fgoldi *x@ = the field element to write
  95  *
  96  * Returns:     ---
  97  *
  98  * Use:         Stores a field element in the given octet vector in external
  99  *              representation.  A canonical encoding is always stored.
 100  */
 101
 102 extern void fgoldi_store(octet /*zv*/[56], const fgoldi */*x*/);
 103
 104 /* --- @fgoldi_set@ --- *
 105  *
 106  * Arguments:   @fgoldi *z@ = where to write the result
 107  *              @int a@ = a small-ish constant
 108  *
 109  * Returns:     ---
 110  *
 111  * Use:         Sets @z@ to equal @a@.
 112  */
 113
 114 extern void fgoldi_set(fgoldi */*x*/, int /*a*/);
 115
 116 /* --- @fgoldi_add@ --- *
 117  *
 118  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 119  *              @const fgoldi *x, *y@ = two operands
 120  *
 121  * Returns:     ---
 122  *
 123  * Use:         Set @z@ to the sum %$x + y$%.
 124  */
 125
 126 extern void fgoldi_add(fgoldi */*z*/,
 127                        const fgoldi */*x*/, const fgoldi */*y*/);
 128
 129 /* --- @fgoldi_sub@ --- *
 130  *
 131  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 132  *              @const fgoldi *x, *y@ = two operands
 133  *
 134  * Returns:     ---
 135  *
 136  * Use:         Set @z@ to the difference %$x - y$%.
 137  */
 138
 139 extern void fgoldi_sub(fgoldi */*z*/,
 140                        const fgoldi */*x*/, const fgoldi */*y*/);
 141
 142 /* --- @fgoldi_neg@ --- *
 143  *
 144  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@)
 145  *              @const fgoldi *x@ = an operand
 146  *
 147  * Returns:     ---
 148  *
 149  * Use:         Set @z = -x@.
 150  */
 151
 152 extern void fgoldi_neg(fgoldi */*z*/, const fgoldi */*x*/);
 153
 154 /* --- @fgoldi_pick2@ --- *
 155  *
 156  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 157  *              @const fgoldi *x, *y@ = two operands
 158  *              @uint32 m@ = a mask
 159  *
 160  * Returns:     ---
 161  *
 162  * Use:         If @m@ is zero, set @z = y@; if @m@ is all-bits-set, then set
 163  *              @z = x@.  If @m@ has some other value, then scramble @z@ in
 164  *              an unhelpful way.
 165  */
 166
 167 extern void fgoldi_pick2(fgoldi */*z*/,
 168                          const fgoldi */*x*/, const fgoldi */*y*/,
 169                          uint32 /*m*/);
 170
 171 /* --- @fgoldi_pickn@ --- *
 172  *
 173  * Arguments:   @fgoldi *z@ = where to put the result
 174  *              @const fgoldi *v@ = a table of entries
 175  *              @size_t n@ = the number of entries in @v@
 176  *              @size_t i@ = an index
 177  *
 178  * Returns:     ---
 179  *
 180  * Use:         If @0 <= i < n < 32@ then set @z = v[i]@.  If @n >= 32@ then
 181  *              do something unhelpful; otherwise, if @i >= n@ then set @z@
 182  *              to zero.
 183  */
 184
 185 extern void fgoldi_pickn(fgoldi */*z*/,
 186                          const fgoldi */*v*/, size_t /*n*/, size_t /*i*/);
 187
 188 /* --- @fgoldi_condswap@ --- *
 189  *
 190  * Arguments:   @fgoldi *x, *y@ = two operands
 191  *              @uint32 m@ = a mask
 192  *
 193  * Returns:     ---
 194  *
 195  * Use:         If @m@ is zero, do nothing; if @m@ is all-bits-set, then
 196  *              exchange @x@ and @y@.  If @m@ has some other value, then
 197  *              scramble @x@ and @y@ in an unhelpful way.
 198  */
 199
 200 extern void fgoldi_condswap(fgoldi */*x*/, fgoldi */*y*/, uint32 /*m*/);
 201
 202 /* --- @fgoldi_condneg@ --- *
 203  *
 204  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@)
 205  *              @const fgoldi *x@ = an operand
 206  *              @uint32 m@ = a mask
 207  *
 208  * Returns:     ---
 209  *
 210  * Use:         If @m@ is zero, set @z = x@; if @m@ is all-bits-set, then set
 211  *              @z = -x@.  If @m@ has some other value then scramble @z@ in
 212  *              an unhelpful way.
 213  */
 214
 215 extern void fgoldi_condneg(fgoldi */*z*/, const fgoldi */*x*/, uint32 /*m*/);
 216
 217 /* --- @fgoldi_mulconst@ --- *
 218  *
 219  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@)
 220  *              @const fgoldi *x@ = an operand
 221  *              @long a@ = a small-ish constant; %$|a| < 2^{20}$%.
 222  *
 223  * Returns:     ---
 224  *
 225  * Use:         Set @z@ to the product %$a x$%.
 226  */
 227
 228 extern void fgoldi_mulconst(fgoldi */*z*/, const fgoldi */*x*/, long /*a*/);
 229
 230 /* --- @fgoldi_mul@ --- *
 231  *
 232  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 233  *              @const fgoldi *x, *y@ = two operands
 234  *
 235  * Returns:     ---
 236  *
 237  * Use:         Set @z@ to the product %$x y$%.
 238  */
 239
 240 extern void fgoldi_mul(fgoldi */*z*/,
 241                        const fgoldi */*x*/, const fgoldi */*y*/);
 242
 243 /* --- @fgoldi_sqr@ --- *
 244  *
 245  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 246  *              @const fgoldi *x@ = an operand
 247  *
 248  * Returns:     ---
 249  *
 250  * Use:         Set @z@ to the square %$x^2$%.
 251  */
 252
 253 extern void fgoldi_sqr(fgoldi */*z*/, const fgoldi */*x*/);
 254
 255 /* --- @fgoldi_inv@ --- *
 256  *
 257  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@)
 258  *              @const fgoldi *x@ = an operand
 259  *
 260  * Returns:     ---
 261  *
 262  * Use:         Stores in @z@ the multiplicative inverse %$x^{-1}$%.  If
 263  *              %$x = 0$% then @z@ is set to zero.  This is considered a
 264  *              feature.
 265  */
 266
 267 extern void fgoldi_inv(fgoldi */*z*/, const fgoldi */*x*/);
 268
 269 /* --- @fgoldi_quosqrt@ --- *
 270  *
 271  * Arguments:   @fgoldi *z@ = where to put the result (may alias @x@ or @y@)
 272  *              @const fgoldi *x, *y@ = two operands
 273  *
 274  * Returns:     Zero if successful, @-1@ if %$x/y$% is not a square.
 275  *
 276  * Use:         Stores in @z@ the one of the square roots %$\pm\sqrt{x/y}$%.
 277  *              If %$x = y = 0% then the result is zero; if %$y = 0$% but %$x
 278  *              \ne 0$% then the operation fails.  If you wanted a specific
 279  *              square root then you'll have to pick it yourself.
 280  */
 281
 282 extern int fgoldi_quosqrt(fgoldi */*z*/,
 283                           const fgoldi */*x*/, const fgoldi */*y*/);
 284
 285 /*----- That's all, folks -------------------------------------------------*/
 286
 287 #ifdef __cplusplus
 288   }
 289 #endif
 290
 291 #endif