INSTALL 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  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 32bit Visual Studio Solution wolfssl.sln
  17. For a 64bit solution please use wolfssl64.sln
  18. 5. Building with IAR
  19. Please see the README in IDE/IAR-EWARM for detailed instructions
  20. 6. Building with Keil
  21. Please see the Keil Projects in IDE/MDK5-ARM/Projects
  22. 7. Building with Microchip tools
  23. Please see the README in mplabx
  24. 8. Building with Freescale MQX
  25. Please see the README in mqx
  26. 9. Building with Rowley CrossWorks for ARM
  27. Use the CrossWorks project in IDE/ROWLEY-CROSSWORKS-ARM/wolfssl.hzp
  28. There is a README.md in IDE/ROWLEY-CROSSWORKS-ARM with more information
  29. 10. Building with Arduino
  30. Use the script IDE/ARDUINO/wolfssl-arduino.sh to reformat the wolfSSL
  31. library for compatibility with the Arduino IDE. There is a README.md in
  32. IDE/ARDUINO for detailed instructions.
  33. 11. Building for Android with Visual Studio 2017
  34. Please see the README in IDE/VS-ARM.
  35. Use the Visual Studio solution IDE/VS-ARM/wolfssl.sln.
  36. 12. Building for Yocto Project or OpenEmbedded
  37. Please see the README in the "meta-wolfssl" repository. This repository
  38. holds wolfSSL's Yocto and OpenEmbedded layer, which contains recipes
  39. for wolfSSL, wolfSSH, wolfMQTT, wolfTPM, wolfCrypt examples, and OSS
  40. project bbappend files.
  41. https://github.com/wolfssl/meta-wolfssl
  42. The wolfSSL recipe can also be found in the OpenEmbedded
  43. "meta-openembedded/meta-networking/recipes-connectivity" layer:
  44. https://github.com/openembedded/meta-openembedded
  45. 13. Porting to a new platform
  46. Please see section 2.4 in the manual:
  47. http://www.wolfssl.com/yaSSL/Docs-cyassl-manual-2-building-cyassl.html
  48. 14. Building with CMake
  49. Note: Primary development uses automake (./configure). The support for CMake
  50. is still under development.
  51. For configuring wolfssl using CMake, we recommend downloading the CMake
  52. GUI (https://cmake.org/download/). This tool allows you to see all of
  53. wolfssl's configuration variables, set them, and view their descriptions.
  54. Looking at the GUI or CMakeCache.txt (generated after running cmake once) is
  55. the best way to find out what configuration options are available and what
  56. they do. You can also invoke CMake from the GUI, which is described in the
  57. Windows instructions below. For Unix-based systems, we describe the command
  58. line work flow. Regardless of your chosen workflow, cmake will generate
  59. a header options.h in the wolfssl directory that contains the options used
  60. to configure the build.
  61. Unix-based Platforms
  62. ---
  63. 1) Navigate to the wolfssl root directory containing "CMakeLists.txt".
  64. 2) Create a directory called "build" and change into it. This is where
  65. CMake will store build files.
  66. 3) Run `cmake ..` to generate the target build files (e.g. UNIX Makefiles).
  67. To enable or disable features, set them using -D<option>=[yes/no]. For
  68. example, to disable TLS 1.3 support, run cmake .. -DWOLFSSL_TLS13=no
  69. (autoconf equivalent: ./configure --disable-tls13) To enable DSA, run
  70. cmake .. -DWOLFSSL_DSA=yes (autoconf equivalent: ./configure
  71. --enable-dsa). Again, you can find a list of these options and their
  72. descriptions either using the CMake GUI or by looking at CMakeCache.txt.
  73. 5) The build directory should now contain the generated build files. Build
  74. with `cmake --build .`. Under the hood, this runs the target build tool
  75. (by default, make). You can also invoke the target build tool directly
  76. (e.g. make).
  77. To build with debugging use: `cmake .. -DCMAKE_BUILD_TYPE=Debug`.
  78. Windows (Visual Studio)
  79. ---
  80. 1) Go to this page, download the appropriate Windows installer, and install
  81. to get the CMake GUI: https://cmake.org/download/ Native CMake support in
  82. Visual Studio 16 2019 (and possibly older versions) has proven buggy. We
  83. recommend using the CMake GUI in concert with Visual Studio, as described
  84. in these steps.
  85. 2) Open CMake.
  86. 3) Where is the soure code: <root directory of wolfssl containing
  87. CMakeLists.txt>
  88. 4) Where to build the binaries: <build directory, e.g. wolfssl/build>
  89. 5) Hit Configure. CMake runs the code in CMakeLists.txt and builds up an
  90. internal representation of the project.
  91. 6) Hit Generate. CMake generates the build files. For Windows, this will
  92. be Visual Studio project (.vcxproj) and solution (.sln) files.
  93. 7) Open Visual Studio and select "Open a project or solution".
  94. 8) Navigate to the build directory and select wolfssl.sln to load the
  95. project.
  96. Windows (command line)
  97. ---
  98. 1) Open Command Prompt
  99. 2) Run the Visual Studio batch to setup command line variables, e.g. C:\Program Files (x86)\Microsoft Visual
  100. Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat
  101. 3) Follow steps in "Unix-based Platforms" above.
  102. 15. Building with liboqs for TLS 1.3 KEM Groups [EXPERIMENTAL]
  103. In order be able to use liboqs, you must have it built and installed on your
  104. system. For example, on linux, this would be sufficient:
  105. $ cd liboqs
  106. $ mkdir build
  107. $ cd build
  108. $ cmake -DOQS_USE_OPENSSL=0 ..
  109. $ make all
  110. $ sudo make install
  111. And then for building wolfssl, the following is sufficient:
  112. $ cd wolfssl
  113. $ ./autogen.sh (Might not be necessary)
  114. $ ./configure --with-liboqs
  115. $ make all
  116. Execute the following to see the liboqs-related options near the end of the
  117. output of these commands:
  118. $ ./examples/server/server -?
  119. $ ./examples/client/client -?
  120. For a quick start, you can run the client and server like this:
  121. $ ./examples/server/server -v 4 --oqs KYBER512
  122. $ ./examples/client/client -v 4 --oqs KYBER512
  123. Look for the following line in the output of the server and client:
  124. ```
  125. Using OQS KEM: KYBER512
  126. ```
  127. The following NIST Competition Round 3 Finalist KEMs are supported:
  128. - CRYSTALS-KYBER
  129. - SABER
  130. - NTRU
  131. Links to more information about these algorithms can be found here:
  132. https://csrc.nist.gov/projects/post-quantum-cryptography/round-3-submissions
  133. NOTE: The quantum-safe algorithms provided by LIBOQS are unstandardized and
  134. experimental. It is highly advised that they NOT be used in production
  135. environments.