config.h

/*
 * Manual configuration file for the Falcon implementation. Here can
 * be set some compilation-time options.
 *
 * ==========================(LICENSE BEGIN)============================
 *
 * Copyright (c) 2017-2019  Falcon Project
 *
 * Permission is hereby granted, free of charge, to any person obtaining
 * a copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * ===========================(LICENSE END)=============================
 *
 * @author   Thomas Pornin <thomas.pornin@nccgroup.com>
 */

#ifndef FALCON_CONFIG_H__
#define FALCON_CONFIG_H__

/*
 * Each option is a macro which should be defined to either 1 or 0.
 * If any of the options below is left undefined, then a default value
 * will be used by the code, possibly using compile-time autodetection
 * from compiler-defined macros.
 *
 * Explicitly setting a parameter can be done by uncommenting/modifying
 * its definition below, in this file, or equivalently by setting it as
 * a compiler flag.
 */

/*
 * Emulated floating-point implementation.
 *
 * Emulation uses only integer operations with uint32_t and uint64_t
 * types. This is constant-time, provided that the underlying platform
 * offers constant-time opcodes for the following operations:
 *
 *  - Multiplication of two 32-bit unsigned integers into a 64-bit result.
 *  - Left-shift or right-shift of a 32-bit unsigned integer by a
 *    potentially secret shift count in the 0..31 range.
 *
 * Notably, the ARM Cortex M3 does not fulfill the first condition,
 * while the Pentium IV does not fulfill the second.
 *
 */

/*
 * *** CRITICAL SECURITY WARNING ***:
 *
 * Here floating-point emulation is enabled in order to get reliable
 * deterministic signing, because native floating-point units and code
 * optimizations may yield slight discrepancies that could affect
 * determinism.
 *
 * KEEPING FALCON_FPEMU ENABLED IS STRONGLY RECOMMENDED! Emulation may
 * be needed for obtaining truly deterministic signing across
 * different platforms and configurations, i.e., the same message
 * should always yield the same signature (under the same secret key).
 *
 * Any non-determinism in signing can lead to a CATASTROPHIC SECURITY
 * FAILURE, potentially enabling an attacker to create forgeries for
 * arbitrary messages after obtaining two or more different signatures
 * for the same message (under the same secret key).
 *
 * Determinism can be sanity-checked (but not guaranteed) using the
 * provided KATs, via test_deterministic. Any deviation from the
 * expected results indicates a lack of the desired determinism;
 * however, agreement does not prove determinism for all possible
 * inputs.
 */
#define FALCON_FPEMU  1


/*
 * Native 'double' C type for floating-point computations. Exact
 * reproducibility of all tests requires that type to faithfully follow
 * IEEE-754 "round-to-nearest" rules.
 *
 * Native double support will use the CPU hardware and/or
 * compiler-provided functions; the latter is typically NOT
 * constant-time, while the former MAY be constant-time, or not. On
 * recent x86 CPU in 64-bit mode, SSE2 opcodes are used and they provide
 * constant-time operations for all the operations used in Falcon,
 * except for some special cases of divisions and square roots, but it
 * can be shown that theses cases imply only negligible leak of
 * information that cannot be leveraged into a full attack.
 *
 * If neither FALCON_FPNATIVE nor FALCON_FPEMU is defined, then use of
 * the native 'double' C type is the default behaviour unless
 * FALCON_ASM_CORTEXM4 is defined to 1, in which case the emulated code
 * will be used.
 *
 */

/*
 * For determinism, explicitly disable native floating-point
 * operations. (These are already implicitly disabled by enabling
 * FALCON_FPEMU above; here it is made explicit as a defensive
 * measure.)
 */
#define FALCON_FPNATIVE  0


/*
 * Assembly for ARM Cortex-M4 CPU: by default, such support will be
 * used based on some autodection on the compiler version and target
 * architecture. Define this variable to 1 to force use of the
 * assembly code, or 0 to disable it regardless of the autodetection.
 *
 * When FALCON_ASM_CORTEXM4 is enabled (whether defined explicitly or
 * autodetected), emulated floating-point code will be used, unless
 * FALCON_FPNATIVE or FALCON_FPEMU is explicitly set to override the
 * choice. Emulated code with ARM assembly is constant-time and provides
 * better performance than emulated code with plain C.
 *
 * The assembly code for the M4 can also work on a Cortex-M3. If the
 * compiler is instructed to target the M3 (e.g. '-mcpu=cortex-m3' with
 * GCC) then FALCON_ASM_CORTEXM4 won't be autodetected, but it can be
 * enabled explicitly. Take care, though, that the M3 multiplication
 * opcode (multiplication of two 32-bit unsigned integers with a 64-bit
 * result) is NOT constant-time.
 *
 */

/*
 * Explicitly disable the specialized assembly code for ARM Cortex-M4.
 *
 * While we are not aware of any way that the assembly code could lead
 * to non-determinism, caution should be exercised if it is ever under
 * consideration for usage. (At minimum, check KATs.)
 */
#define FALCON_ASM_CORTEXM4  0


/*
 * AVX2 intrinsics: if enabled, then the code will compile only when
 * targeting x86 with a compiler that supports AVX2 intrinsics (tested
 * with GCC 7.4.0, Clang 6.0.0, and MSVC 2015, both in 32-bit and
 * 64-bit modes), and run only on systems that offer the AVX2
 * opcodes. Some operations leverage AVX2 for better performance.
 *
 */

/*
 * Explicitly disable AVX2 optimizations. (These are already
 * implicitly disabled by enabling FALCON_FPEMU above; here it is made
 * explicit as a defensive measure.)
 *
 * While we are not aware of any way that AVX2 optimizations could
 * lead to non-determinism, caution should be exercised if they are
 * ever under consideration for usage. (At minimum, check KATs.)
 */
#define FALCON_AVX2  0


/*
 * FMA intrinsics: this setting has any effect only if FALCON_AVX2 is
 * also enabled. The FMA intrinsics are normally available on any x86
 * CPU that also has AVX2. Note that setting this option will slightly
 * modify the values of expanded private keys, but will normally not
 * change the values of non-expanded private keys, public keys or
 * signatures, for a given keygen/sign seed (non-expanded private keys
 * and signatures might theoretically change, but only with low
 * probability, less than 2^(-40); produced signatures are still safe
 * and interoperable).
 *
 */

/*
 * Explicitly disable FMA intrinsics, which (as mentioned above) are
 * KNOWN to lead to non-determinism in some cases. (These are already
 * implicitly disabled by enabling FALCON_FPEMU above; here it is made
 * explicit as a defensive measure.)
 *
 * CRITICAL SECURITY WARNING: it is strongly recommended *NOT* to
 * enable both FALCON_FPU and FALCON_FMA. Doing so is *KNOWN* to lead
 * to non-determinism in some cases.
 */
#define FALCON_FMA  0


/*
 * Assert that the platform uses little-endian encoding. If enabled,
 * then encoding and decoding of aligned multibyte values will be
 * slightly faster (especially for hashing and random number
 * generation). If not defined explicitly, then autodetection is
 * applied.
 *
#define FALCON_LE   1
 */

/*
 * Assert that the platform tolerates accesses to unaligned multibyte
 * values. If enabled, then some operations are slightly faster. Note
 * that ARM Cortex M4 do _not_ fully tolerate unaligned accesses; for
 * such systems, this option should not be enabled. If not defined
 * explicitly, then autodetection is applied.
 *
#define FALCON_UNALIGNED   1
 */

/*
 * Use a PRNG based on ChaCha20 and seeded with SHAKE256, instead of
 * SHAKE256 directly, for key pair generation purposes. This speeds up
 * key pair generation, especially on platforms where SHAKE256 is
 * comparatively slow: on the ARM Cortex M4, average key generation time
 * is reduced by 19% with this setting; on a recent x86 Skylake, the
 * reduction is smaller (less than 8%).
 *
 * However, this setting changes the private/public key pair obtained
 * from a given seed, thus preventing reproducibility of the
 * known-answer tests vectors. For compatibility with existing KAT
 * vectors (e.g. in PQClean, pqm4 and NIST implementations), this
 * setting is not enabled by default.
 *
#define FALCON_KG_CHACHA20   1
 */

/*
 * Use an explicit OS-provided source of randomness for seeding (for the
 * Zf(get_seed)() function implementation). Three possible sources are
 * defined:
 *
 *  - getentropy() system call
 *  - /dev/urandom special file
 *  - CryptGenRandom() function call
 *
 * More than one source may be enabled, in which case they will be tried
 * in the order above, until a success is reached.
 *
 * By default, sources are enabled at compile-time based on these
 * conditions:
 *
 *  - getentropy(): target is one of: Linux with Glibc-2.25+, FreeBSD 12+,
 *    or OpenBSD.
 *  - /dev/urandom: target is a Unix-like system (including Linux,
 *    FreeBSD, NetBSD, OpenBSD, DragonFly, macOS, Android, Solaris, AIX).
 *  - CryptGenRandom(): target is Windows (Win32 or Win64).
 *
 * On most small embedded systems, none will be enabled and Zf(get_seed)()
 * will always return 0. Applications will need to provide their own seeds.
 *
#define FALCON_RAND_GETENTROPY   1
#define FALCON_RAND_URANDOM      1
#define FALCON_RAND_WIN32        1
 */

#endif