INSTALL 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311
  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. 2. Building on iOS
  11. Use on the xcode project in IDE/iOS/wolfssl.xcodeproj
  12. There is a README in IDE/iOS with more information
  13. 3. Building for Apple ARM64
  14. 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.
  15. 4. Building on Windows
  16. Use the Visual Studio Solution wolfssl64.sln
  17. 5. Building with IAR
  18. Please see the README in IDE/IAR-EWARM for detailed instructions
  19. 6. Building with Keil
  20. Please see the Keil Projects in IDE/MDK5-ARM/Projects
  21. 7. Building with Microchip tools
  22. Please see the README in mplabx
  23. 8. Building with Freescale MQX
  24. Please see the README in mqx
  25. 9. Building with Rowley CrossWorks for ARM
  26. Use the CrossWorks project in IDE/ROWLEY-CROSSWORKS-ARM/wolfssl.hzp
  27. There is a README.md in IDE/ROWLEY-CROSSWORKS-ARM with more information
  28. 10. Building with Arduino
  29. Use the script IDE/ARDUINO/wolfssl-arduino.sh to reformat the wolfSSL
  30. library for compatibility with the Arduino IDE. There is a README.md in
  31. IDE/ARDUINO for detailed instructions.
  32. 11. Building for Android with Visual Studio 2017
  33. Please see the README in IDE/VS-ARM.
  34. Use the Visual Studio solution IDE/VS-ARM/wolfssl.sln.
  35. 12. Building for Yocto Project or OpenEmbedded
  36. Please see the README in the "meta-wolfssl" repository. This repository
  37. holds wolfSSL's Yocto and OpenEmbedded layer, which contains recipes
  38. for wolfSSL, wolfSSH, wolfMQTT, wolfTPM, wolfCrypt examples, and OSS
  39. project bbappend files.
  40. https://github.com/wolfssl/meta-wolfssl
  41. The wolfSSL recipe can also be found in the OpenEmbedded
  42. "meta-openembedded/meta-networking/recipes-connectivity" layer:
  43. https://github.com/openembedded/meta-openembedded
  44. 13. Porting to a new platform
  45. Please see section 2.4 in the manual:
  46. http://www.wolfssl.com/yaSSL/Docs-cyassl-manual-2-building-cyassl.html
  47. 14. Building with CMake
  48. Note: Primary development uses automake (./configure). The support for CMake
  49. is still under development.
  50. For configuring wolfssl using CMake, we recommend downloading the CMake
  51. GUI (https://cmake.org/download/). This tool allows you to see all of
  52. wolfssl's configuration variables, set them, and view their descriptions.
  53. Looking at the GUI or CMakeCache.txt (generated after running cmake once) is
  54. the best way to find out what configuration options are available and what
  55. they do. You can also invoke CMake from the GUI, which is described in the
  56. Windows instructions below. For Unix-based systems, we describe the command
  57. line work flow. Regardless of your chosen workflow, cmake will generate
  58. a header options.h in the wolfssl directory that contains the options used
  59. to configure the build.
  60. Unix-based Platforms
  61. ---
  62. 1) Navigate to the wolfssl root directory containing "CMakeLists.txt".
  63. 2) Create a directory called "build" and change into it. This is where
  64. CMake will store build files.
  65. 3) Run `cmake ..` to generate the target build files (e.g. UNIX Makefiles).
  66. To enable or disable features, set them using -D<option>=[yes/no]. For
  67. example, to disable TLS 1.3 support, run cmake .. -DWOLFSSL_TLS13=no
  68. (autoconf equivalent: ./configure --disable-tls13) To enable DSA, run
  69. cmake .. -DWOLFSSL_DSA=yes (autoconf equivalent: ./configure
  70. --enable-dsa). Again, you can find a list of these options and their
  71. descriptions either using the CMake GUI or by looking at CMakeCache.txt.
  72. 5) The build directory should now contain the generated build files. Build
  73. with `cmake --build .`. Under the hood, this runs the target build tool
  74. (by default, make). You can also invoke the target build tool directly
  75. (e.g. make).
  76. To build with debugging use: `cmake .. -DCMAKE_BUILD_TYPE=Debug`.
  77. Windows (Visual Studio)
  78. ---
  79. 1) Go to this page, download the appropriate Windows installer, and install
  80. to get the CMake GUI: https://cmake.org/download/ Native CMake support in
  81. Visual Studio 16 2019 (and possibly older versions) has proven buggy. We
  82. recommend using the CMake GUI in concert with Visual Studio, as described
  83. in these steps.
  84. 2) Open CMake.
  85. 3) Where is the source code: <root directory of wolfssl containing
  86. CMakeLists.txt>
  87. 4) Where to build the binaries: <build directory, e.g. wolfssl/build>
  88. 5) Hit Configure. CMake runs the code in CMakeLists.txt and builds up an
  89. internal representation of the project.
  90. 6) Hit Generate. CMake generates the build files. For Windows, this will
  91. be Visual Studio project (.vcxproj) and solution (.sln) files.
  92. 7) Open Visual Studio and select "Open a project or solution".
  93. 8) Navigate to the build directory and select wolfssl.sln to load the
  94. project.
  95. Windows (command line)
  96. ---
  97. 1) Open Command Prompt
  98. 2) Run the Visual Studio batch to setup command line variables, e.g. C:\Program Files (x86)\Microsoft Visual
  99. Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat
  100. 3) Follow steps in "Unix-based Platforms" above.
  101. 15. Building with liboqs for TLS 1.3 [EXPERIMENTAL]
  102. In order be able to use liboqs, you must have it built and installed on your
  103. system. We support liboqs at a specific git commit.
  104. NOTE: Even if you have already installed liboqs, you need to follow these
  105. steps to install liboqs again as we support sphincs variants that are
  106. disabled by default in OQS's fork of OpenSSL.
  107. Here are instructions for obtaining and building liboqs:
  108. $ mkdir ~/oqs
  109. $ cd ~/oqs
  110. $ git clone --single-branch https://github.com/open-quantum-safe/liboqs.git
  111. $ cd liboqs/
  112. $ git checkout 0.8.0
  113. $ mkdir build
  114. $ cd build
  115. $ cmake -DOQS_USE_OPENSSL=0 ..
  116. $ make all
  117. $ sudo make install
  118. And then for building wolfssl, the following is sufficient:
  119. $ cd wolfssl
  120. $ ./autogen.sh (Might not be necessary)
  121. $ ./configure --with-liboqs
  122. $ make all
  123. Execute the following to see the liboqs-related options for KEM groups near
  124. the end of the output of these commands:
  125. $ ./examples/server/server -?
  126. $ ./examples/client/client -?
  127. For a quick start, you can run the client and server like this:
  128. $ ./examples/server/server -v 4 --pqc P521_KYBER_LEVEL5
  129. $ ./examples/client/client -v 4 --pqc P521_KYBER_LEVEL5
  130. Look for the following line in the output of the server and client:
  131. ```
  132. Using Post-Quantum KEM: P521_KYBER_LEVEL5
  133. ```
  134. For authentication, you can generate a certificate chain using a patch on
  135. top of the Open Quantum Safe project's fork of OpenSSL. We support
  136. certificates and keys generated by the patched version which is maintained
  137. in our OSP repo.
  138. Instructions for obtaining and building our patched version of OQS's fork of
  139. OpenSSL can be found at:
  140. https://github.com/wolfSSL/osp/tree/master/oqs/README.md
  141. There are scripts for generating FALCON, Dilithium and SPHINCS+ certificate
  142. chains which can be found in the same directory as the `README.md` file in
  143. the `osp` github repo. Please find instructions on how to generate the keys
  144. and certificates in the `README.md` file.
  145. Once the certificates and keys are generated, copy them from the
  146. to the certs directory of wolfssl. Now you can run the server and client
  147. like this:
  148. $ examples/server/server -v 4 -l TLS_AES_256_GCM_SHA384 \
  149. -A certs/falcon_level5_root_cert.pem \
  150. -c certs/falcon_level1_entity_cert.pem \
  151. -k certs/falcon_level1_entity_key.pem \
  152. --pqc P521_KYBER_LEVEL5
  153. $ examples/client/client -v 4 -l TLS_AES_256_GCM_SHA384 \
  154. -A certs/falcon_level1_root_cert.pem \
  155. -c certs/falcon_level5_entity_cert.pem \
  156. -k certs/falcon_level5_entity_key.pem \
  157. --pqc P521_KYBER_LEVEL5
  158. Congratulations! You have just achieved a fully quantum-safe TLS 1.3
  159. connection!
  160. The following NIST Competition winning algorithms are supported:
  161. - CRYSTALS-KYBER (KEM)
  162. - Dilithium (signature scheme)
  163. - FALCON (signature scheme)
  164. - SPHINCS+ (signature scheme)
  165. The following NIST Competition Round 3 finalist algorithms were supported,
  166. but have been removed after 5.3.3
  167. - SABER (KEM)
  168. - NTRU (KEM)
  169. Links to more information about all of these algorithms can be found here:
  170. https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions
  171. NOTE: The quantum-safe algorithms provided by liboqs are unstandardized and
  172. experimental. It is highly advised that they NOT be used in production
  173. environments. All OIDs and codepoints are temporary and expected to
  174. change in the future. You should have no expectation of backwards
  175. compatibility.
  176. 16. Building with vcpkg
  177. # Building wolfssl - Using vcpkg
  178. You can download and install wolfssl using the [vcpkg](https://github.com/Microsoft/vcpkg):
  179. git clone https://github.com/Microsoft/vcpkg.git
  180. cd vcpkg
  181. ./bootstrap-vcpkg.sh
  182. OR for Windows
  183. bootstrap-vcpkg.bat
  184. ./vcpkg integrate install
  185. ./vcpkg install wolfssl
  186. The wolfssl port in vcpkg is kept up to date by wolfSSL.
  187. We also have vcpkg ports for wolftpm, wolfmqtt and curl.
  188. 17. Building with hash-sigs lib for LMS/HSS support [EXPERIMENTAL]
  189. Using LMS/HSS requires that the hash-sigs lib has been built on
  190. your system. We support hash-sigs lib at this git commit:
  191. b0631b8891295bf2929e68761205337b7c031726
  192. At the time of writing this, this is the HEAD of the master
  193. branch of the hash-sigs project.
  194. Currently the hash-sigs project only builds static libraries:
  195. - hss_lib.a: a single-threaded static lib.
  196. - hss_lib_thread.a: a multi-threaded static lib.
  197. The multi-threaded version will mainly have speedups for key
  198. generation and signing.
  199. Additionally, the hash-sigs project can be modified to build
  200. and install a shared library in /usr/local with either single
  201. or multi-threaded versions. If the shared version has been
  202. built, libhss.so is the assumed name.
  203. wolfSSL supports either option, and by default will look for
  204. hss_lib.a first, and hss_lib_thread.a second, and libhss.so
  205. lastly, in a specified hash-sigs dir.
  206. How to get and build the hash-sigs library:
  207. $ mkdir ~/hash_sigs
  208. $ cd ~/hash_sigs
  209. $ git clone https://github.com/cisco/hash-sigs.git src
  210. $ cd src
  211. $ git checkout b0631b8891295bf2929e68761205337b7c031726
  212. In sha256.h, set USE_OPENSSL to 0:
  213. #define USE_OPENSSL 0
  214. To build the single-threaded version:
  215. $ make hss_lib.a
  216. $ ls *.a
  217. hss_lib.a
  218. To build multi-threaded:
  219. $ make hss_lib_thread.a
  220. $ ls *.a
  221. hss_lib_thread.a
  222. Build wolfSSL with
  223. $ ./configure \
  224. --enable-static \
  225. --disable-shared \
  226. --enable-lms=yes \
  227. --with-liblms=<path to dir containing hss_lib_thread.a>
  228. $ make
  229. Run the benchmark against LMS/HSS with:
  230. $ ./wolfcrypt/benchmark/benchmark -lms_hss