Browse Source

Cleanup markdown documentation

* Add syntax highlighting where appropriate
* Fix some markdown compliance issues
* Add some links for things
* Add some inline code quoting
* Fix some headings
* Fix copyright date in doxygen html output
Andrew Hutchings 2 years ago
parent
commit
11e3f867b0

+ 20 - 24
IDE/Espressif/ESP-IDF/README_32se.md

@@ -1,35 +1,31 @@
 # DEMO program with ATECC608A on ESP-WROOM-32SE
 ## Overview
- Running demo programs with ATECC608A on 32SE by setting *WOLFSSL_ESPWROOM32SE* definition
+ Running demo programs with ATECC608A on 32SE by setting `WOLFSSL_ESPWROOM32SE` definition
 
 Including the following examples:
 
-* simple tls_client/tls_server
+* simple `tls_client`/`tls_server`
 * crypt benchmark
 
- The *user_settings.h* file enables some of the hardened settings. 
- 
+ The `user_settings.h` file enables some of the hardened settings.
+
 ## Requirements
- 1. ESP-IDF development framework  
-    [https://docs.espressif.com/projects/esp-idf/en/latest/get-started/]
+1. ESP-IDF development framework: https://docs.espressif.com/projects/esp-idf/en/latest/get-started/
+
+2. Microchip CryptoAuthentication Library: https://github.com/MicrochipTech/cryptoauthlib
 
- 2. Microchip CryptoAuthentication Library  
-    [https://github.com/MicrochipTech/cryptoauthlib]
-    
 ## Setup
- 1. wolfSSL under ESP-IDF. Please see [README.md](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md)
- 2. CryptoAuthentication Library under ESP-IDF. Please see [README.md](https://github.com/miyazakh/cryptoauthlib_esp_idf/blob/master/README.md)
- 
- 3. Uncomment out #define WOLFSSL_ESPWROOM32SE in /path/to/wolfssl/wolfssl/wolfcrypt/settings.h
- 
-    Note : Need to enable WOLFSSL_ESPIDF  
-    Note : crypt test will fail if enabled WOLFSSL_ESPWROOM32SE
- 
+1. wolfSSL under ESP-IDF. Please see [README.md](https://github.com/wolfSSL/wolfssl/blob/master/IDE/Espressif/ESP-IDF/README.md)
+2. CryptoAuthentication Library under ESP-IDF. Please see [README.md](https://github.com/miyazakh/cryptoauthlib_esp_idf/blob/master/README.md)
+3. Uncomment out `#define WOLFSSL_ESPWROOM32SE` in `/path/to/wolfssl/wolfssl/wolfcrypt/settings.h`
+    * **Note:** Need to enable `WOLFSSL_ESPIDF`
+    * **Note:** crypt test will fail if enabled `WOLFSSL_ESPWROOM32SE`
+
 ## Configuration
- 1. The *user_settings.h* can be found in /path/to/esp-idf/components/wolfssl/include/user_settings.h
+1. The `user_settings.h` can be found in `/path/to/esp-idf/components/wolfssl/include/user_settings.h`
 
 ## Build examples
- 1. See README in each example folder
+1. See `README` in each example folder
 
 ## Benchmark
 w/o atecc608a
@@ -48,11 +44,11 @@ ECDSA    256 verify         14 ops took 1.079 sec, avg 77.071 ms, 12.975 ops/sec
 ```
 
 ## Support
- For question please email [support@wolfssl.com]
+For question please email [support@wolfssl.com](mailto:support@wolfssl.com)
+
+Note: This is tested with the following condition:
 
- Note: This is tested with the following condition:
- 
-- Model    : ESP32-WROOM-32SE  
-- ESP-IDF  : v3.3-beta1-39-g6cb37ecc5(commit hash : 6cb37ecc5)  
+- Model    : ESP32-WROOM-32SE
+- ESP-IDF  : v3.3-beta1-39-g6cb37ecc5(commit hash : 6cb37ecc5)
 - CryptAuthLib: commit hash : c6b176e
 - OS       : Ubuntu 18.04.1 LTS (Bionic Beaver)

+ 107 - 77
IDE/WORKBENCH/README.md

@@ -7,37 +7,43 @@ Project and then selecting VxWorks Image Project.
 Choose the path to the wolfSSL library here. Uncheck everything except the examples,
 src and wolfcrypt directories. Uncheck the following:
 
-        wolfcrypt/src/aes_asm.asm
-        wolfcrypt/src/aes_asm.s
-        examples/echoclient/
-        examples/echoserver/
-        wolfcrypt/user-crypto
-
+    ```
+    wolfcrypt/src/aes_asm.asm
+    wolfcrypt/src/aes_asm.s
+    examples/echoclient/
+    examples/echoserver/
+    wolfcrypt/user-crypto
+    ```
     Uncheck "Create top level folder". Click Finish.
 
 3. To include the path to the wolfSSL header files, right click on the project
 and go to Properties > Build Properties and select the "Paths" tab. Click "Add"
 then "Browse" and select:
 
-        <path_to_wolfssl>/
-
+    ```
+    <path_to_wolfssl>/
+    ```
     Click "OK" then "OK" again.
 
-4. In ```<path_to_wolfssl>/wolfssl/wolfcrypt/settings.h```, uncomment
+4. In `<path_to_wolfssl>/wolfssl/wolfcrypt/settings.h`, uncomment
 
-        #define WOLFSSL_VXWORKS
+    ```c
+    #define WOLFSSL_VXWORKS
+    ```
 
-Note: pthreads defined by default
+    **Note:** pthreads defined by default
 
-5. If using the VxWorks simulator add the following to EXTRA\_DEFINE:
+5. If using the VxWorks simulator add the following to `EXTRA_DEFINE`:
 
-        -DVXWORKS_SIM /* only if using the VxWorks simulator */
+    ```
+    -DVXWORKS_SIM /* only if using the VxWorks simulator */
+    ```
 
     This can be done by right clicking on the project in Project Explorer, going to
     Build Properties and selecting the "Variables" tab. Highlight EXTRA\_DEFINE and
     click "Edit". Enter the above define to the end of the line.
 
-6. Copy the certs folder in ```<path_to_wolfssl>/``` to the Wind River Workbench
+6. Copy the certs folder in `<path_to_wolfssl>/` to the Wind River Workbench
 workspace folder. This is where the simulator looks for the filesystem.
 
 7. Include Entropy:
@@ -59,83 +65,99 @@ and output the status for each as a success or failure. The benchmark applicatio
 
 1. Include the following at the top of usrAppInit.c:
 
-        #include <wolfcrypt/test/test.h>
-        #include <wolfssl/ssl.h>
-        #include <wolfssl/wolfcrypt/settings.h>
-        #include <wolfssl/test.h>
-        extern int benchmark_test(void* args);
-
-2. In usrAppInit.c, make a call to the wolfCrypt test and benchmark applications
-by adding the following to the usrAppInit() function:
-
-        typedef struct func_args {
-	        int    argc;
-	        char** argv;
-	        int    return_code;
-	        tcp_ready* signal;
-	        callback_functions *callbacks;
-	    } func_args;
-
-	    func_args args;
-
-	    wolfcrypt_test(&args);
-	    benchmark_test(&args);
+    ```c
+    #include <wolfcrypt/test/test.h>
+    #include <wolfssl/ssl.h>
+    #include <wolfssl/wolfcrypt/settings.h>
+    #include <wolfssl/test.h>
+    extern int benchmark_test(void* args);
+    ```
+2. In `usrAppInit.c`, make a call to the wolfCrypt test and benchmark applications
+by adding the following to the `usrAppInit()` function:
+
+    ```c
+    typedef struct func_args {
+        int    argc;
+        char** argv;
+        int    return_code;
+        tcp_ready* signal;
+        callback_functions *callbacks;
+    } func_args;
+
+    func_args args;
+
+    wolfcrypt_test(&args);
+    benchmark_test(&args);
+    ```
 
 3. Right click on the project and select "Build Project".
 
-4. To run the VxWorks simulator, click the dropdown list next to "VxWorks Simulator" at the top of Workbench and go to "Open Connection Details". Add the correct Kernel Image file. This will be located in ```workspace/<project_name>/default/vxWorks```. Click Apply. Start the simulator by clicking the green, "Connect 'VxWorks Simulator'" button to the right of the "VxWorks Simulator" dropdown list. Verify in the simulator terminal that all wolfCrypt tests pass.
+4. To run the VxWorks simulator, click the dropdown list next to "VxWorks Simulator" at the top of Workbench and go to "Open Connection Details". Add the correct Kernel Image file. This will be located in `workspace/<project_name>/default/vxWorks`. Click Apply. Start the simulator by clicking the green, "Connect 'VxWorks Simulator'" button to the right of the "VxWorks Simulator" dropdown list. Verify in the simulator terminal that all wolfCrypt tests pass.
 
 ##### 2.2 Example Client
-The wolfSSL example client.c file can be found in ```<path_to_wolfssl>/wolfssl/examples/client```.
+The wolfSSL example client.c file can be found in `<path_to_wolfssl>/wolfssl/examples/client`.
 
-1. Add the following include to usrAppInit.c:
+1. Add the following include to `usrAppInit.c`:
 
-        #include <examples/client/client.h>
+    ```c
+    #include <examples/client/client.h>
+    ```
 
-2. In usrAppInit.c, include the func\_args as described in the Test Application
+2. In `usrAppInit.c`, include the `func_args` as described in the Test Application
 section, and add a call to the client function:
 
-        client_test(&args);
+    ```c
+    client_test(&args);
+    ```
 
-3. The char* host in ```examples/client/client.c``` will need to be changed to the IP address to connect to. For example:
+3. The `char*` host in `examples/client/client.c` will need to be changed to the IP address to connect to. For example:
 
-        char* host = "192.168.15.1";
+    ```c
+    char* host = "192.168.15.1";
+    ```
 
 4. Right click on the project and select "Build Project".
 
 5. If using the VxWorks Simulator, localhost will not work. NAT should be selected in the Simulator Connection Advanced setup. To do this, click the dropdown button next to VxWorks Simulator at the top of Workbench and select "Open Connection Details". Make sure the correct kernel image file is selected for you project as stated in section 3.1 step 4. Then click Advanced and select NAT as the Network Config. Click OK and Apply.
 
-6. There is an example server in ```<path_to_wolfssl>``` that can be used for testing the client. wolfSSL will first need to be built. Follow the instructions [here](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) to do so. See the [wolfSSL manual]( https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-3-getting-started.html) for instructions on setting up the example server. From within ```<path_to_wolfssl>/wolfssl```, the following command can be used to run the server on the host machine:
+6. There is an example server in `<path_to_wolfssl>` that can be used for testing the client. wolfSSL will first need to be built. Follow the instructions [here](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) to do so. See the [wolfSSL manual]( https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-3-getting-started.html) for instructions on setting up the example server. From within `<path_to_wolfssl>/wolfssl`, the following command can be used to run the server on the host machine:
 
-        ./examples/server/server -d -b
+    ```sh
+    ./examples/server/server -d -b
+    ```
 
 7. Start the example client in Workbench by following step 3 in section 3.1.
 
 8. The following output should be expected in the simulator terminal:
 
-        SSL version is TLSv1.2
-        SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-        Server response: I hear you fa shizzle!
+    ```
+    SSL version is TLSv1.2
+    SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
+    Server response: I hear you fa shizzle!
+    ```
 
 ##### 2.3 Example Server
 The example server requires more configuration than the client if using the
 VxWorks simulator.
 
-Note: The wolfSSL example server and client cannot run at the same time on the VxWorks simulator. Either remove or comment out the ```client_test(&args);``` line.
-
-1. Add the following include to usrAppInit.c:
+Note: The wolfSSL example server and client cannot run at the same time on the VxWorks simulator. Either remove or comment out the `client_test(&args);` line.
 
-        #include </examples/server/server.h>
+1. Add the following include to `usrAppInit.c`:
 
-2. In usrAppInit.c, after the ```func_args args;``` call, add:
+    ```c
+    #include </examples/server/server.h>
+    ```
 
-        tcp_ready ready;
-	    ready.ready = 0;
-	    ready.port = 0;
-	    args.signal = &ready;
+2. In `usrAppInit.c`, after the `func_args args;` call, add:
 
-        server_test(&args);
+    ```c
+    tcp_ready ready;
+    ready.ready = 0;
+    ready.port = 0;
+    args.signal = &ready;
 
+    server_test(&args);
+    ```
 3. Right click on the project and select "Build Project".
 
 4. Start the server and complete the following:
@@ -144,39 +166,47 @@ Note: The wolfSSL example server and client cannot run at the same time on the V
     192.168.200.1 as the IP address. To connect to the server running on the VxWorks Simulator, enter these commands
     into the host machine's terminal from any directory (for Ubuntu 14.04):
 
-        sudo openvpn --mktun --dev tap0
+    ```sh
+    sudo openvpn --mktun --dev tap0
+    ```
 
-    Note: openvpn may need to be installed first.
+    **Note:** openvpn may need to be installed first.
 
     In Wind River directory on the host machine:
 
-        sudo vxworks-7/host/x86-linux2/bin/vxsimnetd
+    ```sh
+    sudo vxworks-7/host/x86-linux2/bin/vxsimnetd
+    ```
 
     This will start the vxsimnetd application. Leave it running in the background.
 
-5. There is an example client in ```<path_to_wolfssl>/wolfssl/examples``` . Again, wolfSSL will first need to be built. Follow the instructions [here](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) to do so. See the [wolfSSL manual]( https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-3-getting-started.html) for instructions on how to set up the client. From within ```<path_to_wolfssl>/wolfssl``` , the following command can be used to run the client on the host machine:
+5. There is an example client in `<path_to_wolfssl>/wolfssl/examples` . Again, wolfSSL will first need to be built. Follow the instructions [here](https://www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-2-building-wolfssl.html) to do so. See the [wolfSSL manual]( https://wolfssl.com/wolfSSL/Docs-wolfssl-manual-3-getting-started.html) for instructions on how to set up the client. From within `<path_to_wolfssl>/wolfssl` , the following command can be used to run the client on the host machine:
 
-        ./examples/client/client -h 192.168.200.1
+    ```sh
+    ./examples/client/client -h 192.168.200.1
+    ```
 
 6. The following output should be expected in the simulator terminal:
 
-        SSL version is TLSv1.2
-        SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-        Client message: hello wolfssl!
+    ```
+    SSL version is TLSv1.2
+    SSL cipher suite is TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
+    Client message: hello wolfssl!
+    ```
 
 #### 3 Necessary Files if Using VxWorks Simulator
 The following files are required to replicate this build:
-* vxsim\_linux\_1\_0\_2\_2 (directory)
-* compilers/gnu-4.8.1.5/include/c++/4.8
-* compilers/gnu-4.8.1.5/include/c++/4.8/i586-wrs-vxworks
-* compilers/gnu-4.8.1.5/lib/gcc/i586-wrs-vxworks/4.8.1/include
-* compilers/gnu-4.8.1.5/lib/gcc/i586-wrs-vxworks/4.8.1/include-fixed
-* vsb\_vxsim\_linux/share/h
-* vsb\_vxsim\_linux/krnl/h/system
-* vsb\_vxsim\_linux/krnl/h/public
-* vsb\_vxsim\_linux/krnl/configlette
-* vsb\_vxsim\_linux/h
+* `vxsim_linux_1_0_2_2` (directory)
+* `compilers/gnu-4.8.1.5/include/c++/4.8`
+* `compilers/gnu-4.8.1.5/include/c++/4.8/i586-wrs-vxworks`
+* `compilers/gnu-4.8.1.5/lib/gcc/i586-wrs-vxworks/4.8.1/include`
+* `compilers/gnu-4.8.1.5/lib/gcc/i586-wrs-vxworks/4.8.1/include-fixed`
+* `vsb_vxsim_linux/share/h`
+* `vsb_vxsim_linux/krnl/h/system`
+* `vsb_vxsim_linux/krnl/h/public`
+* `vsb_vxsim_linux/krnl/configlette`
+* `vsb_vxsim_linux/h`
 
 Note: This project was tested with a pre-built image in the VxWorks distribution
-called vip\_vxsim\_linux\_gnu.
+called `vip_vxsim_linux_gnu`.
 

+ 124 - 121
README.md

@@ -35,75 +35,78 @@ of the wolfSSL manual.
 
 ## Notes, Please Read
 
-**Note 1)**
+### Note 1
 wolfSSL as of 3.6.6 no longer enables SSLv3 by default.  wolfSSL also no longer
 supports static key cipher suites with PSK, RSA, or ECDH. This means if you
 plan to use TLS cipher suites you must enable DH (DH is on by default), or
 enable ECC (ECC is on by default), or you must enable static key cipher suites
 with one or more of the following defines:
 
-    WOLFSSL_STATIC_DH
-    WOLFSSL_STATIC_RSA
-    WOLFSSL_STATIC_PSK
-
+```
+WOLFSSL_STATIC_DH
+WOLFSSL_STATIC_RSA
+WOLFSSL_STATIC_PSK
+```
 Though static key cipher suites are deprecated and will be removed from future
 versions of TLS.  They also lower your security by removing PFS.
 
-When compiling ssl.c, wolfSSL will now issue a compiler error if no cipher
+When compiling `ssl.c`, wolfSSL will now issue a compiler error if no cipher
 suites are available. You can remove this error by defining
-```WOLFSSL_ALLOW_NO_SUITES``` in the event that you desire that, i.e., you're
+`WOLFSSL_ALLOW_NO_SUITES` in the event that you desire that, i.e., you're
 not using TLS cipher suites.
 
-**Note 2)**
+### Note 2
 wolfSSL takes a different approach to certificate verification than OpenSSL
 does. The default policy for the client is to verify the server, this means
 that if you don't load CAs to verify the server you'll get a connect error,
 no signer error to confirm failure (-188).
 
-If you want to mimic OpenSSL behavior of having SSL\_connect succeed even if
+If you want to mimic OpenSSL behavior of having `SSL_connect` succeed even if
 verifying the server fails and reducing security you can do this by calling:
 
-    wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0);
+```c
+wolfSSL_CTX_set_verify(ctx, SSL_VERIFY_NONE, 0);
+```
 
-before calling wolfSSL\_new();. Though it's not recommended.
+before calling `wolfSSL_new();`. Though it's not recommended.
 
-**Note 3)**
+### Note 3
 The enum values SHA, SHA256, SHA384, SHA512 are no longer available when
-wolfSSL is built with --enable-opensslextra (```OPENSSL_EXTRA```) or with the
-macro ```NO_OLD_SHA_NAMES```. These names get mapped to the OpenSSL API for a
-single call hash function. Instead the name WC_SHA, WC_SHA256, WC_SHA384 and
-WC_SHA512 should be used for the enum name.
+wolfSSL is built with `--enable-opensslextra` (`OPENSSL_EXTRA`) or with the
+macro `NO_OLD_SHA_NAMES`. These names get mapped to the OpenSSL API for a
+single call hash function. Instead the name `WC_SHA`, `WC_SHA256`, `WC_SHA384` and
+`WC_SHA512` should be used for the enum name.
 
 # wolfSSL Release 4.8.1 (July 16, 2021)
-Release 4.8.1 of wolfSSL embedded TLS has an OCSP vulnerability fix:
+[Release 4.8.1](https://github.com/wolfSSL/wolfssl/releases/tag/v4.8.1-stable) of wolfSSL embedded TLS has an OCSP vulnerability fix:
 
 ### Vulnerabilities
 * [High] OCSP verification issue when response is for a certificate with no relation to the chain in question BUT that response contains the NoCheck extension which effectively disables ALL verification of that one cert. Users who should upgrade to 4.8.1 are TLS client users doing OCSP, TLS server users doing mutual auth with OCSP, and CertManager users doing OCSP independent of TLS. Thanks to Jan Nauber, Marco Smeets, Werner Rueschenbaum and Alissa Kim of Volkswagen Infotainment for the report.
 
 # wolfSSL Release 4.8.0 (July 09, 2021)
-Release 4.8.0 of wolfSSL embedded TLS has bug fixes and new features including:
+[Release 4.8.0](https://github.com/wolfSSL/wolfssl/releases/tag/v4.8.0-stable) of wolfSSL embedded TLS has bug fixes and new features including:
 
 ### Vulnerabilities
-* [Low] CVE-2021-37155: OCSP request/response verification issue. In the case that the serial number in the OCSP request differs from the serial number in the OCSP response the error from the comparison was not resulting in a failed verification. We recommend users that have wolfSSL version 4.6.0 and 4.7.0 with OCSP enabled update their version of wolfSSL. Version 4.5.0 and earlier are not affected by this report. Thanks to Rainer Mueller-Amersdorffer, Roee Yankelevsky, Barak Gutman, Hila Cohen and Shoshi Berko (from CYMOTIVE Technologies and CARIAD) for the report.
-* [Low] CVE-2021-24116: Side-Channel cache look up vulnerability in base64 PEM decoding for versions of wolfSSL 4.5.0 and earlier. Versions 4.6.0 and up contain a fix and do not need to be updated for this report. If decoding a PEM format private key using version 4.5.0 and older of wolfSSL then we recommend updating the version of wolfSSL used. Thanks to Florian Sieck, Jan Wichelmann, Sebastian Berndt and Thomas Eisenbarth for the report.
+* \[Low\] [CVE-2021-37155](https://nvd.nist.gov/vuln/detail/CVE-2021-37155): OCSP request/response verification issue. In the case that the serial number in the OCSP request differs from the serial number in the OCSP response the error from the comparison was not resulting in a failed verification. We recommend users that have wolfSSL version 4.6.0 and 4.7.0 with OCSP enabled update their version of wolfSSL. Version 4.5.0 and earlier are not affected by this report. Thanks to Rainer Mueller-Amersdorffer, Roee Yankelevsky, Barak Gutman, Hila Cohen and Shoshi Berko (from CYMOTIVE Technologies and CARIAD) for the report.
+* \[Low\] [CVE-2021-24116](https://nvd.nist.gov/vuln/detail/CVE-2021-24116): Side-Channel cache look up vulnerability in base64 PEM decoding for versions of wolfSSL 4.5.0 and earlier. Versions 4.6.0 and up contain a fix and do not need to be updated for this report. If decoding a PEM format private key using version 4.5.0 and older of wolfSSL then we recommend updating the version of wolfSSL used. Thanks to Florian Sieck, Jan Wichelmann, Sebastian Berndt and Thomas Eisenbarth for the report.
 
 ### New Feature Additions
 ###### New Product
-* Added wolfSentry build with --enable-wolfsentry and tie-ins to wolfSSL code for use with wolfSentry
+* Added wolfSentry build with `--enable-wolfsentry` and tie-ins to wolfSSL code for use with wolfSentry
 
 ###### Ports
 * QNX CAAM driver added, supporting ECC black keys, CMAC, BLOBs, and TRNG use
-*  _WIN32_WCE wolfCrypt port added
-* INTIME_RTOS directory support added
+*  `_WIN32_WCE` wolfCrypt port added
+* `INTIME_RTOS` directory support added
 * Added support for STM32G0
-* Renesas RX: Added intrinsics for rot[rl], revl (thanks @rliebscher)
+* Renesas RX: Added intrinsics for rot\[rl\], revl (thanks @rliebscher)
 * Added support for running wolfcrypt/test/testwolfcrypt on Dolphin emulator to test DEVKITPRO port
 * Zephyr project port updated to latest version 2.6.X
 
 ###### ASN1 and PKCS
 * Storing policy constraint extension from certificate added
-* Added support for NID_favouriteDrink pilot
-* Added the API function wc_EncryptPKCS8Key to handle encrypting a DER, PKCS#8-formatted key
+* Added support for `NID_favouriteDrink` pilot
+* Added the API function `wc_EncryptPKCS8Key` to handle encrypting a DER, PKCS#8-formatted key
 
 ###### Compatibility Layer Additions
 * Open Source PORTS Added/Updated
@@ -111,54 +114,54 @@ Release 4.8.0 of wolfSSL embedded TLS has bug fixes and new features including:
     - OpenLDAP
     - socat-1.7.4.1
     - Updated QT port for 5.15.2
-* Changes to extend set_cipher_list() compatibility layer API to have set_ciphersuites compatibility layer API capability
+* Changes to extend `set_cipher_list()` compatibility layer API to have `set_ciphersuites` compatibility layer API capability
 * Added more support for SHA3 in the EVP layer
 * API Added
-    - MD5/MD5_Transform
-    - SHA/SHA_Transform/SHA1_Transform
-    - SHA224/SHA256_Transform/SHA512_Transform
-    - SSL_CTX_get0_param/SSL_CTX_set1_param
-    - X509_load_crl_file
-    - SSL_CTX_get_min_proto_version
-    - EVP_ENCODE_CTX_new
-    - EVP_ENCODE_CTX_free
-    - EVP_EncodeInit
-    - EVP_EncodeUpdate
-    - EVP_EncodeFinal
-    - EVP_DecodeInit
-    - EVP_DecodeUpdate
-    - EVP_DecodeFinal
-    - EVP_PKEY_print_public
-    - BIO_tell
-    - THREADID_current
-    - THREADID_hash
-    - SSL_CTX_set_ecdh_auto
-    - RAND_set_rand_method()
-    - X509_LOOKUP_ctrl()
-    - RSA_bits
-    - EC_curve_nist2nid
-    - EC_KEY_set_group
-    - SSL_SESSION_set_cipher
-    - SSL_set_psk_use_session_callback
-    - EVP_PKEY_param_check
-    - DH_get0_pqg
-    - CRYPTO_get_ex_new_index
-    - SSL_SESSION_is_resumable
-    - SSL_CONF_cmd
-    - SSL_CONF_CTX_finish
-    - SSL_CTX_keylog_cb_func
-    - SSL_CTX_set_keylog_callback
-    - SSL_CTX_get_keylog_callback
+    - `MD5`/`MD5_Transform`
+    - `SHA`/`SHA_Transform`/`SHA1_Transform`
+    - `SHA224`/`SHA256_Transform`/`SHA512_Transform`
+    - `SSL_CTX_get0_param`/`SSL_CTX_set1_param`
+    - `X509_load_crl_file`
+    - `SSL_CTX_get_min_proto_version`
+    - `EVP_ENCODE_CTX_new`
+    - `EVP_ENCODE_CTX_free`
+    - `EVP_EncodeInit`
+    - `EVP_EncodeUpdate`
+    - `EVP_EncodeFinal`
+    - `EVP_DecodeInit`
+    - `EVP_DecodeUpdate`
+    - `EVP_DecodeFinal`
+    - `EVP_PKEY_print_public`
+    - `BIO_tell`
+    - `THREADID_current`
+    - `THREADID_hash`
+    - `SSL_CTX_set_ecdh_auto`
+    - `RAND_set_rand_method()`
+    - `X509_LOOKUP_ctrl()`
+    - `RSA_bits`
+    - `EC_curve_nist2nid`
+    - `EC_KEY_set_group`
+    - `SSL_SESSION_set_cipher`
+    - `SSL_set_psk_use_session_callback`
+    - `EVP_PKEY_param_check`
+    - `DH_get0_pqg`
+    - `CRYPTO_get_ex_new_index`
+    - `SSL_SESSION_is_resumable`
+    - `SSL_CONF_cmd`
+    - `SSL_CONF_CTX_finish`
+    - `SSL_CTX_keylog_cb_func`
+    - `SSL_CTX_set_keylog_callback`
+    - `SSL_CTX_get_keylog_callback`
 
 ###### Misc.
-* Added wolfSSL_CTX_get_TicketEncCtx getter function to return the ticket encryption ctx value
-* Added wc_AesKeyWrap_ex and wc_AesKeyUnWrap_ex APIs to accept an Aes object to use for the AES operations
-* Added implementation of AES-GCM streaming (--enable-aesgcm-stream)
-* Added deterministic generation of k with ECC following RFC6979 when the macro WOLFSL_ECDSA_DETERMINISTIC_K is defined and wc_ecc_set_deterministic function is called
-* Implemented wc_DsaParamsDecode and wc_DsaKeyToParamsDer
+* Added `wolfSSL_CTX_get_TicketEncCtx` getter function to return the ticket encryption ctx value
+* Added `wc_AesKeyWrap_ex` and `wc_AesKeyUnWrap_ex` APIs to accept an `Aes` object to use for the AES operations
+* Added implementation of AES-GCM streaming (`--enable-aesgcm-stream`)
+* Added deterministic generation of k with ECC following RFC6979 when the macro `WOLFSL_ECDSA_DETERMINISTIC_K` is defined and `wc_ecc_set_deterministic` function is called
+* Implemented `wc_DsaParamsDecode` and `wc_DsaKeyToParamsDer`
 * Asynchronous support for TLS v1.3 TLSX ECC/DH key generation and key agreement
 * Added crypto callback support for Ed/Curve25519 and SHA2-512/384
-* TLS 1.3 wolfSSL_key_update_response function added to see if a update response is needed
+* TLS 1.3 `wolfSSL_key_update_response` function added to see if a update response is needed
 
 ### Fixes
 * Fix for detecting extra unused bytes that are in an ASN1 sequence appended to the end of a valid ECC signature
@@ -168,13 +171,13 @@ Release 4.8.0 of wolfSSL embedded TLS has bug fixes and new features including:
 * Fix for corner TLS downgrade case where a TLS 1.3 setup that allows for downgrades but has TLS 1.3 set as the minimum version would still downgrade to TLS 1.2
 
 ###### PKCS7 (Multiple fixes throughout regarding memory leaks with SMIME and heap buffer overflows due to streaming functionality)
-* Fix PKCS7 dynamic content save/restore in PKCS7_VerifySignedData
-* Fix for heap buffer overflow on compare with wc_PKCS7_DecryptKtri
-* Fix for heap buffer overflow with wc_PKCS7_VerifySignedData
-* Fix for heap buffer overflow with wc_PKCS7_DecodeEnvelopedData
-* Check size of public key used with certificate passed into wc_PKCS7_InitWithCert before XMEMCPY to avoid overflow
-* Fix for heap buffer overflow fix for wolfSSL_SMIME_read_PKCS7
-* Fix to cleanly free memory in error state with wolfSSL_SMIME_read_PKCS7
+* Fix PKCS7 dynamic content save/restore in `PKCS7_VerifySignedData`
+* Fix for heap buffer overflow on compare with `wc_PKCS7_DecryptKtri`
+* Fix for heap buffer overflow with `wc_PKCS7_VerifySignedData`
+* Fix for heap buffer overflow with `wc_PKCS7_DecodeEnvelopedData`
+* Check size of public key used with certificate passed into `wc_PKCS7_InitWithCert` before `XMEMCPY` to avoid overflow
+* Fix for heap buffer overflow fix for `wolfSSL_SMIME_read_PKCS7`
+* Fix to cleanly free memory in error state with `wolfSSL_SMIME_read_PKCS7`
 * SMIME error checking improvements and canonicalize multi-part messages before hashing
 
 ###### DTLS Fixes
@@ -193,38 +196,38 @@ Release 4.8.0 of wolfSSL embedded TLS has bug fixes and new features including:
 * Espressif ESP32 SHA_CTX macro conflict resolved
 
 ###### Math Library Fixes
-* For platforms that support limits.h or windows make sure both SIZEOF_LONG_LONG and SIZEOF_LONG are set to avoid issues with CTC_SETTINGS
+* For platforms that support limits.h or windows make sure both `SIZEOF_LONG_LONG` and `SIZEOF_LONG` are set to avoid issues with `CTC_SETTINGS`
 * SP C 32/64: fix corner cases around subtraction affecting RSA PSS use
-* Fix to return the error code from sp_cond_swap_ct when malloc fails
-* Fix potential memory leak with small stack in the function fp_gcd
+* Fix to return the error code from `sp_cond_swap_ct` when `malloc` fails
+* Fix potential memory leak with small stack in the function `fp_gcd`
 * Static Analysis Fixes
 * Fixes made from Coverity analysis including:
 * Cleanups for some return values,
-* Fix for leak with wolfSSL_a2i_ASN1_INTEGER
-* Sanity check on length in wolfSSL_BN_rand
-* Sanity check size in TLSX_Parse catching a possible integer overflow
-* Fixes found with -fsanitize=undefined testing
-* Fix null dereferences or undefined memcpy calls
-* Fix alignment in myCryptoDevCb
+* Fix for leak with `wolfSSL_a2i_ASN1_INTEGER`
+* Sanity check on length in `wolfSSL_BN_rand`
+* Sanity check size in `TLSX_Parse` catching a possible integer overflow
+* Fixes found with `-fsanitize=undefined` testing
+* Fix null dereferences or undefined `memcpy` calls
+* Fix alignment in `myCryptoDevCb`
 * Fix default DTLS context assignment
 * Added align configure option to force data alignment
 
 ###### Misc.
-* Fix for wolfSSL_ASN1_TIME_adj set length
-* Fix for freeing structure on error case in the function AddTrustedPeer
-* Return value of SSL_read when called after bidirectional shutdown
-* Fix for build options ./configure --enable-dtls --disable-asn
+* Fix for `wolfSSL_ASN1_TIME_adj` set length
+* Fix for freeing structure on error case in the function `AddTrustedPeer`
+* Return value of `SSL_read` when called after bidirectional shutdown
+* Fix for build options `./configure --enable-dtls --disable-asn`
 * FIx for detection of a salt length from an RSA PSS signature
-* Fix to free up globalRNGMutex mutex when cleaning up global RNG
+* Fix to free up `globalRNGMutex` mutex when cleaning up global RNG
 * Fix leak when multiple hardware names are in SAN
 * Fix nonblocking ret value from CRL I/O callbacks
-* Fix wolfSSL_BIO_free_all return type to better match for compatibility layer
-* Fix for make distcheck, maintainer-clean, to allow distribution builds
+* Fix `wolfSSL_BIO_free_all` return type to better match for compatibility layer
+* Fix for `make distcheck`, `maintainer-clean`, to allow distribution builds
 * Fix for async with fragmented packets
 * Fix for the build or RSA verify or public only
-* Fix for return value of wolfSSL_BIO_set_ssl to better match expected compatibility layer return value
-* Fix for sanity checks on size of issuer hash and key along with better freeing on error cases with DecodeBasicOcspResponse
-* Fix for potential memory leak with wolfSSL_OCSP_cert_to_id
+* Fix for return value of `wolfSSL_BIO_set_ssl` to better match expected compatibility layer return value
+* Fix for sanity checks on size of issuer hash and key along with better freeing on error cases with `DecodeBasicOcspResponse`
+* Fix for potential memory leak with `wolfSSL_OCSP_cert_to_id`
 
 ### Improvements/Optimizations
 ###### DTLS/TLS Code Base
@@ -232,15 +235,15 @@ Release 4.8.0 of wolfSSL embedded TLS has bug fixes and new features including:
 * TLS 1.3 PSK: use the hash algorithm to choose cipher suite
 * TLS Extended Master Secret ext: TLS13 - send in second Client Hello if in first
 * TLS Encrypt then MAC: check all padding bytes are the same value
-* wolfSSL_GetMaxRecordSize updated to now take additional cipher data into account
+* `wolfSSL_GetMaxRecordSize` updated to now take additional cipher data into account
 * Updated session export/import with DTLS to handle a new internal options flag
-* Refactored dtls_expected_peer_handshake_number handling
-* Added wolfSSL_CTX_get_ephemeral_key and wolfSSL_get_ephemeral_key for loading a constant key in place of an ephemeral one
-* Improved checking of XSNPRINTF return value in DecodePolicyOID
+* Refactored `dtls_expected_peer_handshake_number` handling
+* Added `wolfSSL_CTX_get_ephemeral_key` and `wolfSSL_get_ephemeral_key` for loading a constant key in place of an ephemeral one
+* Improved checking of `XSNPRINTF` return value in `DecodePolicyOID`
 
 ###### Build Options and Warnings
-* Added wolfSSL_CTX_set_verify to the ABI list
-* Adjusted FP_ECC build to not allow SECP160R1, SECP160R2, SECP160K1 and SECP224K1. FP_ECC does not work with scalars that are the length of the order when the order is longer than the prime.
+* Added `wolfSSL_CTX_set_verify` to the ABI list
+* Adjusted `FP_ECC` build to not allow SECP160R1, SECP160R2, SECP160K1 and SECP224K1. `FP_ECC` does not work with scalars that are the length of the order when the order is longer than the prime.
 * Added CMake support for CURVE25519, ED25519, CURVE448, and ED448
 * cmake addition to test paths when building
 * Added support for session tickets in CMake
@@ -248,52 +251,52 @@ Release 4.8.0 of wolfSSL embedded TLS has bug fixes and new features including:
 * Turn on reproducible-build by default when enable-distro
 * Windows Project: Include the X448 and Ed448 files
 * GCC-11 compile time warning fixes
-* Fix for compiling build of ./configure '--disable-tlsv12' '-enable-pkcallbacks'
+* Fix for compiling build of `./configure --disable-tlsv12 -enable-pkcallbacks`
 * Added build error for insecure build combination of secure renegotiation enabled with extended master secret disabled when session resumption is enabled
 * Updated building and running with Apple M1
 * Apache httpd build without TLS 1.3 macro guard added
 * Enable SHA3 and SHAKE256 requirements automatically when ED448 is enabled
-* Added option for AES CBC cipher routines to return BAD_LENGTH_E when called with an input buffer length not a multiple of AES_BLOCK_SIZE
-* Macro WOLFSSL_SP_INT_DIGIT_ALIGN added for alignment on buffers with SP build. This was needed for compiler building on a Renesas board.
+* Added option for AES CBC cipher routines to return `BAD_LENGTH_E` when called with an input buffer length not a multiple of `AES_BLOCK_SIZE`
+* Macro `WOLFSSL_SP_INT_DIGIT_ALIGN` added for alignment on buffers with SP build. This was needed for compiler building on a Renesas board.
 * Build support with no hashes enabled an no RNG compiled in
 * Allow use of FREESCALE hardware RNG without a specific port
 * Resolved some warnings with Windows builds and PBKDF disabled
-* Updated the version of autoconf and automake along with fixes for some new GCC-10 warnings
+* Updated the version of `autoconf` and `automake` along with fixes for some new GCC-10 warnings
 
 ###### Math Libraries
 * SP: Thumb implementation that works with clang
-* SP math all: sp_cmp handling of negative values
+* SP math all: `sp_cmp` handling of negative values
 * SP C ECC: mont sub - always normalize after sub before check for add
 * TFM math library prime checking, added more error checks with small stack build
 * Sanity checks on 0 value with GCD math function
-* fp_exptmod_ct error checking and small stack variable free on error
-* Sanity check on supported digit size when calling mp_add_d in non fastmath builds
-* Support for mp_dump with SP Math ALL
-* WOLFSSL_SP_NO_MALLOC for both the normal SP build and small SP build now
-* WOLFSSL_SP_NO_DYN_STACK added for SP small code that is not small stack build to avoid dynamic stack
+* `fp_exptmod_ct` error checking and small stack variable free on error
+* Sanity check on supported digit size when calling `mp_add_d` in non fastmath builds
+* Support for `mp_dump` with SP Math ALL
+* `WOLFSSL_SP_NO_MALLOC` for both the normal SP build and small SP build now
+* `WOLFSSL_SP_NO_DYN_STACK` added for SP small code that is not small stack build to avoid dynamic stack
 
 ###### PKCS 7/8
-* wc_PKCS7_DecodeCompressedData to optionally handle a packet without content wrapping
-* Added setting of content type parsed with PKCS7  wc_PKCS7_DecodeAuthEnvelopedData and wc_PKCS7_DecodeEnvelopedData
+* `wc_PKCS7_DecodeCompressedData` to optionally handle a packet without content wrapping
+* Added setting of content type parsed with PKCS7 `wc_PKCS7_DecodeAuthEnvelopedData` and `wc_PKCS7_DecodeEnvelopedData`
 * PKCS8 code improvements and refactoring
 
 ###### Misc.
-* Sanity checks on null inputs to the functions wolfSSL_X509_get_serialNumber and wolfSSL_X509_NAME_print_ex
-* Added ARM CryptoCell support for importing public key with wc_ecc_import_x963_ex()
-* Improved checking for possible use of key->dp == NULL cases with ECC functions
+* Sanity checks on null inputs to the functions `wolfSSL_X509_get_serialNumber` and `wolfSSL_X509_NAME_print_ex`
+* Added ARM CryptoCell support for importing public key with `wc_ecc_import_x963_ex()`
+* Improved checking for possible use of `key->dp == NULL` cases with ECC functions
 * Updated SHAKE256 to compile with NIST FIPS 202 standard and added support for OID values (thanks to strongX509)
-* Improved ECC operations when using WOLFSSL_NO_MALLOC
-* Added WOLFSSL_SNIFFER_FATAL_ERROR for an return value when sniffer is in a fatal state
-* Allow parsing spaces in Base64_SkipNewline
-* Issue callback when exceeding depth limit rather than error out with OPENSSL_EXTRA build
+* Improved ECC operations when using `WOLFSSL_NO_MALLOC`
+* Added `WOLFSSL_SNIFFER_FATAL_ERROR` for an return value when sniffer is in a fatal state
+* Allow parsing spaces in `Base64_SkipNewline`
+* Issue callback when exceeding depth limit rather than error out with `OPENSSL_EXTRA` build
 * Added NXP LTC RSA key generation acceleration
 
 
-For additional vulnerability information visit the vulnerability page at
+For additional vulnerability information visit the vulnerability page at:
 https://www.wolfssl.com/docs/security-vulnerabilities/
 
 See INSTALL file for build instructions.
-More info can be found on-line at https://wolfssl.com/wolfSSL/Docs.html
+More info can be found on-line at: https://wolfssl.com/wolfSSL/Docs.html
 
 
 

+ 1 - 1
doc/formats/html/footer.html

@@ -32,7 +32,7 @@
 </ul>
 </div>
 <div id="lowCenter">
-<p class="footText" id="center">Copyright &#169 2020 wolfSSL Inc.<br>All rights reserved.</p>
+<p class="footText" id="center">Copyright &#169 2021 wolfSSL Inc.<br>All rights reserved.</p>
 <div class="lowNav">
 <p class="footText">Help and Support</p>
 <ul class="lowNavList">

+ 29 - 32
examples/README.md

@@ -1,82 +1,79 @@
 # wolfSSL examples directory
 ## client and server
 
- These directories contain a client (client.c) and server (server.c) that utilize a variety of the wolfSSL library's capabilities. The manner in which both programs operate can depend on the configure or can be specified at run-time depending on the end goal. Both applications contain testing as well as benchmarking code.
+These directories contain a client (`client.c`) and server (`server.c`) that utilize a variety of the wolfSSL library's capabilities. The manner in which both programs operate can depend on the configure or can be specified at run-time depending on the end goal. Both applications contain testing as well as benchmarking code.
 
-Compile
+### Compile
+```sh
+./configure
+make
 ```
- ./configure
- make
- ```
-Usage
- ```
- ./examples/server/server
 
- ./examples/client/client
+### Usage
+```sh
+./examples/server/server
 
- ```
+./examples/client/client
+```
 
-Run ```./examples/server/server -h``` and ```./examples/client/client -h```  for usage details.
+Run `./examples/server/server -h` and `./examples/client/client -h`  for usage details.
 
 For simpler wolfSSL TLS server/client examples, visit https://github.com/wolfSSL/wolfssl-examples/tree/master/tls
 
 ## echoclient and echoserver
 
-These directories contain a client (echoclient.c) and server (echoserver.c) that establish a connection encrypted by wolfSSL. Like the names indicate, once the connection has been established any messages entered into echoclient are sent to and displayed on the echoserver and are then echoed back to echoclient. The nature of the encryption, as well as additional behavior of the two programs, depends on how wolfSSL was configured ( DTLS enabled/disabled, Filesystem enabled/disabled, etc ... ).
+These directories contain a client (`echoclient.c`) and server (`echoserver.c`) that establish a connection encrypted by wolfSSL. Like the names indicate, once the connection has been established any messages entered into echoclient are sent to and displayed on the echoserver and are then echoed back to echoclient. The nature of the encryption, as well as additional behavior of the two programs, depends on how wolfSSL was configured ( DTLS enabled/disabled, Filesystem enabled/disabled, etc ... ).
 
-Compile
-```
+### Compile
+```sh
 ./configure
 make
 ```
 
-Usage
-```
+### Usage
+```sh
 ./examples/echoserver/echoserver
 
 ./examples/echoclient/echoclient
-
 ```
 
 ## benchmark
 
 The benchmark directory offers an application that can help you grasp just how well wolfSSL's TLS functionality is performing on your local machine.
 
-
-Compile
-```
+### Compile
+```sh
 ./configure
 make
 ```
 
-Usage
-```         
+### Usage
+```sh
 ./examples/benchmark/tls_bench
-
 ```
 
-The tls_bench executable can also be compiled separately with ``` gcc -lwolfssl -lpthread -o tls_bench tls_bench.c ```.
+The `tls_bench` executable can also be compiled separately with `gcc -lwolfssl -lpthread -o tls_bench tls_bench.c`.
 
-Run ```./examples/benchmark/tls_bench -?``` for usage details.
+Run `./examples/benchmark/tls_bench -?` for usage details.
 
 ## sctp
 This directory contains servers and clients that demonstrate wolfSSL's DTLS-SCTP support.
 
-Compile
-```
+### Compile
+```sh
 ./configure --enable-sctp
 make
 ```
 
-Usage
-```
+### Usage
+```sh
 ./examples/sctp/sctp-server
 
 ./examples/sctp/sctp-client
 ```
 and
 
-```
+```sh
 ./examples/sctp/sctp-server-dtls
 
 ./examples/sctp/sctp-client-dtls
@@ -84,6 +81,6 @@ and
 
 ## configs
 
- This directory contains example wolfSSL configuration file templates for use when autoconf is not available, such as building with a custom IDE.
+This directory contains example wolfSSL configuration file templates for use when autoconf is not available, such as building with a custom IDE.
 
- See [configs/README.md](configs/README.md) for more details.
+See [configs/README.md](configs/README.md) for more details.

+ 2 - 2
tests/CONF_FILES_README.md

@@ -1,4 +1,4 @@
-suites.c is a dynamicically written program where new test cases can be written
+`suites.c` is a dynamicically written program where new test cases can be written
 and added to as needed. When creating a new configure file for a test be sure
-to use the exact formatting as the existing configure files. Reference test.conf
+to use the exact formatting as the existing configure files. Reference `test.conf`
 for an example.

+ 6 - 6
wolfcrypt/src/port/Espressif/README.md

@@ -10,12 +10,12 @@ For detail about ESP32 HW Acceleration, you can find in [Technical Reference Man
 
 To enable hw acceleration :
 
-Uncomment out #define WOLFSSL_ESPIDF in /path/to/wolfssl/wolfssl/wolfcrypt/settings.h  
-Uncomment out #define WOLFSSL_ESPWROOM32 in /path/to/wolfssl/wolfssl/wolfcrypt/settings.h
+* Uncomment out `#define WOLFSSL_ESPIDF` in `/path/to/wolfssl/wolfssl/wolfcrypt/settings.h`
+* Uncomment out `#define WOLFSSL_ESPWROOM32` in `/path/to/wolfssl/wolfssl/wolfcrypt/settings.h`
 
-To disable portions of the hardware acceleration you can optionally define:  
+To disable portions of the hardware acceleration you can optionally define:
 
-```
+```c
 /* Disabled SHA, AES and RSA acceleration */
 #define NO_ESP32WROOM32_CRYPT
 /* Disabled AES acceleration */
@@ -28,12 +28,12 @@ To disable portions of the hardware acceleration you can optionally define:
 
 ### Coding
 
-In your application you must include <wolfssl/wolfcrypt/settings.h> before any other wolfSSL headers. If building the sources directly we recommend defining `WOLFSSL_USER_SETTINGS` and adding your own `user_settings.h` file. You can find a good reference for this in `IDE/GCC-ARM/Header/user_settings.h`.
+In your application you must include `<wolfssl/wolfcrypt/settings.h>` before any other wolfSSL headers. If building the sources directly we recommend defining `WOLFSSL_USER_SETTINGS` and adding your own `user_settings.h` file. You can find a good reference for this in `IDE/GCC-ARM/Header/user_settings.h`.
 
 
 ### Benchmarks
 
-w/ USE_FAST_MATH and WOLFSSL_SMALL_STACK options
+w/ `USE_FAST_MATH` and `WOLFSSL_SMALL_STACK` options
 
 Software only implementation :