f25519.h

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