config.h
1 /*
2 * Manual configuration file for the Falcon implementation. Here can
3 * be set some compilation-time options.
4 *
5 * ==========================(LICENSE BEGIN)============================
6 *
7 * Copyright (c) 2017-2019 Falcon Project
8 *
9 * Permission is hereby granted, free of charge, to any person obtaining
10 * a copy of this software and associated documentation files (the
11 * "Software"), to deal in the Software without restriction, including
12 * without limitation the rights to use, copy, modify, merge, publish,
13 * distribute, sublicense, and/or sell copies of the Software, and to
14 * permit persons to whom the Software is furnished to do so, subject to
15 * the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be
18 * included in all copies or substantial portions of the Software.
19 *
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
22 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
23 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
24 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
25 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
26 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
27 *
28 * ===========================(LICENSE END)=============================
29 *
30 * @author Thomas Pornin <thomas.pornin@nccgroup.com>
31 */
32
33 #ifndef FALCON_CONFIG_H__
34 #define FALCON_CONFIG_H__
35
36 /*
37 * Each option is a macro which should be defined to either 1 or 0.
38 * If any of the options below is left undefined, then a default value
39 * will be used by the code, possibly using compile-time autodetection
40 * from compiler-defined macros.
41 *
42 * Explicitly setting a parameter can be done by uncommenting/modifying
43 * its definition below, in this file, or equivalently by setting it as
44 * a compiler flag.
45 */
46
47 /*
48 * Use the native 'double' C type for floating-point computations. Exact
49 * reproducibility of all tests requires that type to faithfully follow
50 * IEEE-754 "round-to-nearest" rules.
51 *
52 * Native double support will use the CPU hardware and/or
53 * compiler-provided functions; the latter is typically NOT
54 * constant-time, while the former MAY be constant-time, or not. On
55 * recent x86 CPU in 64-bit mode, SSE2 opcodes are used and they provide
56 * constant-time operations for all the operations used in Falcon,
57 * except for some special cases of divisions and square roots, but it
58 * can be shown that theses cases imply only negligible leak of
59 * information that cannot be leveraged into a full attack.
60 *
61 * If neither FALCON_FPNATIVE nor FALCON_FPEMU is defined, then use of
62 * the native 'double' C type is the default behaviour unless
63 * FALCON_ASM_CORTEXM4 is defined to 1, in which case the emulated code
64 * will be used.
65 *
66 #define FALCON_FPNATIVE 1
67 */
68
69 /*
70 * Use emulated floating-point implementation.
71 *
72 * Emulation uses only integer operations with uint32_t and uint64_t
73 * types. This is constant-time, provided that the underlying platform
74 * offers constant-time opcodes for the following operations:
75 *
76 * - Multiplication of two 32-bit unsigned integers into a 64-bit result.
77 * - Left-shift or right-shift of a 32-bit unsigned integer by a
78 * potentially secret shift count in the 0..31 range.
79 *
80 * Notably, the ARM Cortex M3 does not fulfill the first condition,
81 * while the Pentium IV does not fulfill the second.
82 *
83 * If neither FALCON_FPNATIVE nor FALCON_FPEMU is defined, then use of
84 * the native 'double' C type is the default behaviour unless
85 * FALCON_ASM_CORTEXM4 is defined to 1, in which case the emulated code
86 * will be used.
87 *
88 #define FALCON_FPEMU 1
89 */
90
91 /*
92 * Enable use of assembly for ARM Cortex-M4 CPU. By default, such
93 * support will be used based on some autodection on the compiler
94 * version and target architecture. Define this variable to 1 to force
95 * use of the assembly code, or 0 to disable it regardless of the
96 * autodetection.
97 *
98 * When FALCON_ASM_CORTEXM4 is enabled (whether defined explicitly or
99 * autodetected), emulated floating-point code will be used, unless
100 * FALCON_FPNATIVE or FALCON_FPEMU is explicitly set to override the
101 * choice. Emulated code with ARM assembly is constant-time and provides
102 * better performance than emulated code with plain C.
103 *
104 * The assembly code for the M4 can also work on a Cortex-M3. If the
105 * compiler is instructed to target the M3 (e.g. '-mcpu=cortex-m3' with
106 * GCC) then FALCON_ASM_CORTEXM4 won't be autodetected, but it can be
107 * enabled explicitly. Take care, though, that the M3 multiplication
108 * opcode (multiplication of two 32-bit unsigned integers with a 64-bit
109 * result) is NOT constant-time.
110 *
111 #define FALCON_ASM_CORTEXM4 1
112 */
113
114 /*
115 * Enable use of AVX2 intrinsics. If enabled, then the code will compile
116 * only when targeting x86 with a compiler that supports AVX2 intrinsics
117 * (tested with GCC 7.4.0, Clang 6.0.0, and MSVC 2015, both in 32-bit
118 * and 64-bit modes), and run only on systems that offer the AVX2
119 * opcodes. Some operations leverage AVX2 for better performance.
120 *
121 #define FALCON_AVX2 1
122 */
123
124 /*
125 * Enable use of FMA intrinsics. This setting has any effect only if
126 * FALCON_AVX2 is also enabled. The FMA intrinsics are normally available
127 * on any x86 CPU that also has AVX2. Note that setting this option will
128 * slightly modify the values of expanded private keys, but will normally
129 * not change the values of non-expanded private keys, public keys or
130 * signatures, for a given keygen/sign seed (non-expanded private keys
131 * and signatures might theoretically change, but only with low probability,
132 * less than 2^(-40); produced signatures are still safe and interoperable).
133 *
134 #define FALCON_FMA 1
135 */
136
137 /*
138 * Assert that the platform uses little-endian encoding. If enabled,
139 * then encoding and decoding of aligned multibyte values will be
140 * slightly faster (especially for hashing and random number
141 * generation). If not defined explicitly, then autodetection is
142 * applied.
143 *
144 #define FALCON_LE 1
145 */
146
147 /*
148 * Assert that the platform tolerates accesses to unaligned multibyte
149 * values. If enabled, then some operations are slightly faster. Note
150 * that ARM Cortex M4 do _not_ fully tolerate unaligned accesses; for
151 * such systems, this option should not be enabled. If not defined
152 * explicitly, then autodetection is applied.
153 *
154 #define FALCON_UNALIGNED 1
155 */
156
157 /*
158 * Use a PRNG based on ChaCha20 and seeded with SHAKE256, instead of
159 * SHAKE256 directly, for key pair generation purposes. This speeds up
160 * key pair generation, especially on platforms where SHAKE256 is
161 * comparatively slow: on the ARM Cortex M4, average key generation time
162 * is reduced by 19% with this setting; on a recent x86 Skylake, the
163 * reduction is smaller (less than 8%).
164 *
165 * However, this setting changes the private/public key pair obtained
166 * from a given seed, thus preventing reproducibility of the
167 * known-answer tests vectors. For compatibility with existing KAT
168 * vectors (e.g. in PQClean, pqm4 and NIST implementations), this
169 * setting is not enabled by default.
170 *
171 #define FALCON_KG_CHACHA20 1
172 */
173
174 /*
175 * Use an explicit OS-provided source of randomness for seeding (for the
176 * Zf(get_seed)() function implementation). Three possible sources are
177 * defined:
178 *
179 * - getentropy() system call
180 * - /dev/urandom special file
181 * - CryptGenRandom() function call
182 *
183 * More than one source may be enabled, in which case they will be tried
184 * in the order above, until a success is reached.
185 *
186 * By default, sources are enabled at compile-time based on these
187 * conditions:
188 *
189 * - getentropy(): target is one of: Linux with Glibc-2.25+, FreeBSD 12+,
190 * or OpenBSD.
191 * - /dev/urandom: target is a Unix-like system (including Linux,
192 * FreeBSD, NetBSD, OpenBSD, DragonFly, macOS, Android, Solaris, AIX).
193 * - CryptGenRandom(): target is Windows (Win32 or Win64).
194 *
195 * On most small embedded systems, none will be enabled and Zf(get_seed)()
196 * will always return 0. Applications will need to provide their own seeds.
197 *
198 #define FALCON_RAND_GETENTROPY 1
199 #define FALCON_RAND_URANDOM 1
200 #define FALCON_RAND_WIN32 1
201 */
202
203 #endif