Add WolfSSL building information

Also, converted to Markdown, and provided revised information about test.

1 files changed, 80 insertions, 0 deletions

diff --git a/docs/BUILD_TLS.md b/docs/BUILD_TLS.md
new file mode 100644
index 00000000..63ae6347
--- /dev/null
+++ b/docs/BUILD_TLS.md
@@ -0,0 +1,80 @@
+# Building for TLS Support
+
+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).
+
+> [!IMPORTANT]
+> These libraries are licensed under different terms than NNG.
+> You are responsible for reading those license terms, and ensuring
+> that your use conforms to them.
+
+> [!TIP]
+> This project receives no compensation or support in any other form
+> from either ARM (owners of the Mbed TLS project) or WolfSSL.
+> Thus, as a special request, if you're paying for commercial licenses for
+> either Mbed TLS or WolfSSL for use with NNG, please consider also sponsoring
+> this project or obtaining a commercial support contract from
+> [Staysail Systems, Inc.](https://www.staysail.tech/)
+> You can enquire about support contracts at info@staysail.tech.
+> Sponsorship information is available on our
+> [GitHub page](https://github.com/nanomsg/nng). Thank you!
+
+On many distributions you may be able to install a pre-packaged version
+of either library. We recommend doing so if this is an option for you.
+For example, Ubuntu users can install the `libmbedtls-dev` package.
+
+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).
+
+## 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.
+
+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
+to it by setting the `MBEDTLS_ROOT_DIR` or `WOLFSSL_ROOT_DIR` CMake variable
+as appropriate.
+
+## Example
+
+The following example would work on either Linux or macOS, and assumes
+that we have checked out github source trees into `$HOME/work`.
+It also assumes that Mbed TLS is already installed in `/usr/local` or
+a standard search path.
+
+```
+
+$ export NNGDIR=$HOME/work/nng
+$ mkdir build
+$ cd build
+
+$ cmake -G Ninja -DNNG_ENABLE_TLS=ON ..
+
+... (lots of lines of output from cmake...)
+
+$ ninja build
+
+... (lots of lines of output from ninja...)
+
+$ ./src/supplemental/tls/tls_test -v
+
+... (lots of lines of output from the test ...)
+
+Summary:
+  Count of all unit tests:        9
+  Count of run unit tests:        9
+  Count of failed unit tests:     0
+  Count of skipped unit tests:    0
+SUCCESS: All unit tests have passed.
+```