Falcon source files (reference implementation)


shake.h

    1 /*
    2  * API for SHAKE implementation.
    3  *
    4  * The SHAKE implementation is stand-alone and does not depend on other
    5  * Falcon files. Applications may include this file and use SHAKE
    6  * directly; however, for normal Falcon operations (key generation,
    7  * signature, verification), explicit calls to SHAKE by the application
    8  * are not necessary.
    9  *
   10  * ==========================(LICENSE BEGIN)============================
   11  *
   12  * Copyright (c) 2017  Falcon Project
   13  *
   14  * Permission is hereby granted, free of charge, to any person obtaining
   15  * a copy of this software and associated documentation files (the
   16  * "Software"), to deal in the Software without restriction, including
   17  * without limitation the rights to use, copy, modify, merge, publish,
   18  * distribute, sublicense, and/or sell copies of the Software, and to
   19  * permit persons to whom the Software is furnished to do so, subject to
   20  * the following conditions:
   21  *
   22  * The above copyright notice and this permission notice shall be
   23  * included in all copies or substantial portions of the Software.
   24  *
   25  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   26  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   27  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   28  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   29  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   30  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
   31  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
   32  *
   33  * ===========================(LICENSE END)=============================
   34  *
   35  * @author   Thomas Pornin <thomas.pornin@nccgroup.trust>
   36  */
   37 
   38 #ifndef SHAKE_H__
   39 #define SHAKE_H__
   40 
   41 #include <stddef.h>
   42 #include <stdint.h>
   43 
   44 #ifdef __cplusplus
   45 extern "C" {
   46 #endif
   47 
   48 /* ==================================================================== */
   49 /*
   50  * SHAKE implementation.
   51  *
   52  * The computation uses a caller-provided context structure. Call sequence:
   53  *
   54  *   - Initialise the structure with shake_init(). The "capacity" defines
   55  *     the variant which is used; it must be a multiple of 64, at least 64,
   56  *     at most 1600, but the extreme values don't make much sense.
   57  *     SHAKE128 uses capacity 256; SHAKE256 uses capacity 512.
   58  *
   59  *   - Inject some data with shake_inject(). This can be done with an
   60  *     arbitrary number of calls; each call injects an arbitrary number
   61  *     of bytes.
   62  *
   63  *   - Call shake_flip() to switch to extraction mode.
   64  *
   65  *   - Obtain successive output bytes with shake_extract(). Each call
   66  *     may ask for an arbitrary number of bytes (even zero).
   67  *
   68  * There is no explicit deallocation, since there is no dynamic
   69  * allocation.
   70  *
   71  * Caller is responsible for ensuring that a context is properly
   72  * initialised, that shake_flip() is called, that no call to
   73  * shake_inject() is made after shake_flip (and before the next
   74  * shake_init() on the same structure), and that no call to
   75  * shake_extract() is made before shake_flip().
   76  */
   77 
   78 /*
   79  * SHAKE context. Contents are opaque (don't access them directly).
   80  */
   81 typedef struct {
   82         unsigned char dbuf[200];
   83         size_t dptr;
   84         size_t rate;
   85         uint64_t A[25];
   86 } shake_context;
   87 
   88 /*
   89  * Initialise (or reinitialise) the provided context structure, for a
   90  * given capacity. Capacity is expressed in bits, and is typically
   91  * twice the "bit security level" you are aiming at. In practice,
   92  * use 256 for SHAKE128, 512 for SHAKE256.
   93  */
   94 void shake_init(shake_context *sc, int capacity);
   95 
   96 /*
   97  * Inject some data bytes in the provided SHAKE context (which must have
   98  * been initialised previously with shake_init(), and not yet "flipped").
   99  */
  100 void shake_inject(shake_context *sc, const void *data, size_t len);
  101 
  102 /*
  103  * "Flip" the provided SHAKE context to extraction mode. The context must
  104  * have been previously initialised, and not yet flipped.
  105  */
  106 void shake_flip(shake_context *sc);
  107 
  108 /*
  109  * Extract bytes from a flipped SHAKE context. Several successive calls
  110  * can be made, yielding the next bytes of the conceptually infinite
  111  * output.
  112  */
  113 void shake_extract(shake_context *sc, void *out, size_t len);
  114 
  115 /* ==================================================================== */
  116 
  117 #ifdef __cplusplus
  118 }
  119 #endif
  120 
  121 #endif