-
Notifications
You must be signed in to change notification settings - Fork 834
/
INSTALL
440 lines (325 loc) · 15.6 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
0. Building on *nix from git repository
Run the autogen script to generate configure, then proceed to step 1.
Prerequisites: You'll need autoconf, automake and libtool installed.
$ ./autogen.sh
1. Building on *nix from a release
$ ./configure
$ make
$ make check # (optional, but highly recommended)
$ sudo make install
Note: Building with configure generates a wolfssl/options.h file that contains
all the generated build options. This file needs to be included in your application
before any other wolfSSL headers. Optionally your application can define
WOLFSSL_USE_OPTIONS_H to do this automatically.
2. Building on iOS
Use on the xcode project in IDE/iOS/wolfssl.xcodeproj
There is a README in IDE/iOS with more information
3. Building for Apple ARM64
When building for an Apple ARM64 platform, ensure the host CPU type is detected as "aarch64" during configure, if not, pass --host=aarch64-apple-darwin to configure.
4. Building on Windows
Use the Visual Studio Solution wolfssl64.sln
5. Building with IAR
Please see the README in IDE/IAR-EWARM for detailed instructions
6. Building with Keil
Please see the Keil Projects in IDE/MDK5-ARM/Projects
7. Building with Microchip tools
Please see the README in mplabx
8. Building with Freescale MQX
Please see the README in mqx
9. Building with Rowley CrossWorks for ARM
Use the CrossWorks project in IDE/ROWLEY-CROSSWORKS-ARM/wolfssl.hzp
There is a README.md in IDE/ROWLEY-CROSSWORKS-ARM with more information
10. Building with Arduino
Use the script IDE/ARDUINO/wolfssl-arduino.sh to reformat the wolfSSL
library for compatibility with the Arduino IDE. There is a README.md in
IDE/ARDUINO for detailed instructions.
11. Building for Android with Visual Studio 2017
Please see the README in IDE/VS-ARM.
Use the Visual Studio solution IDE/VS-ARM/wolfssl.sln.
12. Building for Yocto Project or OpenEmbedded
Please see the README in the "meta-wolfssl" repository. This repository
holds wolfSSL's Yocto and OpenEmbedded layer, which contains recipes
for wolfSSL, wolfSSH, wolfMQTT, wolfTPM, wolfCrypt examples, and OSS
project bbappend files.
https://github.com/wolfssl/meta-wolfssl
The wolfSSL recipe can also be found in the OpenEmbedded
"meta-openembedded/meta-networking/recipes-connectivity" layer:
https://github.com/openembedded/meta-openembedded
13. Porting to a new platform
Please see section 2.4 in the manual:
https://www.wolfssl.com/documentation/manuals/wolfssl/chapter02.html#customizing-or-porting-wolfssl
14. Building with CMake
Note: Primary development uses automake (./configure). The support for CMake
is still under development.
For configuring wolfssl using CMake, we recommend downloading the CMake
GUI (https://cmake.org/download/). This tool allows you to see all of
wolfssl's configuration variables, set them, and view their descriptions.
Looking at the GUI or CMakeCache.txt (generated after running cmake once) is
the best way to find out what configuration options are available and what
they do. You can also invoke CMake from the GUI, which is described in the
Windows instructions below. For Unix-based systems, we describe the command
line work flow. Regardless of your chosen workflow, cmake will generate
a header options.h in the wolfssl directory that contains the options used
to configure the build.
Note: Building with configure generates a wolfssl/options.h file that contains
all the generated build options. This file needs to be included in your application
before any other wolfSSL headers. Optionally your application can define
WOLFSSL_USE_OPTIONS_H to do this automatically.
Unix-based Platforms
---
1) Navigate to the wolfssl root directory containing "CMakeLists.txt".
2) Create a directory called "build" and change into it. This is where
CMake will store build files.
3) Run `cmake ..` to generate the target build files (e.g. UNIX Makefiles).
To enable or disable features, set them using -D<option>=[yes/no]. For
example, to disable TLS 1.3 support, run cmake .. -DWOLFSSL_TLS13=no
(autoconf equivalent: ./configure --disable-tls13) To enable DSA, run
cmake .. -DWOLFSSL_DSA=yes (autoconf equivalent: ./configure
--enable-dsa). Again, you can find a list of these options and their
descriptions either using the CMake GUI or by looking at CMakeCache.txt.
5) The build directory should now contain the generated build files. Build
with `cmake --build .`. Under the hood, this runs the target build tool
(by default, make). You can also invoke the target build tool directly
(e.g. make).
To build with debugging use: `cmake .. -DCMAKE_BUILD_TYPE=Debug`.
In the simplest form:
# create a root directory for wolfssl repo
git clone https://github.com/wolfSSL/wolfssl.git
cd wolfssl
# From the root of the wolfSSL repo:
mkdir -p out
pushd out
cmake ..
cmake --build .
# View the available ciphers with:
./examples/client/client -e
popd
ARIA Cipher Suite.
The ARIA cipher needs a 3rd party source binary, typically called
`MagicCrypto.tar.gz`.
The MagicCrypto files can be either copied to the local `wolfssl` directory,
or an environment variable `ARIA_DIR` can be set to point to the location.
Simply having the environment variable or local `MagicCrypto` directory
will not automatically enable the ARIA Ciphers.
To enable ARIA Ciphers in wolfSSL for `CMake`:
# From the root of the wolfSSL repo:
# set to your path
export ARIA_DIR=~/workspace/MagicCrypto
mkdir -p out
pushd out
cmake .. -DWOLFSSL_ARIA=yes
cmake --build .
# View the available ciphers with:
./examples/client/client -e
popd
Windows (Visual Studio)
---
1) Go to this page, download the appropriate Windows installer, and install
to get the CMake GUI: https://cmake.org/download/ Native CMake support in
Visual Studio 16 2019 (and possibly older versions) has proven buggy. We
recommend using the CMake GUI in concert with Visual Studio, as described
in these steps.
2) Open CMake.
3) Where is the source code: <root directory of wolfssl containing
CMakeLists.txt>
4) Where to build the binaries: <build directory, e.g. wolfssl/build>
5) Hit Configure. CMake runs the code in CMakeLists.txt and builds up an
internal representation of the project.
6) Hit Generate. CMake generates the build files. For Windows, this will
be Visual Studio project (.vcxproj) and solution (.sln) files.
7) Open Visual Studio and select "Open a project or solution".
8) Navigate to the build directory and select wolfssl.sln to load the
project.
Windows (command line)
---
1) Open Command Prompt
2) Run the Visual Studio batch to setup command line variables, e.g. C:\Program Files (x86)\Microsoft Visual
Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat
3) Follow steps in "Unix-based Platforms" above.
15. Building with liboqs for TLS 1.3 [EXPERIMENTAL]
In order be able to use liboqs, you must have it built and installed on your
system. We support liboqs at a specific git commit.
NOTE: Even if you have already installed liboqs, you need to follow these
steps to install liboqs again as we support sphincs variants that are
disabled by default in OQS's fork of OpenSSL.
Here are instructions for obtaining and building liboqs:
$ mkdir ~/oqs
$ cd ~/oqs
$ git clone --single-branch https://github.com/open-quantum-safe/liboqs.git
$ cd liboqs/
$ git checkout 0.8.0
$ mkdir build
$ cd build
$ cmake -DOQS_USE_OPENSSL=0 ..
$ make all
$ sudo make install
And then for building wolfssl, the following is sufficient:
$ cd wolfssl
$ ./autogen.sh (Might not be necessary)
$ ./configure --with-liboqs
$ make all
Execute the following to see the liboqs-related options for KEM groups near
the end of the output of these commands:
$ ./examples/server/server -?
$ ./examples/client/client -?
For a quick start, you can run the client and server like this:
$ ./examples/server/server -v 4 --pqc P521_KYBER_LEVEL5
$ ./examples/client/client -v 4 --pqc P521_KYBER_LEVEL5
Look for the following line in the output of the server and client:
```
Using Post-Quantum KEM: P521_KYBER_LEVEL5
```
For authentication, you can generate a certificate chain using a patch on
top of the Open Quantum Safe project's fork of OpenSSL. We support
certificates and keys generated by the patched version which is maintained
in our OSP repo.
Instructions for obtaining and building our patched version of OQS's fork of
OpenSSL can be found at:
https://github.com/wolfSSL/osp/tree/master/oqs/README.md
There are scripts for generating FALCON, Dilithium and SPHINCS+ certificate
chains which can be found in the same directory as the `README.md` file in
the `osp` github repo. Please find instructions on how to generate the keys
and certificates in the `README.md` file.
Once the certificates and keys are generated, copy them from the
to the certs directory of wolfssl. Now you can run the server and client
like this:
$ examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \
-A certs/falcon_level5_root_cert.pem \
-c certs/falcon_level1_entity_cert.pem \
-k certs/falcon_level1_entity_key.pem \
--pqc P521_KYBER_LEVEL5
$ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \
-A certs/falcon_level1_root_cert.pem \
-c certs/falcon_level5_entity_cert.pem \
-k certs/falcon_level5_entity_key.pem \
--pqc P521_KYBER_LEVEL5
Congratulations! You have just achieved a fully quantum-safe TLS 1.3
connection!
The following NIST Competition winning algorithms are supported:
- CRYSTALS-KYBER (KEM)
- Dilithium (signature scheme)
- FALCON (signature scheme)
- SPHINCS+ (signature scheme)
The following NIST Competition Round 3 finalist algorithms were supported,
but have been removed after 5.3.3
- SABER (KEM)
- NTRU (KEM)
Links to more information about all of these algorithms can be found here:
https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions
NOTE: The quantum-safe algorithms provided by liboqs are unstandardized and
experimental. It is highly advised that they NOT be used in production
environments. All OIDs and codepoints are temporary and expected to
change in the future. You should have no expectation of backwards
compatibility.
16. Building with vcpkg
# Building wolfssl - Using vcpkg
You can download and install wolfssl using the [vcpkg](https://github.com/Microsoft/vcpkg):
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
OR for Windows
bootstrap-vcpkg.bat
./vcpkg integrate install
./vcpkg install wolfssl
The wolfssl port in vcpkg is kept up to date by wolfSSL.
We also have vcpkg ports for wolftpm, wolfmqtt and curl.
17. Building with hash-sigs lib for LMS/HSS support [EXPERIMENTAL]
Using LMS/HSS requires that the hash-sigs lib has been built on
your system. We support hash-sigs lib at this git commit:
b0631b8891295bf2929e68761205337b7c031726
At the time of writing this, this is the HEAD of the master
branch of the hash-sigs project.
Currently the hash-sigs project only builds static libraries:
- hss_verify.a: a single-threaded verify-only static lib.
- hss_lib.a: a single-threaded static lib.
- hss_lib_thread.a: a multi-threaded static lib.
The multi-threaded version will mainly have speedups for key
generation and signing.
The default LMS build (--enable-lms) will look for
hss_lib.a first, and hss_lib_thread.a second, in a specified
hash-sigs dir.
The LMS verify-only build (--enable-lms=verify-only) will look
for hss_verify.a only, which is a slimmer library that includes
only the minimal functions necessary for signature verification.
How to get and build the hash-sigs library:
$ mkdir ~/hash_sigs
$ cd ~/hash_sigs
$ git clone https://github.com/cisco/hash-sigs.git src
$ cd src
$ git checkout b0631b8891295bf2929e68761205337b7c031726
In sha256.h, set USE_OPENSSL to 0:
#define USE_OPENSSL 0
To build the single-threaded version:
$ make hss_lib.a
$ ls *.a
hss_lib.a
To build multi-threaded:
$ make hss_lib_thread.a
$ ls *.a
hss_lib_thread.a
To build verify-only:
$ make hss_verify.a
$ ls *.a
hss_verify.a
Build wolfSSL with
$ ./configure \
--enable-static \
--disable-shared \
--enable-lms \
--with-liblms=<path to dir containing hss_lib.a or hss_lib_thread.a>
$ make
Run the benchmark against LMS/HSS with:
$ ./wolfcrypt/benchmark/benchmark -lms_hss
18. Building for Debian, Ubuntu, Linux Mint, and derivatives
To generate a .deb package, configure wolfSSL with the desired
configuration. Then run `make deb` to generate a Debian package
with the current configuration. To build the package inside a
Docker container, use `make deb-docker`. In both cases the
resulting packages are placed in the root directory of the
project.
19. Building for RHEL, Fedora, CentOS, SUSE, and openSUSE
To generate a .rpm package, configure wolfSSL with the desired
configuration. Then run `make rpm` to generate a .rpm package
with the current configuration. To build the package inside a
Docker container, use `make rpm-docker`. In both cases the
resulting packages are placed in the root directory of the
project.
20. Building with xmss-reference lib for XMSS/XMSS^MT support [EXPERIMENTAL]
Experimental support for XMSS/XMSS^MT has been achieved by integration
with the xmss-reference implementation from RFC 8391 (XMSS: eXtended
Merkle Signature Scheme). We support a patched version of xmss-reference
based on this git commit:
171ccbd26f098542a67eb5d2b128281c80bd71a6
At the time of writing this, this is the HEAD of the master branch of
the xmss-reference project.
How to get the xmss-reference library:
$ mkdir ~/xmss
$ cd ~/xmss
$ git clone https://github.com/XMSS/xmss-reference.git src
$ cd src
$ git checkout 171ccbd26f098542a67eb5d2b128281c80bd71a6
$ git apply <path to xmss reference patch>
The patch may be found in the wolfssl-examples repo here:
pq/stateful_hash_sig/0001-Patch-to-support-wolfSSL-xmss-reference-integration.patch
To build patched xmss-reference:
$ make xmss_lib.a
To build verify-only patched xmss-reference:
$ make xmss_verify_lib.a
Note that this patch changes xmss-reference to use wolfCrypt SHA256 hashing,
by registering a SHA callback function in xmss-reference. It
thus benefits from all the same asm speedups as wolfCrypt SHA hashing.
Depending on architecture you may build with --enable-intelasm, or
--enable-armasm, and see 30-40% speedups in XMSS/XMSS^MT.
For full keygen, signing, verifying, and benchmarking support, build
wolfSSL with:
$ ./configure \
--enable-xmss \
--with-libxmss=<path to xmss src dir>
$ make
Run the benchmark against XMSS/XMSS^MT with:
$ ./wolfcrypt/benchmark/benchmark -xmss_xmssmt
For a leaner xmss verify-only build, build with
$ ./configure \
--enable-xmss=verify-only \
--with-libxmss=<path to xmss src dir>
$ make