2
0

INSTALL 16 KB

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