10. Building on *nix from git repository
2
3    Run the autogen script to generate configure, then proceed to step 1.
4    Prerequisites: You'll need autoconf, automake and libtool installed.
5
6    $ ./autogen.sh
7
81. Building on *nix from a release
9
10    $ ./configure
11    $ make
12    $ make check   # (optional, but highly recommended)
13    $ sudo make install
14
152. Building on iOS
16
17    Use on the xcode project in IDE/iOS/wolfssl.xcodeproj
18    There is a README in IDE/iOS with more information
19
203. Building for Apple ARM64
21
22    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.
23
244. Building on Windows
25
26    Use the 32bit Visual Studio Solution wolfssl.sln
27    For a 64bit solution please use wolfssl64.sln
28
295. Building with IAR
30
31    Please see the README in IDE/IAR-EWARM for detailed instructions
32
336. Building with Keil
34
35    Please see the Keil Projects in IDE/MDK5-ARM/Projects
36
377. Building with Microchip tools
38
39    Please see the README in mplabx
40
418. Building with Freescale MQX
42
43    Please see the README in mqx
44
459. Building with Rowley CrossWorks for ARM
46
47    Use the CrossWorks project in IDE/ROWLEY-CROSSWORKS-ARM/wolfssl.hzp
48    There is a README.md in IDE/ROWLEY-CROSSWORKS-ARM with more information
49
5010. Building with Arduino
51
52    Use the script IDE/ARDUINO/wolfssl-arduino.sh to reformat the wolfSSL
53    library for compatibility with the Arduino IDE. There is a README.md in
54    IDE/ARDUINO for detailed instructions.
55
5611. Building for Android with Visual Studio 2017
57
58    Please see the README in IDE/VS-ARM.
59    Use the Visual Studio solution IDE/VS-ARM/wolfssl.sln.
60
6112. Building for Yocto Project or OpenEmbedded
62
63    Please see the README in the "meta-wolfssl" repository. This repository
64    holds wolfSSL's Yocto and OpenEmbedded layer, which contains recipes
65    for wolfSSL, wolfSSH, wolfMQTT, wolfTPM, wolfCrypt examples, and OSS
66    project bbappend files.
67
68    https://github.com/wolfssl/meta-wolfssl
69
70    The wolfSSL recipe can also be found in the OpenEmbedded
71    "meta-openembedded/meta-networking/recipes-connectivity" layer:
72
73    https://github.com/openembedded/meta-openembedded
74
7513. Porting to a new platform
76
77    Please see section 2.4 in the manual:
78    http://www.wolfssl.com/yaSSL/Docs-cyassl-manual-2-building-cyassl.html
79
8014. Building with CMake
81    Note: Primary development uses automake (./configure). The support for CMake
82    is still under development.
83
84    For configuring wolfssl using CMake, we recommend downloading the CMake
85    GUI (https://cmake.org/download/). This tool allows you to see all of
86    wolfssl's configuration variables, set them, and view their descriptions.
87    Looking at the GUI or CMakeCache.txt (generated after running cmake once) is
88    the best way to find out what configuration options are available and what
89    they do. You can also invoke CMake from the GUI, which is described in the
90    Windows instructions below. For Unix-based systems, we describe the command
91    line work flow. Regardless of your chosen workflow, cmake will generate
92    a header options.h in the wolfssl directory that contains the options used
93    to configure the build.
94
95    Unix-based Platforms
96    ---
97    1) Navigate to the wolfssl root directory containing "CMakeLists.txt".
98    2) Create a directory called "build" and change into it. This is where
99       CMake will store build files.
100    3) Run `cmake ..` to generate the target build files (e.g. UNIX Makefiles).
101       To enable or disable features, set them using -D<option>=[yes/no]. For
102       example, to disable TLS 1.3 support, run cmake .. -DWOLFSSL_TLS13=no
103       (autoconf equivalent: ./configure --disable-tls13) To enable DSA, run
104       cmake .. -DWOLFSSL_DSA=yes (autoconf equivalent: ./configure
105       --enable-dsa). Again, you can find a list of these options and their
106       descriptions either using the CMake GUI or by looking at CMakeCache.txt.
107    5) The build directory should now contain the generated build files. Build
108       with `cmake --build .`. Under the hood, this runs the target build tool
109       (by default, make). You can also invoke the target build tool directly
110       (e.g. make).
111
112       To build with debugging use: `cmake .. -DCMAKE_BUILD_TYPE=Debug`.
113
114    Windows (Visual Studio)
115    ---
116    1) Go to this page, download the appropriate Windows installer, and install
117       to get the CMake GUI: https://cmake.org/download/ Native CMake support in
118       Visual Studio 16 2019 (and possibly older versions) has proven buggy. We
119       recommend using the CMake GUI in concert with Visual Studio, as described
120    in these steps.
121    2) Open CMake.
122    3) Where is the source code: <root directory of wolfssl containing
123       CMakeLists.txt>
124    4) Where to build the binaries: <build directory, e.g. wolfssl/build>
125    5) Hit Configure. CMake runs the code in CMakeLists.txt and builds up an
126       internal representation of the project.
127    6) Hit Generate. CMake generates the build files. For Windows, this will
128       be Visual Studio project (.vcxproj) and solution (.sln) files.
129    7) Open Visual Studio and select "Open a project or solution".
130    8) Navigate to the build directory and select wolfssl.sln to load the
131       project.
132
133    Windows (command line)
134    ---
135    1) Open Command Prompt
136    2) Run the Visual Studio batch to setup command line variables, e.g. C:\Program Files (x86)\Microsoft Visual
137       Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat
138    3) Follow steps in "Unix-based Platforms" above.
139
14015. Building with liboqs for TLS 1.3 [EXPERIMENTAL]
141    In order be able to use liboqs, you must have it built and installed on your
142    system. We support the 0.7.0 release of liboqs. You can download it from
143    the following link:
144
145    https://github.com/open-quantum-safe/liboqs/archive/refs/tags/0.7.0.tar.gz
146
147    Once unpacked, this would be sufficient:
148
149    $ cd liboqs-0.7.0
150    $ mkdir build
151    $ cd build
152    $ cmake -DOQS_USE_OPENSSL=0 ..
153    $ make all
154    $ sudo make install
155
156    And then for building wolfssl, the following is sufficient:
157
158    $ cd wolfssl
159    $ ./autogen.sh (Might not be necessary)
160    $ ./configure --with-liboqs
161    $ make all
162
163    Execute the following to see the liboqs-related options for KEM groups near
164    the end of the output of these commands:
165
166    $ ./examples/server/server -?
167    $ ./examples/client/client -?
168
169    For a quick start, you can run the client and server like this:
170
171    $ ./examples/server/server -v 4 --pqc P521_KYBER_LEVEL5
172    $ ./examples/client/client -v 4 --pqc P521_KYBER_LEVEL5
173
174    Look for the following line in the output of the server and client:
175
176    ```
177    Using Post-Quantum KEM: P521_KYBER_LEVEL5
178    ```
179
180    For authentication, you can generate a certificate chain using the Open
181    Quantum Safe project's fork of OpenSSL. We support certificates and keys
182    generated by the 2021-08 snapshot of the OQS-OpenSSL_1_1_1-stable branch
183    of the fork. You can download it from the following link:
184
185    https://github.com/open-quantum-safe/openssl/archive/refs/tags/OQS-OpenSSL_1_1_1-stable-snapshot-2021-08.tar.gz
186
187    Once unpacked, this would be sufficient for building it:
188
189    $ cd openssl-OQS-OpenSSL_1_1_1-stable-snapshot-2021-08/
190    $ ./config no-shared
191    $ make all
192
193    Note that installation is NOT required.
194
195    There is a script for generating a Falcon NIST Level 1 and NIST Level 5
196    certificate chain which can be found in the wolfssl-examples github repo at
197    pq/generate_falcon_chains.sh. Please find detailed instructions on how to
198    generate and verify the keys and certificates in pq/README.md. As a quick-
199    start, simply copy generate_falcon_chains.sh into the
200    openssl-OQS-OpenSSL_1_1_1-stable-snapshot-2021-08 directory and execute the
201    script.
202
203    Once the certificates and keys are generated, copy them from the
204    openssl-OQS-OpenSSL_1_1_1-stable-snapshot-2021-08/ directory to the certs
205    directory of wolfssl. Now you can run the server and client like this:
206
207    $ examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \
208      -A certs/falcon_level5_root_cert.pem \
209      -c certs/falcon_level1_entity_cert.pem \
210      -k certs/falcon_level1_entity_key.pem \
211      --pqc P521_KYBER_LEVEL5
212
213    $ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \
214      -A certs/falcon_level1_root_cert.pem \
215      -c certs/falcon_level5_entity_cert.pem \
216      -k certs/falcon_level5_entity_key.pem \
217      --pqc P521_KYBER_LEVEL5
218
219    Congratulations! You have just achieved a fully quantum-safe TLS 1.3
220    connection!
221
222    The following NIST Competition Round 3 Finalist algorithms are supported:
223    - CRYSTALS-KYBER (KEM)
224    - SABER (KEM)
225    - NTRU (KEM)
226    - FALCON (signature scheme)
227
228    Links to more information about these algorithms can be found here:
229
230    https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions
231
232    NOTE: The quantum-safe algorithms provided by liboqs are unstandardized and
233          experimental. It is highly advised that they NOT be used in production
234          environments. All OIDs and codepoints are temporary and expected to
235          change in the future. You should have no expectation of backwards
236          compatibility.
237