diff --git a/wolfSSL/src/chapter01.md b/wolfSSL/src/chapter01.md index addbe104..5edff6a9 100644 --- a/wolfSSL/src/chapter01.md +++ b/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). diff --git a/wolfSSL/src/chapter02.md b/wolfSSL/src/chapter02.md index b01639ef..1d268323 100644 --- a/wolfSSL/src/chapter02.md +++ b/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,7 +76,7 @@ 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 @@ -84,15 +84,15 @@ You will need to download Service Pack 1 to build wolfSSL solution once it has b ### 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 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,11 +1822,11 @@ 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) @@ -1834,7 +1834,7 @@ This library is planned to be deprecated and removed from the wolfSSL/wolfCrypt Forked from public domain LibTomMath library. For more information about LibTomMath, please see . 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 diff --git a/wolfSSL/src/chapter03.md b/wolfSSL/src/chapter03.md index 23eb75f7..f95ddd36 100644 --- a/wolfSSL/src/chapter03.md +++ b/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 ``` -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(); diff --git a/wolfSSL/src/chapter04.md b/wolfSSL/src/chapter04.md index 8a8df3ed..1ddf7e72 100644 --- a/wolfSSL/src/chapter04.md +++ b/wolfSSL/src/chapter04.md @@ -10,7 +10,7 @@ For an overview of wolfSSL features, please reference the wolfSSL product webpag ## Protocol Support -wolfSSL supports **SSL 3.0**, **TLS **(**1.0**, **1.1**, **1.2, 1.3**), and **DTLS **(**1.0 **and **1.2**). You can easily select a protocol to use by using one of the following functions (as shown for either the client or server). wolfSSL does not support SSL 2.0, as it has been insecure for several years. The client and server functions below change slightly when using the OpenSSL compatibility layer. For the OpenSSL-compatible functions, please see [OpenSSL Compatibility](chapter13.md#openssl-compatibility). +wolfSSL supports **SSL 3.0**, **TLS **(**1.0**, **1.1**, **1.2, 1.3**), and **DTLS **(**1.0**, **1.2**, **1.3**). You can easily select a protocol to use by using one of the following functions (as shown for either the client or server). wolfSSL does not support SSL 2.0, as it has been insecure for several years. The client and server functions below change slightly when using the OpenSSL compatibility layer. For the OpenSSL-compatible functions, please see [OpenSSL Compatibility](chapter13.md#openssl-compatibility). ### Server Functions @@ -23,7 +23,7 @@ wolfSSL supports **SSL 3.0**, **TLS **(**1.0**, **1.1**, **1.2, 1.3**), and **DT * [`wolfTLSv1_3_server_method()`](group__Setup.md#function-wolftlsv1_3_server_method) - TLS 1.3 * [`wolfSSLv23_server_method()`](group__Setup.md#function-wolfsslv23_server_method) - Use highest possible version from SSLv3 - TLS 1.2 -wolfSSL supports robust server downgrade with the [`wolfSSLv23_server_method()`](group__Setup.md#function-wolfsslv23_server_method) function. See [Robust Client and Server Downgrade](#robust-client-and-server-downgrade) for a details. +wolfSSL supports robust server downgrade with the [`wolfSSLv23_server_method()`](group__Setup.md#function-wolfsslv23_server_method) function. See [Robust Client and Server Downgrade](#robust-client-and-server-downgrade) for details. ### Client Functions @@ -36,17 +36,17 @@ wolfSSL supports robust server downgrade with the [`wolfSSLv23_server_method()`] * [`wolfTLSv1_3_client_method()`](group__Setup.md#function-wolftlsv1_3_client_method) - TLS 1.3 * [`wolfSSLv23_client_method()`](group__Setup.md#function-wolfsslv23_client_method) - Use highest possible version from SSLv3 - TLS 1.2 -wolfSSL supports robust client downgrade with the [`wolfSSLv23_client_method()`](group__Setup.md#function-wolfsslv23_client_method) function. See [Robust Client and Server Downgrade](#robust-client-and-server-downgrade) for a details. +wolfSSL supports robust client downgrade with the [`wolfSSLv23_client_method()`](group__Setup.md#function-wolfsslv23_client_method) function. See [Robust Client and Server Downgrade](#robust-client-and-server-downgrade) for details. -For details on how to use these functions, please see the [Getting Started](chapter03.md#getting-started) chapter. For a comparison between SSL 3.0, TLS 1.0, 1.1, 1.2, and DTLS, please see Appendix A. +For details on how to use these functions, please see the [Getting Started](chapter03.md#getting-started) chapter. For a comparison between SSL, TLS, and DTLS, please see Appendix A. ### Robust Client and Server Downgrade -Both wolfSSL clients and servers have robust version downgrade capability. If a specific protocol version method is used on either side, then only that protocol version will be negotiated or an error will be returned. For example, a client that uses TLS 1.0 and tries to connect to an SSL 3.0 only server, the connection will fail, likewise connecting to a TLS 1.1 will fail as well. +Both wolfSSL clients and servers have robust version downgrade capability. If a specific protocol version method is used on either side, then only that protocol version will be negotiated or an error will be returned. For example, if a client that uses TLS 1.0 tries to connect to an SSL 3.0 only server, then the connection will fail; likewise, connecting to a TLS 1.1 server will fail as well. -To resolve this issue, a client that uses the [`wolfSSLv23_client_method()`](group__Setup.md#function-wolfsslv23_client_method) function will support the highest protocol version supported by the server by downgrading if necessary. In this case, the client will be able to connect to a server running TLS 1.0 - TLS 1.3 (or a subset or superset that includes SSL 3.0 depending on which protocol versions are configured in wolfSSL). The only versions it can't connect to is SSL 2.0 which has been insecure for years, and SSL 3.0 which has been disabled by default. +To resolve this issue, a client that uses the [`wolfSSLv23_client_method()`](group__Setup.md#function-wolfsslv23_client_method) function will support the highest protocol version supported by the server by downgrading if necessary. In this case, the client will be able to connect to a server running TLS 1.0 - TLS 1.3 (or a subset or superset that includes SSL 3.0 depending on which protocol versions are configured in wolfSSL). The only versions it can't connect to are SSL 2.0 which has been insecure for years, and SSL 3.0 which has been disabled by default. -Similarly, a server using the [`wolfSSLv23_server_method()`](group__Setup.md#function-wolfsslv23_server_method) function can handle clients supporting protocol versions from TLS 1.0 - TLS 1.2. A wolfSSL server can't accept a connection from SSLv2 because no security is provided. +Similarly, a server using the [`wolfSSLv23_server_method()`](group__Setup.md#function-wolfsslv23_server_method) function can handle clients supporting protocol versions from TLS 1.0 - TLS 1.3. A wolfSSL server can't accept a connection from SSLv2 because no security is provided. ### IPv6 Support @@ -60,7 +60,7 @@ Further information on IPv6 can be found here: ### DTLS -wolfSSL has support for DTLS (“Datagram” TLS) for both client and server. The current supported version is DTLS 1.0. +wolfSSL has support for DTLS (“Datagram” TLS) for both client and server. The current supported versions are DTLS 1.0, 1.2, and 1.3. The TLS protocol was designed to provide a secure transport channel across a **reliable** medium (such as TCP). As application layer protocols began to be developed using UDP transport (such as SIP and various electronic gaming protocols), a need arose for a way to provide communications security for applications which are delay sensitive. This need lead to the creation of the DTLS protocol. @@ -80,7 +80,7 @@ The focus of lwIP is to reduce RAM usage while still providing a full TCP stack. ### TLS Extensions -A list of TLS extensions supported by wolfSSL and note of which RFC can be referenced for the given extension. +A list of TLS extensions supported by wolfSSL and the RFC corresponding to each extension: | RFC | Extension | wolfSSL Type | | --- | --------- | ------------ | @@ -114,7 +114,7 @@ Cipher suites come in a variety of strengths. Because they are made up of sever There can be many methods of grading the strength of a cipher suite - the specific method used seems to vary between different projects and companies and can include things such as symmetric and public key algorithm key sizes, type of algorithm, performance, and known weaknesses. -**NIST** (National Institute of Standards and Technology) makes recommendations on choosing an acceptable cipher suite by providing comparable algorithm strengths for varying key sizes of each. The strength of a cryptographic algorithm depends on the algorithm and the key size used. The NIST Special Publication, [SP800-57](https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final), states that two algorithms are considered to be of comparable strength as follows: +**NIST** (National Institute of Standards and Technology) makes recommendations on choosing an acceptable cipher suite by providing comparable algorithm strengths for varying key sizes of each. The NIST Special Publication, [SP800-57](https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final), states how two algorithms can be compared: > Two algorithms are considered to be of comparable strength for the given key sizes (X and Y) if the amount of work needed to “break the algorithms” or determine the keys (with the given key sizes) is approximately the same using a given resource. The security strength of an algorithm for a given key size is traditionally described in terms of the amount of work it takes to try all keys for a symmetric algorithm with a key size of “X” that has no shortcut attacks (i.e., the most efficient attack is to try all possible keys). @@ -288,7 +288,7 @@ wolfSSL supports AEAD suites, including AES-GCM, AES-CCM, and CHACHA-POLY1305. T ### Block and Stream Ciphers -wolfSSL supports the **AES**, **DES**, **3DES**, and **Camellia** block ciphers and the **RC4**, and **CHACHA20 **stream ciphers. AES, DES, 3DES and RC4 are enabled by default. Camellia, and ChaCha20 can be enabled when building wolfSSL (with the [`--enable-camellia`](chapter02.md#--enable-camellia), and [`--disable-chacha`](chapter02.md#--disable-chacha) build options, respectively). The default mode of AES is CBC mode. To enable GCM or CCM mode with AES, use the [`--enable-aesgcm`](chapter02.md#--enable-aesgcm) and [`--enable-aesccm`](chapter02.md#--enable-aesccm) build options. Please see the examples for usage and the [wolfCrypt Usage Reference](chapter10.md#wolfcrypt-usage-reference) for specific usage information. +wolfSSL supports the **AES**, **DES**, **3DES**, and **Camellia** block ciphers and the **RC4**, and **CHACHA20 **stream ciphers. AES, DES, 3DES, RC4, and ChaCha20 are enabled by default. Camellia can be enabled when building wolfSSL with the [`--enable-camellia`](chapter02.md#--enable-camellia) build option. The default mode of AES is CBC mode. To enable GCM or CCM mode with AES, use the [`--enable-aesgcm`](chapter02.md#--enable-aesgcm) and [`--enable-aesccm`](chapter02.md#--enable-aesccm) build options. Please see the examples for usage and the [wolfCrypt Usage Reference](chapter10.md#wolfcrypt-usage-reference) for specific usage information. While SSL uses RC4 as the default stream cipher, it has been obsoleted due to compromise. Recently wolfSSL added ChaCha20. While RC4 is about 11% more performant than ChaCha, RC4 is generally considered less secure than ChaCha. ChaCha can put up very nice times of it’s own with added security as a tradeoff. @@ -296,7 +296,7 @@ To see a comparison of cipher performance, visit the wolfSSL Benchmark web page, #### What’s the Difference? -A block cipher has to be encrypted in chunks that are the block size for the cipher. For example, AES has a block size of 16 bytes. So if you're encrypting a bunch of small, 2 or 3 byte chunks back and forth, over 80% of the data is useless padding, decreasing the speed of the encryption/decryption process and needlessly wasting network bandwidth to boot. Basically block ciphers are designed for large chunks of data, have block sizes requiring padding, and use a fixed, unvarying transformation. +A block cipher has to be encrypted in chunks that are the block size for the cipher. For example, AES has a block size of 16 bytes. So if you're encrypting a bunch of small, 2 or 3 byte chunks back and forth, over 80% of the data is useless padding, decreasing the speed of the encryption/decryption process and needlessly wasting network bandwidth to boot. Basically, block ciphers are designed for large chunks of data, have block sizes requiring padding, and use a fixed, unvarying transformation. Stream ciphers work well for large or small chunks of data. They are suitable for smaller data sizes because no block size is required. If speed is a concern, stream ciphers are your answer, because they use a simpler transformation that typically involves an xor'd keystream. So if you need to stream media, encrypt various data sizes including small ones, or have a need for a fast cipher then stream ciphers are your best bet. @@ -344,7 +344,7 @@ Additionally, wolfSSL also provides support for RSA-Probabilistic Signature Sche #### PKCS #5, PBKDF1, PBKDF2, PKCS #12 -PKCS #5 is a password based key derivation method which combines a password, a salt, and an iteration count to generate a password-based key. wolfSSL supports both PBKDF1 and PBKDF2 key derivation functions. A key derivation function produces a derived key from a base key and other parameters (such as the salt and iteration count as explained above). PBKDF1 applies a hash function (MD5, SHA1, etc) to derive keys, where the derived key length is bounded by the length of the hash function output. With PBKDF2, a pseudorandom function is applied (such as HMAC-SHA-1) to derive the keys. In the case of PBKDF2, the derived key length is unbounded. +PKCS #5 is a password-based key derivation method which combines a password, a salt, and an iteration count to generate a password-based key. wolfSSL supports both PBKDF1 and PBKDF2 key derivation functions. A key derivation function produces a derived key from a base key and other parameters (such as the salt and iteration count as explained above). PBKDF1 applies a hash function (MD5, SHA1, etc) to derive keys, where the derived key length is bounded by the length of the hash function output. With PBKDF2, a pseudorandom function is applied (such as HMAC-SHA-1) to derive the keys. In the case of PBKDF2, the derived key length is unbounded. wolfSSL also supports the PBKDF function from PKCS #12 in addition to PBKDF1 and PBKDF2. The function prototypes look like this: @@ -389,13 +389,13 @@ Supported features include: ##### PKCS #7 Callbacks -Additional callbacks and supporting functions were added to allow for a user to choose their keys after the PKCS7 bundle has been parsed.For unwrapping the CEK the function `wc_PKCS7_SetWrapCEKCb()` can be called. The callback set by this function gets called in the case of KARI and KEKRI bundles. The keyID or SKID gets passed from wolfSSL to the user along with the originator key in the case of KARI. After the user unwraps the CEK with their KEK the decrypted key to be used should then be passed back to wolfSSL. An example of this can be found in the wolfssl-examples repository in the file `signedData-EncryptionFirmwareCB.c`. +Additional callbacks and supporting functions were added to allow for a user to choose their keys after the PKCS7 bundle has been parsed. For unwrapping the CEK the function `wc_PKCS7_SetWrapCEKCb()` can be called. The callback set by this function gets called in the case of KARI and KEKRI bundles. The keyID or SKID gets passed from wolfSSL to the user along with the originator key in the case of KARI. After the user unwraps the CEK with their KEK the decrypted key to be used should then be passed back to wolfSSL. An example of this can be found in the wolfssl-examples repository in the file `signedData-EncryptionFirmwareCB.c`. An additional callback was added for decryption of PKCS7 bundles. For setting a decryption callback function the API `wc_PKCS7_SetDecodeEncryptedCb()` can be used. To set a user defined context the API `wc_PKCS7_SetDecodeEncryptedCtx()` should be used. This callback will get executed on calls to `wc_PKCS7_DecodeEncryptedData()`. ##### PKCS #7 Streaming -Stream oriented API for PKCS7 decoding gives the option of passing inputs in smaller chunks instead of all at once.By default the streaming functionality with PKCS7 is on. To turn off support for streaming PKCS7 API the macro `NO_PKCS7_STREAM` can be defined. An example of doing this with autotools would be `./configure --enable-pkcs7 CFLAGS=-DNO_PKCS7_STREAM`. +Stream oriented API for PKCS7 decoding gives the option of passing inputs in smaller chunks instead of all at once. By default the streaming functionality with PKCS7 is on. To turn off support for streaming PKCS7 API the macro `NO_PKCS7_STREAM` can be defined. An example of doing this with autotools would be `./configure --enable-pkcs7 CFLAGS=-DNO_PKCS7_STREAM`. For streaming when decoding/verifying bundles the following functions are supported: @@ -405,7 +405,7 @@ For streaming when decoding/verifying bundles the following functions are suppor 4. [`wc_PKCS7_DecodeEnvelopedData()`](group__PKCS7.md#function-wc_pkcs7_decodeenvelopeddate) 5. `wc_PKCS7_DecodeAuthEnvelopedData()` -**Note**: that when calling [`wc_PKCS7_VerifySignedData_ex`](group__PKCS7.md#function-wc_pkcs7_verifysigneddata_ex) it is expected that the argument pkiMsgFoot is the full buffer. The internal structure only supports streaming of one buffer which in this case would be `pkiMsgHead`. +**Note**: that when calling [`wc_PKCS7_VerifySignedData_ex`](group__PKCS7.md#function-wc_pkcs7_verifysigneddata_ex) it is expected that the argument pkiMsgFoot is the full buffer. The internal structure only supports streaming of one buffer, which in this case would be `pkiMsgHead`. ### Forcing the Use of a Specific Cipher diff --git a/wolfSSL/src/chapter07.md b/wolfSSL/src/chapter07.md index adc46aa3..a6c5f352 100644 --- a/wolfSSL/src/chapter07.md +++ b/wolfSSL/src/chapter07.md @@ -10,17 +10,17 @@ wolfSSL (formerly CyaSSL) has support for **PEM**, and **DER** formats for certi **DER**, or “Distinguished Encoding Rules”, is a binary format of a certificate. DER file extensions can include `.der` and `.cer`, and cannot be viewed with a text editor. -An X.509 certificate is encoded using ASN.1 format. The DER format is the ASN.1 encoding. The PEM format is Base64 encoded and wrapped with a human readable header and footer. TLS send certificates in DER format. +An X.509 certificate is encoded using ASN.1 format. The DER format is the ASN.1 encoding. The PEM format is Base64 encoded and wrapped with a human readable header and footer. TLS sends certificates in DER format. ## Supported Certificate Extensions If an unsupported or unknown extension that is marked as critical is found, then an error message is returned, otherwise unsupported or unknown extensions found -are ignored. Certificate extension parsing expect that at the very least +are ignored. Certificate extension parsing expects that at the very least `--enable-certext` (macro WOLFSSL_CERT_EXT) has been used when compiling the wolfSSL library. This is a high level list of certificate -extensions that can be **parsed** and at least part if not all of the extensions +extensions that can be **parsed** and at least part, if not all, of the extensions be used. | Extension From [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2) | Supported | @@ -405,7 +405,7 @@ Supported types are: * `PKCS8_PRIVATEKEY_TYPE` * `PKCS8_ENC_PRIVATEKEY_TYPE` -Now the buffer `pemCert<` holds the PEM format of the certificate. +Now the buffer `pemCert` holds the PEM format of the certificate. If you wish to create a CA signed certificate then a couple of steps are required. After filling in the subject information as before, you’ll need to set the issuer information from the CA certificate. This can be done with `SetIssuer()` like this: diff --git a/wolfSSL/src/chapter08.md b/wolfSSL/src/chapter08.md index ad5cec9f..125b3dd8 100644 --- a/wolfSSL/src/chapter08.md +++ b/wolfSSL/src/chapter08.md @@ -19,15 +19,17 @@ The log levels can be found in `wolfssl/wolfcrypt/logging.h`, and the implementa wolfSSL tries to provide informative error messages in order to help with debugging. -Each [`wolfSSL_read()`](group__IO.md#function-wolfssl_read) and [`wolfSSL_write()`](group__IO.md#function-wolfssl_write) call will return the number of bytes written upon success, 0 upon connection closure, and -1 for an error, just like `read()` and `write()`. In the event of an error you can use two calls to get more information about the error. +[//]: # (This is a comment. links to group__IO.md and group__Debug.md are causing lines to be truncated so I have removed references to them.) -The function [`wolfSSL_get_error()`](group__Debug.md#function-wolfssl_get_error) will return the current error code. It takes the current `WOLFSSL` object, and [`wolfSSL_read()`](group__IO.md#function-wolfssl_read) or [`wolfSSL_write()`](group__IO.md#function-wolfssl_write) result value as an arguments and returns the corresponding error code. +Each `wolfSSL_read()` and `wolfSSL_write()` call will return the number of bytes written upon success, 0 upon connection closure, and -1 for an error, just like `read()` and `write()`. In the event of an error you can use two calls to get more information about the error. + +The function `wolfSSL_get_error()` will return the current error code. It takes the current `WOLFSSL` object, and `wolfSSL_read()` or `wolfSSL_write()` result value as arguments and returns the current error code. ```c int err = wolfSSL_get_error(ssl, result); ``` -To get a more human-readable error code description, the [`wolfSSL_ERR_error_string()`](group__Debug.md#function-wolfssl_err_error_string) function can be used. It takes the return code from [`wolfSSL_get_error`](group__Debug.md#function-wolfssl_get_error) and a storage buffer as arguments, and places the corresponding error description into the storage buffer (`errorString` in the example below). +To get a more human-readable error code description, the `wolfSSL_ERR_error_string()` function can be used. It takes the return code from `wolfSSL_get_error` and a storage buffer as arguments, and places the corresponding error description into the storage buffer (`errorString` in the example below). ```c char errorString[80];