diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/BUILD_TLS.md | 46 |
1 files changed, 39 insertions, 7 deletions
diff --git a/docs/BUILD_TLS.md b/docs/BUILD_TLS.md index 63ae6347..7bdea54a 100644 --- a/docs/BUILD_TLS.md +++ b/docs/BUILD_TLS.md @@ -3,8 +3,9 @@ If you want to include support for Transport Layer Security (`tls+tcp://` and `wss://` URLs) you should follow these directions. -TLS support in NNG depends on either the [Mbed TLS](https://tls.mbed.org/) -or [WolfSSL](https://www.wolfssl.com/) library (your choice). +TLS support in NNG depends on a suitable TLS library. +The options are [Mbed TLS](https://tls.mbed.org/), +[WolfSSL](https://www.wolfssl.com/), [OpenSSL](https://openssl.org). > [!IMPORTANT] > These libraries are licensed under different terms than NNG. @@ -30,21 +31,52 @@ You can also build these from source; if you choose to do so, please make sure you also _install_ it somewhere (even a temporary staging directory). +## Notes about Mbed TLS + +MbedTLS 2.28 or 3.6 are tested and known to work. +MbedTLS 4.0 is not at present supported, but we will work to +address that soon. Support for MbedTLS 2.28 may be dropped +before NNG 2.0 finalizes, as it is no longer supported by +the Mbed TLS project. + +## Notes about WolfSSL + +WolfSSL can be configured with a small subset of possible +features, which can impair NNG's functionality. We recommend +enabling support for peer certificates as well as the optional +extra OpenSSL compatibility APIs. + +Note that the open source version of WolfSSL is GPLv3, which +applies significant additional considerations on users. Please +check with your lawyer if you're not planning to open source +your work under GPLv3 as well. + +We have not tested NNG with the commercial version of WolfSSL. +If you want support for that, please contact Staysail Systems +to make support arrangements. + +## Notes about OpenSSL + +OpenSSL requires version 3.5 or newer. (As of this writing, OpenSSL +3.5 is the most recent long term support - LTS - release of OpenSSL.) +No effort will be made to support earlier releases. + ## Configuring NNG with TLS TLS support is not enabled by default, but can be enabled by configuring with the CMake option `NNG_ENABLE_TLS=ON`. -You can select which library to use by using `NNG_TLS_ENGINE=mbed` or -`NNG_TLS_ENGINE=wolf`. If you specify neither, then Mbed TLS will be assumed -by default. +You can select which library to use by using `NNG_TLS_ENGINE=mbed`, +`NNG_TLS_ENGINE=wolf`, or `NNG_TLS_ENGINE=openssl`. +If you do not specify an engine, then `mbed` is assumed by default. +(Note that the default may change in future releases.) By default NNG searches for an installed components in `/usr/local`, as well as the normal installation directories for libraries on your system. -If you have installed Mbed TLS elsewhere, you can direct the NNG configuration +If you have installed the TLS library elsewhere, you can direct the NNG configuration to it by setting the `MBEDTLS_ROOT_DIR` or `WOLFSSL_ROOT_DIR` CMake variable -as appropriate. +as appropriate. For OpenSSL, see the CMake documentation for `FindOpenSSL`. ## Example |