From 611c4acdddab9d702d235c2bcfe3b69002e93569 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 19 Oct 2025 10:40:26 -0700 Subject: Add support for OpenSSL v3.5 and newer. We are *only* supporting 3.5 (or newer 3.x releases) as its the newest LTS version of OpenSSL. This supports the full set of TLS features with NNG, including DTLS, PSK, TLS 1.3, etc. Future work will explore making using of the QUIC support in OpenSSL. Note that this OpenSSL work sits on top of NNG's TCP streams, so it cannot benefit from Linux in-kernel TLS or other features such as TCP fast open at this time. --- docs/BUILD_TLS.md | 46 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 39 insertions(+), 7 deletions(-) (limited to 'docs') 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 -- cgit v1.2.3-70-g09d2