scaf.h

   1 /* -*-c-*-
   2  *
   3  * Simple scalar fields
   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_SCAF_H
  48 #define CATACOMB_SCAF_H
  49
  50 #ifdef __cplusplus
  51   extern "C" {
  52 #endif
  53
  54 /*----- Header files ------------------------------------------------------*/
  55
  56 #include "fake-mLib-bits.h"
  57
  58 /*----- Type selection ----------------------------------------------------*/
  59
  60   typedef uint32 scaf_piece;
  61   typedef uint64 scaf_dblpiece;
  62
  63 #define SCAF_NPIECE(bits, piecewd) (((bits) + piecewd - 1)/piecewd)
  64
  65 /*----- Functions provided -----------------------------------------------*/
  66
  67 /* --- @scaf_load@ --- *
  68  *
  69  * Arguments:   @scaf_piece *z@ = where to write the result
  70  *              @const octet *b@ = source buffer to read
  71  *              @size_t sz@ = size of the source buffer
  72  *              @size_t npiece@ = number of pieces to read
  73  *              @unsigned piecewd@ = nominal width of pieces in bits
  74  *
  75  * Returns:     ---
  76  *
  77  * Use:         Loads a little-endian encoded scalar into a vector @z@ of
  78  *              single-precision pieces.
  79  */
  80
  81 extern void scaf_load(scaf_piece */*z*/, const octet */*b*/, size_t /*sz*/,
  82                       size_t /*npiece*/, unsigned /*piecewd*/);
  83
  84 /* --- @scaf_loaddbl@ --- *
  85  *
  86  * Arguments:   @scaf_dblpiece *z@ = where to write the result
  87  *              @const octet *b@ = source buffer to read
  88  *              @size_t sz@ = size of the source buffer
  89  *              @size_t npiece@ = number of pieces to read
  90  *              @unsigned piecewd@ = nominal width of pieces in bits
  91  *
  92  * Returns:     ---
  93  *
  94  * Use:         Loads a little-endian encoded scalar into a vector @z@ of
  95  *              double-precision pieces.
  96  */
  97
  98 extern void scaf_loaddbl(scaf_dblpiece */*z*/, const octet */*b*/,
  99                          size_t /*sz*/, size_t /*npiece*/,
 100                          unsigned /*piecewd*/);
 101
 102 /* --- @scaf_store@ --- *
 103  *
 104  * Arguments:   @octet *b@ = buffer to fill in
 105  *              @size_t sz@ = size of the buffer
 106  *              @const scaf_piece *x@ = scalar to store
 107  *              @size_t npiece@ = number of pieces in @x@
 108  *              @unsigned piecewd@ = nominal width of pieces in bits
 109  *
 110  * Returns:     ---
 111  *
 112  * Use:         Stores a scalar in a vector of single-precison pieces as a
 113  *              little-endian vector of bytes.
 114  */
 115
 116 extern void scaf_store(octet */*b*/, size_t /*sz*/, const scaf_piece */*x*/,
 117                        size_t /*npiece*/, unsigned /*piecewd*/);
 118
 119 /* --- @scaf_mul@ --- *
 120  *
 121  * Arguments:   @scaf_dblpiece *z@ = where to put the answer
 122  *              @const scaf_piece *x, *y@ = the operands
 123  *              @size_t npiece@ = the length of the operands
 124  *
 125  * Returns:     ---
 126  *
 127  * Use:         Multiply two scalars.  The destination must have space for
 128  *              @2*npiece@ pieces (though the last one will always be zero).
 129  *              The result is not reduced.
 130  */
 131
 132 extern void scaf_mul(scaf_dblpiece */*z*/, const scaf_piece */*x*/,
 133                      const scaf_piece */*y*/, size_t /*npiece*/);
 134
 135 /* --- @scaf_reduce@ --- *
 136  *
 137  * Arguments:   @scaf_piece *z@ = where to write the result
 138  *              @const scaf_dblpiece *x@ = the operand to reduce
 139  *              @const scaf_piece *l@ = the modulus, in internal format
 140  *              @const scaf_piece *mu@ = scaled approximation to @1/l@
 141  *              @size_t npiece@ = number of pieces in @l@
 142  *              @unsigned piecewd@ = nominal width of a piece in bits
 143  *              @scaf_piece *scratch@ = @3*npiece@ scratch pieces
 144  *
 145  * Returns:     ---
 146  *
 147  * Use:         Reduce @x@ (a vector of @2*npiece@ double-precision pieces)
 148  *              modulo @l@ (a vector of @npiece@ single-precision pieces),
 149  *              writing the result to @z@.
 150  *
 151  *              Write @n = npiece@, @w = piecewd@, and %$B = 2^w$%.  The
 152  *              operand @mu@ must contain %$\lfloor B^{2n}/l \rfloor$%, in
 153  *              @npiece + 1@ pieces.  Furthermore, we must have
 154  *              %$3 l < B^n$%.  (Fiddle with %$w$% if necessary.)
 155  */
 156
 157 extern void scaf_reduce(scaf_piece */*z*/, const scaf_dblpiece */*x*/,
 158                         const scaf_piece */*l*/, const scaf_piece */*mu*/,
 159                         size_t /*npiece*/, unsigned /*piecewd*/,
 160                         scaf_piece */*scratch*/);
 161
 162 /*----- That's all, folks -------------------------------------------------*/
 163
 164 #ifdef __cplusplus
 165   }
 166 #endif
 167
 168 #endif