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