Merge pull request #200 from sebastian-carpenter/wolfssl-manual-review

Wolfssl manual review

Author: cconlon

wolfSSL/src/chapter01.md

@@ -10,8 +10,8 @@ You can find the PDF version of this document [here](https://www.wolfssl.com/doc
 
 There are many reasons to choose wolfSSL as your embedded SSL solution. Some of
 the top reasons include size (typical footprint sizes range from 20-100 kB), support for
-the newest standards (SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3, DTLS 1.0, and
-DTLS 1.2), current and progressive cipher support (including stream ciphers), multi-
+the newest standards (SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, TLS 1.3, DTLS 1.0, DTLS 1.2,
+and DTLS 1.3), current and progressive cipher support (including stream ciphers), multi-
 platform, royalty free, and an OpenSSL compatibility API to ease porting into existing
 applications which have previously used the OpenSSL package. For a complete feature
 list, see [Features Overview](chapter04.md#features-overview).

wolfSSL/src/chapter02.md

@@ -25,7 +25,7 @@ After downloading the ZIP file, unzip the file using the `unzip` command. To use
 
 When building wolfSSL on Linux, \*BSD, OS X, Solaris, or other \*nix-like systems, use the autoconf system. To build wolfSSL you only need to run two commands from the wolfSSL root directory, `./configure` and `make`.
 
-The `./configure` script sets up the build environment and you cab append any number of build options to `./configure`. For a list of available build options, please see [Build Options](#build-options) or run the following the command line to see a list of possible options to pass to the `./configure` script:
+The `./configure` script sets up the build environment and you can append any number of build options to `./configure`. For a list of available build options, please see [Build Options](#build-options) or run the following command to see a list of possible options to pass to the `./configure` script:
 
 ```sh
 ./configure --help
@@ -76,23 +76,23 @@ In addition to the instructions below, you can find instructions and tips for bu
 Solutions are included for Visual Studio 2008 in the root directory of the install. For use with Visual Studio 2010 and later, the existing project files should be able to be converted during the import process.
 
 **Note**:
-If importing to a newer version of VS you will be asked: “Do you want to overwrite the project and its imported property sheets?” You can avoid the following by selecting “No”. Otherwise if you select “Yes”, you will see warnings about `EDITANDCONTINUE` being ignored due to `SAFESEH` specification. You will need to right click on the testsuite, sslSniffer, server, echoserver, echoclient, and client individually and modify their Properties-\>Configuration Properties-\>Linker-\>Advanced (scroll all the way to the bottom in Advanced window). Locate “Image Has Safe Exception Handlers” and click the drop down arrow on the far right. Change this to No (`/SAFESEH:NO`) for each of the aforementioned. The other option is to disable `EDITANDCONTINUE` which, we have found to be useful for debugging purposes and is therefore not recommended.
+If importing to a newer version of VS you will be asked: “Do you want to overwrite the project and its imported property sheets?” You can avoid the following by selecting “No”. Otherwise if you select “Yes”, you will see warnings about `EDITANDCONTINUE` being ignored due to `SAFESEH` specification. You will need to right click on the testsuite, sslSniffer, server, echoserver, echoclient, and client individually and modify their Properties-\>Configuration Properties-\>Linker-\>Advanced (scroll all the way to the bottom in Advanced window). Locate “Image Has Safe Exception Handlers” and click the drop down arrow on the far right. Change this to No (`/SAFESEH:NO`) for each of the aforementioned. The other option is to disable `EDITANDCONTINUE` which, we have found to be useful for debugging purposes and is therefore not recommended for production software.
 
 ### VS 2010
 
 You will need to download Service Pack 1 to build wolfSSL solution once it has been updated. If VS reports a linker error, clean and rebuild the project; the linker error should be taken care of.
 
 ### VS 2013 (64 bit solution)
 
-You will need to download Service Pack 4 to build wolfSSL solution once it has been updated. If VS reports a linker error, clean the project then Rebuild the project and the linker error should be taken care of.
+You will need to download Service Pack 4 to build wolfSSL solution once it has been updated. If VS reports a linker error, clean and rebuild the project; the linker error should be taken care of.
 
 To test each build, choose “Build All” from the Visual Studio menu and then run the testsuite program. To edit build options in the Visual Studio project, select your desired project (wolfssl, echoclient, echoserver, etc.) and browse to the “Properties” panel.
 
-**Note**: After the wolfSSL v3.8.0 release the build preprocessor macros were moved to a centralized file located at `IDE/WIN/user_settings.h`. This file can also be found in the project. To add features such as ECC or ChaCha20/Poly1305 add `#defines` here such as `HAVE_ECC` or `HAVE_CHACHA` / `HAVE_POLY1305`.
+**Note**: After the wolfSSL v3.8.0 release the build preprocessor macros were moved to a centralized file located at `IDE/WIN/user_settings.h`. This file can also be found in the project. To add features such as ECC or ChaCha20/Poly1305, add `#defines` here such as `HAVE_ECC` or `HAVE_CHACHA` / `HAVE_POLY1305`.
 
 ### Cygwin
 
-If building wolfSSL for Windows on a Windows development machine, we recommend using the included Visual Studio project files to build wolfSSL. However if Cygwin is required here is a short guide on how our team achieved a successful build:
+If building wolfSSL for Windows on a Windows development machine, we recommend using the included Visual Studio project files to build wolfSSL. However, if Cygwin is required here is a short guide on how our team achieved a successful build:
 
 1. Go to <https://www.cygwin.com/install.html> and download `setup-x86_64.exe`
 2. Run `setup-x86_64.exe` and install however you choose. Click through the installation menus until you reach the "Select Packages" stage.
@@ -174,7 +174,7 @@ wolfSSL also includes recipes for building wolfSSL on Yocto Linux and OpenEmbedd
     to include the name of the desired recipe(s). An example of this is shown below:
 
     ```sh
-    IMAGE_INSTALL_apped = "wolfssl wolfssh wolfmqtt"
+    IMAGE_INSTALL_append = "wolfssl wolfssh wolfmqtt"
     ```
 
 Once the image has been built, wolfSSL's default location (or related products from recipes) will be the `/usr/lib/` directory.
@@ -239,7 +239,7 @@ The library will output as `libwolfssl_osx.a` or `libwolfssl_ios.a` depending on
 compatibility) headers into an `include` directory located in
 `Build/Products/Debug` or `Build/Products/Release`.
 
-For the library and testsuite to link properly the build location needs to be configured as realitive to workspace.
+For the library and testsuite to link properly the build location needs to be configured relative to the workspace.
 
 1. File -> Workspace Settings (or Xcode -> Preferences -> Locations -> Locations)
 2. Derived Data -> Advanced
@@ -318,7 +318,7 @@ The following defines can be used to remove features from wolfSSL. This can be h
 
 #### NO_WOLFSSL_CLIENT
 
-Removes calls specific to the client and is for a server-only builds. You should only use this if you want to remove a few calls for the sake of size.
+Removes calls specific to the client and is for server-only builds. You should only use this if you want to remove a few calls for the sake of size.
 
 #### NO_WOLFSSL_SERVER
 
@@ -376,7 +376,7 @@ Can be defined when a session cache is not needed. This should reduce memory use
 
 #### NO_TLS
 
-Turns off TLS. We don’t recommend turning off TLS.
+Turns off TLS. We do not recommend turning off TLS.
 
 #### SMALL_SESSION_CACHE
 
@@ -1822,19 +1822,19 @@ There are three math libraries in wolfSSL.
 
 When building wolfSSL, only one of these must be used.
 
-Big Integer Library is the most portable option as it is written in C without any assembly. As such it is not optimized for specific architectures. All math variables are instanciated on the heap; minimal stack usage. Unfortunately, Big Integer Library is not timing resistant.
+Big Integer Library is the most portable option as it is written in C without any assembly. As such it is not optimized for specific architectures. All math variables are instantiated on the heap; minimal stack usage. Unfortunately, Big Integer Library is not timing resistant.
 
-Fast Math Library is a good option. It is implemented using both C and assembly. As such, it has optimizations for specific architectures. All math variables are instanciated on the stack; minimal heap usage. It can be made timing resistant if the `TFM_TIMING_RESISTANT` macro is defined. We have taken it through FIPS 140-2 and 140-3 certifications.
+Fast Math Library is a good option. It is implemented using both C and assembly. As such, it has optimizations for specific architectures. All math variables are instantiated on the stack, leading to less heap usage. It can be made timing resistant if the `TFM_TIMING_RESISTANT` macro is defined. We have taken it through FIPS 140-2 and 140-3 certifications.
 
-Single Precision (SP) Math Library is our recommended library. It is implemented using both C and assembly. As such, it has optimizations for specific architectures. All math variables are instanciated on the stack; minimal heap usage. It is always timing resistant. It is generally optimized for speed at the cost of code size, but is highly configurable to compile out unneeded code. We have taken it through DO-178C certifications.
+Single Precision (SP) Math Library is our recommended library. It is implemented using both C and assembly. As such, it has optimizations for specific architectures. All math variables are instantiated on the stack, leading to less heap usage. It is always timing resistant. It is generally optimized for speed at the cost of code size, but is highly configurable to compile out unneeded code. We have taken it through DO-178C certifications.
 
 #### Big Integer Math Library (Deprecation Planned)
 
 This library is planned to be deprecated and removed from the wolfSSL/wolfCrypt library by the end of 2023. If desired this can be enabled with `--enable-heapmath` or `CFLAGS=-DUSE_INTEGER_HEAP_MATH`.
 
 Forked from public domain LibTomMath library. For more information about LibTomMath, please see <https://www.libtom.net/LibTomMath/>. Please note that our fork is considerably more active and secure than the original public domain code.
 
-This is generally the most portable and generally easiest to get going with. The negatives to the normal big integer library are that it is slower, it uses a lot of heap memory as all memory is allocated from the heap, requires an `XREALLOC()` implementation and is not timing resistant. The implementation can be found in `integer.c`.
+This library is generally the most portable and easiest to get going with. The negatives to the normal big integer library are that it is slower, it uses a lot of heap memory as all memory is allocated from the heap, requires an `XREALLOC()` implementation, and is not timing resistant. The implementation can be found in `integer.c`.
 
 #### Fast Math
 
@@ -1848,7 +1848,7 @@ For FastMath, all memory is allocated on the stack. Because the stack memory usa
 
 On ia32, for example, all of the registers need to be available so high optimization and omitting the frame pointer needs to be taken care of. wolfSSL will add `-O3 -fomit-frame-pointer` to GCC for non debug builds. If you're using a different compiler you may need to add these manually to `CFLAGS` during configure.
 
-OS X will also need `-mdynamic-no-pic` added to `CFLAGS`. In addition, if you're building in shared mode for ia32 on OS X you'll need to pass options to `LDFLAGS` as well:
+OS X will also need `-mdynamic-no-pic` added to `CFLAGS`. In addition, if building in shared mode for ia32 on OS X you'll need to pass options to `LDFLAGS` as well:
 
 ```sh
 LDFLAGS="-Wl,-read_only_relocs,warning"
@@ -3738,7 +3738,7 @@ make
 ```
 
 
-There are fail safes to error out early on wolfCrypt_Init / wolfSSL_Init function calls. One case is if the cryptodev module has not been loaded or does not have the support available for the desired operations. The other case where the init. operation would fail if the NXP HSM was not able to be set up. If the application is failing on initialization, adding --enable-debug to the wolfSSL build and the function call wolfSSL_Debugging_ON() before the initialization of wolfSSL will print out useful debug messages about why it is failing.
+There are fail safes to error out early on wolfCrypt_Init / wolfSSL_Init function calls. One case is if the cryptodev module has not been loaded or does not have the support available for the desired operations. The other case where the init operation would fail is if the NXP HSM was not able to be set up. If the application is failing on initialization, adding --enable-debug to the wolfSSL build and the function call wolfSSL_Debugging_ON() before the initialization of wolfSSL will print out useful debug messages about why it is failing.
 
 
 Example building with debug options turned on

wolfSSL/src/chapter03.md

@@ -2,7 +2,7 @@
 
 ## General Description
 
-wolfSSL, formerly CyaSSL, is about 10 times smaller than yaSSL and up to 20 times smaller than OpenSSL when using the compile options described in [Chapter 2](chapter02.md#building-wolfssl). User benchmarking and feedback also reports dramatically better performance from wolfSSL vs. OpenSSL in the vast majority of standard SSL operations.
+wolfSSL, formerly CyaSSL, is about 10 times smaller than yaSSL, and up to 20 times smaller than OpenSSL when using the compile options described in [Chapter 2](chapter02.md#building-wolfssl). User benchmarking and feedback also reports dramatically better performance from wolfSSL vs. OpenSSL in the vast majority of standard SSL operations.
 
 For instructions on the build process please see [Chapter 2](chapter02.md#building-wolfssl).
 
@@ -218,7 +218,7 @@ wolfSSL_connect avg took:  296.417 milliseconds
 
 If you'd like to change the default host from localhost, or the default port from 11111, you can change these settings in `/wolfssl/test.h`. The variables wolfSSLIP and wolfSSLPort control these settings. Re-build all of the examples including testsuite when changing these settings otherwise the test programs won't be able to connect to each other.
 
-By default, the wolfSSL example client tries to connect to the specified server using TLS 1.2. The user is able to change the SSL/TLS version which the client uses by using the `-v` command line option. The following values are available for this option:
+By default, the wolfSSL example client tries to connect to the specified server using TLS 1.2. The user is able to change the SSL/TLS version which the client uses by passing the `-v` command line option. The following values are available for this option:
 
 * `-v 0` - SSL 3.0 (disabled by default)
 * `-v 1` - TLS 1.0
@@ -462,7 +462,7 @@ Enabling this define will switch the benchmark application from loading test key
 
 #### USE_CERT_BUFFERS_2048
 
-Enabling this define is similar to [`USE_CERT_BUFFERS_1024`](#use_cert_buffers_1024) accept that 2048-bit key and certificate buffers are used instead of 1024-bit ones. This define is useful when the processor is fast enough to do
+Enabling this define is similar to [`USE_CERT_BUFFERS_1024`](#use_cert_buffers_1024) except that 2048-bit key and certificate buffers are used instead of 1024-bit ones. This define is useful when the processor is fast enough to do
 2048-bit public key operations but when there is no filesystem available to load keys and certificates from files.
 
 ## Changing a Client Application to Use wolfSSL
@@ -475,7 +475,7 @@ This section will explain the basic steps needed to add wolfSSL to a client appl
     #include <wolfssl/ssl.h>
     ```
 
-2. Initialize wolfSSL and the `WOLFSSL_CTX`. You can use one `WOLFSSL_CTX` no matter how many WOLFSSL objects you end up creating. Basically you'll just need to load CA certificates to verify the server you are connecting to. Basic initialization looks like:
+2. Initialize wolfSSL and the `WOLFSSL_CTX`. You can use one `WOLFSSL_CTX` no matter how many WOLFSSL objects you end up creating. You'll just need to load CA certificates to verify the server you are connecting to. Basic initialization looks like:
 
     ```c
     wolfSSL_Init();