Falcon source files (reference implementation)


falcon.h

    1 /*
    2  * External Falcon API.
    3  *
    4  * ==========================(LICENSE BEGIN)============================
    5  *
    6  * Copyright (c) 2017-2019  Falcon Project
    7  *
    8  * Permission is hereby granted, free of charge, to any person obtaining
    9  * a copy of this software and associated documentation files (the
   10  * "Software"), to deal in the Software without restriction, including
   11  * without limitation the rights to use, copy, modify, merge, publish,
   12  * distribute, sublicense, and/or sell copies of the Software, and to
   13  * permit persons to whom the Software is furnished to do so, subject to
   14  * the following conditions:
   15  *
   16  * The above copyright notice and this permission notice shall be
   17  * included in all copies or substantial portions of the Software.
   18  *
   19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   20  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   22  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   23  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   24  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
   25  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
   26  *
   27  * ===========================(LICENSE END)=============================
   28  *
   29  * @author   Thomas Pornin <thomas.pornin@nccgroup.com>
   30  */
   31 
   32 #ifndef FALCON_H__
   33 #define FALCON_H__
   34 
   35 #include <stddef.h>
   36 #include <stdint.h>
   37 
   38 #ifdef __cplusplus
   39 extern "C" {
   40 #endif
   41 
   42 /* ==================================================================== */
   43 /*
   44  * Falcon API Notes
   45  * ----------------
   46  *
   47  *
   48  * FALCON DEGREE
   49  *
   50  * Falcon is parameterized by a degree, which is a power of two. Formally,
   51  * two values are possible: 512 and 1024 (for Falcon-512 and Falcon-1024,
   52  * respectively). This implementation also supports lower degrees, from
   53  * 2 to 256; these reduced variants do not provide adequate security and
   54  * should be used for research purposes only.
   55  *
   56  * In all functions and macros defined below, the degree is provided
   57  * logarithmically as the 'logn' parameter: logn ranges from 1 to 10,
   58  * and represents the degree 2^logn.
   59  *
   60  *
   61  * ERROR REPORTING
   62  *
   63  * All functions that may fail for some reason return an 'int' value. A
   64  * returned value of zero is a success; all error conditions are
   65  * reported as an error code. Error codes are negative. Macros are
   66  * defined for some error codes; in the interest of forward
   67  * compatiblity, applications that use this implementation should be
   68  * prepared to receive other error codes not listed in the macros below.
   69  *
   70  *
   71  * TEMPORARY BUFFERS
   72  *
   73  * Many functions expect temporary areas, provided as the parameter
   74  * 'tmp'. The caller is responsible for allocating these areas with the
   75  * proper size; the FALCON_TMPSIZE_* macros evaluate to constant
   76  * expressions that yield the proper size (in bytes) and can be used to
   77  * allocate the temporaries on the stack or elsewhere. There are no
   78  * alignment requirements on temporaries (the functions handle alignment
   79  * internally).
   80  *
   81  * The caller is responsible for clearing temporary buffer contents,
   82  * if such memory scrubbing is deemed relevant in the context where this
   83  * implementation is used.
   84  *
   85  * The same temporary buffer can be reused for several operations,
   86  * possibly distinct from each other. For all degrees from 8 to 1024
   87  * (logn = 3 to 10), the following sizes are in ascending order:
   88  *
   89  *    FALCON_TMPSIZE_MAKEPUB
   90  *    FALCON_TMPSIZE_VERIFY
   91  *    FALCON_TMPSIZE_KEYGEN
   92  *    FALCON_TMPSIZE_SIGNTREE
   93  *    FALCON_TMPSIZE_EXPANDPRIV
   94  *    FALCON_TMPSIZE_SIGNDYN
   95  *
   96  * i.e. a temporary buffer large enough for computing signatures with
   97  * an expanded key ("SIGNTREE") will also be large enough for a
   98  * key pair generation ("KEYGEN"). For logn = 1 or 2, the same order
   99  * holds, except that the KEYGEN buffer is larger.
  100  *
  101  * Here are the actual values for the temporary buffer sizes (in bytes):
  102  *
  103  * degree  mkpub  verify  keygen  signtree  expkey  signdyn
  104  *     2      13      17     285       107     111      163
  105  *     4      25      33     291       207     215      319
  106  *     8      49      65     303       407     423      631
  107  *    16      97     129     503       807     839     1255
  108  *    32     193     257     999      1607    1671     2503
  109  *    64     385     513    1991      3207    3335     4999
  110  *   128     769    1025    3975      6407    6663     9991
  111  *   256    1537    2049    7943     12807   13319    19975
  112  *   512    3073    4097   15879     25607   26631    39943
  113  *  1024    6145    8193   31751     51207   53255    79879
  114  *
  115  * Take care that the "expkey" column here qualifies the temporary buffer
  116  * for the key expansion process, but NOT the expanded key itself (which
  117  * has size FALCON_EXPANDEDKEY_SIZE(logn) and is larger than that).
  118  *
  119  *
  120  * FORMATS
  121  *
  122  * Public and private keys are exchanged as serialized sequences of
  123  * bytes. Their respective sizes are fixed (for a given degree) and the
  124  * FALCON_PRIVKEY_SIZE and FALCON_PUBKEY_SIZE macros return that value
  125  * as constant expressions.
  126  *
  127  * There are two formats for signatures. One has a fixed size (given by
  128  * FALCON_SIG_CT_SIZE) and is produced when falcon_sign_dyn() or
  129  * falcon_sign_tree() is called with the 'ct' parameter equal to 1. The
  130  * other has a variable size, whose theoretical maximum is given by
  131  * FALCON_SIG_VARTIME_MAXSIZE (which is always smaller than
  132  * FALCON_SIG_CT_SIZE), but that maximum is not reached in practice;
  133  * the variable-size signature is produced when the 'ct' parameter is 0.
  134  *
  135  * Actual signature size has been measured over 10000 signatures for each
  136  * degree (100 random keys, 100 signatures per key):
  137  *
  138  * degree     ct    v_max    v_real (with std. deviation)
  139  *     2      44      44         44.00 (+/- 0.00)
  140  *     4      47      47         46.03 (+/- 0.17)
  141  *     8      52      52         50.97 (+/- 0.26)
  142  *    16      65      64         60.45 (+/- 0.52)
  143  *    32      89      86         79.53 (+/- 0.68)
  144  *    64     137     130        117.69 (+/- 0.94)
  145  *   128     233     219        193.96 (+/- 1.30)
  146  *   256     425     397        346.53 (+/- 1.84)
  147  *   512     809     752        651.59 (+/- 2.55)
  148  *  1024    1577    1462       1261.06 (+/- 3.57)
  149  *
  150  * with:
  151  *   degree = Falcon degree = 2^logn
  152  *   ct = FALCON_SIG_CT_SIZE(logn)
  153  *   v_max = FALCON_SIG_VARTIME_MAXSIZE(logn)
  154  *   v_real = measured average length of non-ct signature
  155  * All lengths are in bytes.
  156  *
  157  * Note that these lengths, contrary to the values reported in the Falcon
  158  * specification, include the 40-byte per-signature random nonce.
  159  *
  160  * A private key, in its encoded format, can be used as parameter to
  161  * falcon_sign_dyn(). An "expanded private key" is computed with
  162  * falcon_expand_privkey(), to be used with falcon_sign_tree(). The
  163  * expanded private key is much larger than the encoded private key, and
  164  * its format is not portable. Its size (in bytes) is provided by
  165  * FALCON_EXPANDEDKEY_SIZE. There are no specific alignment requirements
  166  * on expanded keys, except that the alignment of a given expanded key
  167  * must not change (i.e. if an expanded key is moved from address addr1
  168  * to address addr2, then it must hold that addr1 = addr2 mod 8).
  169  * Expanded private keys are meant to be used when several signatures are
  170  * to be computed with the same private key: amortized cost per signature
  171  * is about halved when using expanded private keys (for short messages,
  172  * and depending on underlying architecture and implementation choices).
  173  *
  174  *
  175  * USE OF SHAKE256
  176  *
  177  * SHAKE256 is used in two places:
  178  *
  179  *  - As a PRNG: all functions that require randomness (key pair
  180  *    generation, signature generation) receive as parameter a SHAKE256
  181  *    object, in output mode, from which pseudorandom data is obtained.
  182  *
  183  *    A SHAKE256 instance, to be used as a RNG, can be initialized
  184  *    from an explicit 48-byte seed, or from an OS-provided RNG. Using
  185  *    an explicit seed is meant for reproducibility of test vectors,
  186  *    or to be used in cases where no OS-provided RNG is available and
  187  *    supported.
  188  *
  189  *  - As the hashing mechanism for the message which should be signed.
  190  *    The streamed signature API exposes that SHAKE256 object, since
  191  *    the caller then performs the hashing externally.
  192  */
  193 
  194 /* ==================================================================== */
  195 /*
  196  * Error codes.
  197  *
  198  * Most functions in this API that may fail for some reason return an
  199  * 'int' value which will be 0 on success, or a negative error code.
  200  * The macros below define the error codes. In the interest of forward
  201  * compatibility, callers should be prepared to receive additional error
  202  * codes not included in the list below.
  203  */
  204 
  205 /*
  206  * FALCON_ERR_RANDOM is returned when the library tries to use an
  207  * OS-provided RNG, but either none is supported, or that RNG fails.
  208  */
  209 #define FALCON_ERR_RANDOM     -1
  210 
  211 /*
  212  * FALCON_ERR_SIZE is returned when a buffer has been provided to
  213  * the library but is too small to receive the intended value.
  214  */
  215 #define FALCON_ERR_SIZE       -2
  216 
  217 /*
  218  * FALCON_ERR_FORMAT is returned when decoding of an external object
  219  * (public key, private key, signature) fails.
  220  */
  221 #define FALCON_ERR_FORMAT     -3
  222 
  223 /*
  224  * FALCON_ERR_BADSIG is returned when verifying a signature, the signature
  225  * is validly encoded, but its value does not match the provided message
  226  * and public key.
  227  */
  228 #define FALCON_ERR_BADSIG     -4
  229 
  230 /*
  231  * FALCON_ERR_BADARG is returned when a provided parameter is not in
  232  * a valid range.
  233  */
  234 #define FALCON_ERR_BADARG     -5
  235 
  236 /*
  237  * FALCON_ERR_INTERNAL is returned when some internal computation failed.
  238  */
  239 #define FALCON_ERR_INTERNAL   -6
  240 
  241 /* ==================================================================== */
  242 /*
  243  * Sizes.
  244  *
  245  * The sizes are expressed in bytes. Each size depends on the Falcon
  246  * degree, which is provided logarithmically: use logn=9 for Falcon-512,
  247  * logn=10 for Falcon-1024. Valid values for logn range from 1 to 10
  248  * (values 1 to 8 correspond to reduced variants of Falcon that do not
  249  * provided adequate security and are meant for research purposes only).
  250  *
  251  * The sizes are provided as macros that evaluate to constant
  252  * expressions, as long as the 'logn' parameter is itself a constant
  253  * expression. Moreover, all sizes are monotonic (for each size category,
  254  * increasing logn cannot result in a shorter length).
  255  *
  256  * Note: each macro may evaluate its argument 'logn' several times.
  257  */
  258 
  259 /*
  260  * Private key size (in bytes). The size is exact.
  261  */
  262 #define FALCON_PRIVKEY_SIZE(logn) \
  263         (((logn) <= 3 \
  264                 ? (3u << (logn)) \
  265                 : ((10u - ((logn) >> 1)) << ((logn) - 2)) + (1 << (logn))) \
  266         + 1)
  267 
  268 /*
  269  * Public key size (in bytes). The size is exact.
  270  */
  271 #define FALCON_PUBKEY_SIZE(logn) \
  272         (((logn) <= 1 \
  273                 ? 4u \
  274                 : (7u << ((logn) - 2))) \
  275         + 1)
  276 
  277 /*
  278  * Signature size (in bytes) when using constant-time encoding (when the
  279  * the "ct" parameter of falcon_sign_dyn() or falcon_sign_tree() has
  280  * non-zero value). The size is exact.
  281  */
  282 #define FALCON_SIG_CT_SIZE(logn) \
  283         ((3u << ((logn) - 1)) - ((logn) == 3) + 41)
  284 
  285 /*
  286  * Maximum signature size (in bytes) when using the compressed, non
  287  * constant-time encoding (when the "ct" parameter of
  288  * falcon_sign_generate() has zero value). In practice, the signature
  289  * will be shorter.
  290  */
  291 #define FALCON_SIG_VARTIME_MAXSIZE(logn) \
  292         (((((11u << (logn)) + (101u >> (10 - (logn)))) \
  293         + 7) >> 3) + 41)
  294 
  295 /*
  296  * Temporary buffer size for key pair generation.
  297  */
  298 #define FALCON_TMPSIZE_KEYGEN(logn) \
  299         (((logn) <= 3 ? 272u : (28u << (logn))) + (3u << (logn)) + 7)
  300 
  301 /*
  302  * Temporary buffer size for computing the pubic key from the private key.
  303  */
  304 #define FALCON_TMPSIZE_MAKEPUB(logn) \
  305         ((6u << (logn)) + 1)
  306 
  307 /*
  308  * Temporary buffer size for generating a signature ("dynamic" variant).
  309  */
  310 #define FALCON_TMPSIZE_SIGNDYN(logn) \
  311         ((78u << (logn)) + 7)
  312 
  313 /*
  314  * Temporary buffer size for generating a signature ("tree" variant, with
  315  * an expanded key).
  316  */
  317 #define FALCON_TMPSIZE_SIGNTREE(logn) \
  318         ((50u << (logn)) + 7)
  319 
  320 /*
  321  * Temporary buffer size for expanding a private key.
  322  */
  323 #define FALCON_TMPSIZE_EXPANDPRIV(logn) \
  324         ((52u << (logn)) + 7)
  325 
  326 /*
  327  * Size of an expanded private key.
  328  */
  329 #define FALCON_EXPANDEDKEY_SIZE(logn) \
  330         (((8u * (logn) + 40) << (logn)) + 8)
  331 
  332 /*
  333  * Temporary buffer size for verifying a signature.
  334  */
  335 #define FALCON_TMPSIZE_VERIFY(logn) \
  336         ((8u << (logn)) + 1)
  337 
  338 /* ==================================================================== */
  339 /*
  340  * SHAKE256.
  341  */
  342 
  343 /*
  344  * Context for a SHAKE256 computation. Contents are opaque.
  345  * Contents are pure data with no pointer; they need not be released
  346  * explicitly and don't reference any other allocated resource. The
  347  * caller is responsible for allocating the context structure itself,
  348  * typically on the stack.
  349  */
  350 typedef struct {
  351         uint64_t opaque_contents[26];
  352 } shake256_context;
  353 
  354 /*
  355  * Initialize a SHAKE256 context to its initial state. The state is
  356  * then ready to receive data (with shake256_inject()).
  357  */
  358 void shake256_init(shake256_context *sc);
  359 
  360 /*
  361  * Inject some data bytes into the SHAKE256 context ("absorb" operation).
  362  * This function can be called several times, to inject several chunks
  363  * of data of arbitrary length.
  364  */
  365 void shake256_inject(shake256_context *sc, const void *data, size_t len);
  366 
  367 /*
  368  * Flip the SHAKE256 state to output mode. After this call, shake256_inject()
  369  * can no longer be called on the context, but shake256_extract() can be
  370  * called.
  371  *
  372  * Flipping is one-way; a given context can be converted back to input
  373  * mode only by initializing it again, which forgets all previously
  374  * injected data.
  375  */
  376 void shake256_flip(shake256_context *sc);
  377 
  378 /*
  379  * Extract bytes from the SHAKE256 context ("squeeze" operation). The
  380  * context must have been flipped to output mode (with shake256_flip()).
  381  * Arbitrary amounts of data can be extracted, in one or several calls
  382  * to this function.
  383  */
  384 void shake256_extract(shake256_context *sc, void *out, size_t len);
  385 
  386 /*
  387  * Initialize a SHAKE256 context as a PRNG from the provided seed.
  388  * This initializes the context, injects the seed, then flips the context
  389  * to output mode to make it ready to produce bytes.
  390  */
  391 void shake256_init_prng_from_seed(shake256_context *sc,
  392         const void *seed, size_t seed_len);
  393 
  394 /*
  395  * Initialize a SHAKE256 context as a PRNG, using an initial seed from
  396  * the OS-provided RNG. If there is no known/supported OS-provided RNG,
  397  * or if that RNG fails, then the context is not properly initialized
  398  * and FALCON_ERR_RANDOM is returned.
  399  *
  400  * Returned value: 0 on success, or a negative error code.
  401  */
  402 int shake256_init_prng_from_system(shake256_context *sc);
  403 
  404 /* ==================================================================== */
  405 /*
  406  * Key pair generation.
  407  */
  408 
  409 /*
  410  * Generate a new keypair.
  411  *
  412  * The logarithm of the Falcon degree (logn) must be in the 1 to 10
  413  * range; values 1 to 8 correspond to reduced versions of Falcon that do
  414  * not provide adequate security and are meant for research purposes
  415  * only.
  416  *
  417  * The source of randomness is the provided SHAKE256 context *rng, which
  418  * must have been already initialized, seeded, and set to output mode (see
  419  * shake256_init_prng_from_seed() and shake256_init_prng_from_system()).
  420  *
  421  * The new private key is written in the buffer pointed to by privkey.
  422  * The size of that buffer must be specified in privkey_len; if that
  423  * size is too low, then this function fails with FALCON_ERR_SIZE. The
  424  * actual private key length can be obtained from the FALCON_PRIVKEY_SIZE()
  425  * macro.
  426  *
  427  * If pubkey is not NULL, then the new public key is written in the buffer
  428  * pointed to by pubkey. The size of that buffer must be specified in
  429  * pubkey_len; if that size is too low, then this function fails with
  430  * FALCON_ERR_SIZE. The actual public key length can be obtained from the
  431  * FALCON_PUBKEY_SIZE() macro.
  432  *
  433  * If pubkey is NULL then pubkey_len is ignored; the private key will
  434  * still be generated and written to privkey[], but the public key
  435  * won't be written anywhere. The public key can be later on recomputed
  436  * from the private key with falcon_make_public().
  437  *
  438  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  439  * MUST be at least FALCON_TMPSIZE_KEYGEN(logn) bytes.
  440  *
  441  * Returned value: 0 on success, or a negative error code.
  442  */
  443 int falcon_keygen_make(
  444         shake256_context *rng,
  445         unsigned logn,
  446         void *privkey, size_t privkey_len,
  447         void *pubkey, size_t pubkey_len,
  448         void *tmp, size_t tmp_len);
  449 
  450 /*
  451  * Recompute the public key from the private key.
  452  *
  453  * The private key is provided encoded. This function decodes the
  454  * private key and verifies that its length (in bytes) is exactly
  455  * the provided value privkey_len (trailing extra bytes are not
  456  * tolerated).
  457  *
  458  * The public key is written in the buffer pointed to by pubkey. The
  459  * size (in bytes) of the pubkey buffer must be provided in pubkey_len;
  460  * if it is too short for the public key, then FALCON_ERR_SIZE is
  461  * returned. The actual public key size can be obtained from the
  462  * FALCON_PUBKEY_SIZE() macro.
  463  *
  464  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  465  * MUST be at least FALCON_TMPSIZE_MAKEPUB(logn) bytes.
  466  *
  467  * Returned value: 0 on success, or a negative error code.
  468  */
  469 int falcon_make_public(
  470         void *pubkey, size_t pubkey_len,
  471         const void *privkey, size_t privkey_len,
  472         void *tmp, size_t tmp_len);
  473 
  474 /*
  475  * Get the Falcon degree from an encoded private key, public key or
  476  * signature. Returned value is the logarithm of the degree (1 to 10),
  477  * or a negative error code.
  478  */
  479 int falcon_get_logn(void *obj, size_t len);
  480 
  481 /* ==================================================================== */
  482 /*
  483  * Signature generation.
  484  */
  485 
  486 /*
  487  * Sign the data provided in buffer data[] (of length data_len bytes),
  488  * using the private key held in privkey[] (of length privkey_len bytes).
  489  *
  490  * The source of randomness is the provided SHAKE256 context *rng, which
  491  * must have been already initialized, seeded, and set to output mode (see
  492  * shake256_init_prng_from_seed() and shake256_init_prng_from_system()).
  493  *
  494  * The signature is written in sig[]. The caller must set *sig_len to
  495  * the maximum size of sig[]; if the signature computation is
  496  * successful, then *sig_len will be set to the actual length of the
  497  * signature. If ct is zero, then the maximum signature length is
  498  * FALCON_SIG_VARTIME_MAXSIZE(logn) (where 'logn' qualifies the Falcon
  499  * degree encoded in the private key and can be obtained with
  500  * falcon_get_logn()). If ct is non-zero, then the signature length will
  501  * be exactl FALCON_SIG_CT_SIZE(logn) bytes.
  502  *
  503  * Regardless of 'ct', the process is constant-time with regards to the
  504  * private key. When ct != 0, it is also constant-time with regards to
  505  * the signature value and the message data, i.e. no information on the
  506  * signature and the message may be inferred from timing-related side
  507  * channels.
  508  *
  509  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  510  * MUST be at least FALCON_TMPSIZE_SIGNDYN(logn) bytes.
  511  *
  512  * Returned value: 0 on success, or a negative error code.
  513  */
  514 int falcon_sign_dyn(shake256_context *rng,
  515         void *sig, size_t *sig_len,
  516         const void *privkey, size_t privkey_len,
  517         const void *data, size_t data_len,
  518         int ct, void *tmp, size_t tmp_len);
  519 
  520 /*
  521  * Expand a private key. The provided Falcon private key (privkey, of
  522  * size privkey_len bytes) is decoded and expanded into expanded_key[].
  523  *
  524  * The expanded_key[] buffer has size expanded_key_len, which MUST be at
  525  * least FALCON_EXPANDEDKEY_SIZE(logn) bytes (where 'logn' qualifies the
  526  * Falcon degree encoded in the private key and can be obtained with
  527  * falcon_get_logn()). Expanded key contents have an internal,
  528  * implementation-specific format. Expanded keys may be moved in RAM
  529  * only if their 8-byte alignment remains unchanged.
  530  *
  531  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  532  * MUST be at least FALCON_TMPSIZE_EXPANDPRIV(logn) bytes.
  533  *
  534  * Returned value: 0 on success, or a negative error code.
  535  */
  536 int falcon_expand_privkey(void *expanded_key, size_t expanded_key_len,
  537         const void *privkey, size_t privkey_len,
  538         void *tmp, size_t tmp_len);
  539 
  540 /*
  541  * Sign the data provided in buffer data[] (of length data_len bytes),
  542  * using the expanded private key held in expanded_key[], as generated
  543  * by falcon_expand_privkey().
  544  *
  545  * The source of randomness is the provided SHAKE256 context *rng, which
  546  * must have been already initialized, seeded, and set to output mode (see
  547  * shake256_init_prng_from_seed() and shake256_init_prng_from_system()).
  548  *
  549  * The signature is written in sig[]. The caller must set *sig_len to
  550  * the maximum size of sig[]; if the signature computation is
  551  * successful, then *sig_len will be set to the actual length of the
  552  * signature. If ct is zero, then the maximum signature length is
  553  * FALCON_SIG_VARTIME_MAXSIZE(logn) (where 'logn' qualifies the Falcon
  554  * degree encoded in the private key and can be obtained with
  555  * falcon_get_logn()). If ct is non-zero, then the signature length will
  556  * be exactl FALCON_SIG_CT_SIZE(logn) bytes.
  557  *
  558  * Regardless of 'ct', the process is constant-time with regards to the
  559  * private key. When ct != 0, it is also constant-time with regards to
  560  * the signature value and the message data, i.e. no information on the
  561  * signature and the message may be inferred from timing-related side
  562  * channels.
  563  *
  564  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  565  * MUST be at least FALCON_TMPSIZE_SIGNTREE(logn) bytes.
  566  *
  567  * Returned value: 0 on success, or a negative error code.
  568  */
  569 int falcon_sign_tree(shake256_context *rng,
  570         void *sig, size_t *sig_len,
  571         const void *expanded_key,
  572         const void *data, size_t data_len,
  573         int ct, void *tmp, size_t tmp_len);
  574 
  575 /* ==================================================================== */
  576 /*
  577  * Signature generation, streamed API.
  578  *
  579  * In the streamed API, the caller performs the data hashing externally.
  580  * An initialization function (falcon_sign_start()) is first called; it
  581  * generates and returns a random 40-byte nonce value; it also initializes
  582  * a SHAKE256 context and injects the nonce value in that context. The
  583  * caller must then inject the data to sign in the SHAKE256 context, and
  584  * finally call falcon_sign_dyn_finish() or falcon_sign_tree_finish() to
  585  * finalize the signature generation.
  586  */
  587 
  588 /*
  589  * Start a signature generation context.
  590  *
  591  * A 40-byte nonce is generated and written in nonce[]. The *hash_data
  592  * context is also initialized, and the nonce is injected in that context.
  593  *
  594  * The source of randomness is the provided SHAKE256 context *rng, which
  595  * must have been already initialized, seeded, and set to output mode (see
  596  * shake256_init_prng_from_seed() and shake256_init_prng_from_system()).
  597  *
  598  * Returned value: 0 on success, or a negative error code.
  599  */
  600 int falcon_sign_start(shake256_context *rng,
  601         void *nonce,
  602         shake256_context *hash_data);
  603 
  604 /*
  605  * Finish a signature generation operation, using the private key held
  606  * in privkey[] (of length privkey_len bytes). The hashed nonce + message
  607  * is provided as the SHAKE256 context *hash_data, which must still be
  608  * in input mode (i.e. not yet flipped to output mode). That context is
  609  * modified in the process.
  610  *
  611  * The nonce value (which was used at the start of the hashing process,
  612  * usually as part of a falcon_sign_start() call) must be provided again,
  613  * because it is encoded into the signature. The nonce length is 40 bytes.
  614  *
  615  * The source of randomness is the provided SHAKE256 context *rng, which
  616  * must have been already initialized, seeded, and set to output mode (see
  617  * shake256_init_prng_from_seed() and shake256_init_prng_from_system()).
  618  *
  619  * The signature is written in sig[]. The caller must set *sig_len to
  620  * the maximum size of sig[]; if the signature computation is
  621  * successful, then *sig_len will be set to the actual length of the
  622  * signature. If ct is zero, then the maximum signature length is
  623  * FALCON_SIG_VARTIME_MAXSIZE(logn) (where 'logn' qualifies the Falcon
  624  * degree encoded in the private key and can be obtained with
  625  * falcon_get_logn()). If ct is non-zero, then the signature length will
  626  * be exactl FALCON_SIG_CT_SIZE(logn) bytes.
  627  *
  628  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  629  * MUST be at least FALCON_TMPSIZE_SIGNDYN(logn) bytes.
  630  *
  631  * Returned value: 0 on success, or a negative error code.
  632  */
  633 int falcon_sign_dyn_finish(shake256_context *rng,
  634         void *sig, size_t *sig_len,
  635         const void *privkey, size_t privkey_len,
  636         shake256_context *hash_data, const void *nonce,
  637         int ct, void *tmp, size_t tmp_len);
  638 
  639 /*
  640  * Finish a signature generation operation, using the expanded private
  641  * key held in expanded_key[] (as obtained from
  642  * falcon_expand_privkey()). The hashed nonce + message is provided as
  643  * the SHAKE256 context *hash_data, which must still be in input mode
  644  * (i.e. not yet flipped to output mode). That context is modified in
  645  * the process.
  646  *
  647  * The nonce value (which was used at the start of the hashing process,
  648  * usually as part of a falcon_sign_start() call) must be provided again,
  649  * because it is encoded into the signature. The nonce length is 40 bytes.
  650  *
  651  * The source of randomness is the provided SHAKE256 context *rng, which
  652  * must have been already initialized, seeded, and set to output mode (see
  653  * shake256_init_prng_from_seed() and shake256_init_prng_from_system()).
  654  *
  655  * The signature is written in sig[]. The caller must set *sig_len to
  656  * the maximum size of sig[]; if the signature computation is
  657  * successful, then *sig_len will be set to the actual length of the
  658  * signature. If ct is zero, then the maximum signature length is
  659  * FALCON_SIG_VARTIME_MAXSIZE(logn) (where 'logn' qualifies the Falcon
  660  * degree encoded in the private key and can be obtained with
  661  * falcon_get_logn()). If ct is non-zero, then the signature length will
  662  * be exactl FALCON_SIG_CT_SIZE(logn) bytes.
  663  *
  664  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  665  * MUST be at least FALCON_TMPSIZE_SIGNTREE(logn) bytes.
  666  *
  667  * Returned value: 0 on success, or a negative error code.
  668  */
  669 int falcon_sign_tree_finish(shake256_context *rng,
  670         void *sig, size_t *sig_len,
  671         const void *expanded_key,
  672         shake256_context *hash_data, const void *nonce,
  673         int ct, void *tmp, size_t tmp_len);
  674 
  675 /* ==================================================================== */
  676 /*
  677  * Signature verification.
  678  */
  679 
  680 /*
  681  * Verify the signature sig[] (of length sig_len bytes) with regards to
  682  * the provided public key pubkey[] (of length pubkey_len bytes) and the
  683  * message data[] (of length data_len bytes).
  684  *
  685  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  686  * MUST be at least FALCON_TMPSIZE_VERIFY(logn) bytes.
  687  *
  688  * Returned value: 0 on success, or a negative error code.
  689  */
  690 int falcon_verify(const void *sig, size_t sig_len,
  691         const void *pubkey, size_t pubkey_len,
  692         const void *data, size_t data_len,
  693         void *tmp, size_t tmp_len);
  694 
  695 /*
  696  * Start a streamed signature verification. The provided SHAKE256 context
  697  * *hash_data is initialized, and the nonce value (extracted from the
  698  * signature) is injected into it. The caller shall then inject the
  699  * message data into the SHAKE256 context, and finally call
  700  * falcon_verify_finish().
  701  *
  702  * Returned value: 0 on success, or a negative error code.
  703  */
  704 int falcon_verify_start(shake256_context *hash_data,
  705         const void *sig, size_t sig_len);
  706 
  707 /*
  708  * Finish a streamed signature verification. The signature sig[] (of
  709  * length sig_len bytes) is verified against the provided public key
  710  * pubkey[] (of length pubkey_len bytes) and the hashed message. The
  711  * hashed message is provided as a SHAKE256 context *hash_data;
  712  * that context must have received the nonce and the message itself
  713  * (usually, the context is initialized and the nonce injected as
  714  * part of a falcon_verify_start() call), and still be in input
  715  * mode (not yet flipped to output mode). *hash_data is modified by
  716  * the verification process.
  717  *
  718  * The tmp[] buffer is used to hold temporary values. Its size tmp_len
  719  * MUST be at least FALCON_TMPSIZE_VERIFY(logn) bytes.
  720  *
  721  * Returned value: 0 on success, or a negative error code.
  722  */
  723 int falcon_verify_finish(const void *sig, size_t sig_len,
  724         const void *pubkey, size_t pubkey_len,
  725         shake256_context *hash_data,
  726         void *tmp, size_t tmp_len);
  727 
  728 /* ==================================================================== */
  729 
  730 #ifdef __cplusplus
  731 }
  732 #endif
  733 
  734 #endif