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