From faa4cfcae96c97a6408860d27b68b8533b2f5857 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Nordheim?= Date: Mon, 18 Oct 2021 12:02:27 +0200 Subject: SSL: Update documentation wrt backends Mention the platform-specific backends and add a section on packaging Pick-to: 6.2 Fixes: QTBUG-97532 Change-Id: Ice78e32e81a719ccf237625e542d620662d3073e Reviewed-by: Paul Wicking --- src/network/doc/src/ssl.qdoc | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/src/network/doc/src/ssl.qdoc b/src/network/doc/src/ssl.qdoc index 2dcae744ac..d15c1e78d7 100644 --- a/src/network/doc/src/ssl.qdoc +++ b/src/network/doc/src/ssl.qdoc @@ -33,8 +33,9 @@ \keyword SSL The classes below provide support for secure network communication using - the Secure Sockets Layer (SSL) protocol, using the \l{OpenSSL Toolkit} - to perform encryption and protocol handling. + the Secure Sockets Layer (SSL) protocol, using a native TLS backend, + the \l{OpenSSL Toolkit}, or any appropriate TLS plugin to perform encryption + and protocol handling. From Qt version 5.15 onwards, the officially supported version for OpenSSL is 1.1.1 or later. @@ -44,13 +45,21 @@ \section1 Enabling and Disabling SSL Support - When building Qt from source, the configuration system checks for the presence - of the \c{openssl/opensslv.h} header provided by source or developer packages - of OpenSSL. + When building Qt from source, Qt builds plugins for native TLS libraries + that are supported for the operating system you are building for. For + Windows this means + \l{Schannel}{https://docs.microsoft.com/en-us/windows/win32/com/schannel}, + while for macOS this is + \l{Secure Transport}{https://developer.apple.com/documentation/security/secure_transport}. - By default, an SSL-enabled Qt library dynamically loads any installed OpenSSL - library at run-time. However, it is possible to link against the library at - compile-time by configuring Qt with the \c{-openssl-linked} option. + On all platforms, the configuration system checks for the presence of the + \c{openssl/opensslv.h} header provided by source or developer packages + of OpenSSL. If found, it will enable and build the OpenSSL backend for Qt. + + By default, an OpenSSL-enabled Qt library dynamically loads any installed + OpenSSL library at run-time. However, it is possible to link against the + library at compile-time by configuring Qt with the \c{-openssl-linked} + option. When building a version of Qt linked against OpenSSL, Qt's build system will use CMake's \c{FindOpenSSL} command to find OpenSSL in several standard @@ -65,6 +74,20 @@ To disable SSL support in a Qt build, configure Qt with the \c{-no-openssl} option. + \section1 Considerations While Packaging Your Application + + When you package your application, you may run a tool like \l{windeployqt}. This + copies all the plugins for the libraries you use to the \c{plugins/} folder. + However, for TLS you only need one backend, and you may delete the other + plugins before packaging your application. For example, if you're on Windows + and don't require any of the extra features the OpenSSL backend provides, + you can choose to forego shipping the \c{qopensslbackend} plugin as well as + the OpenSSL library, and simply ship the \c{qschannelbackend} plugin. + + However, shipping multiple backends is not a problem. Qt will + attempt to load the backends in order (with OpenSSL attempted first) until + one is successfully loaded. The other backends are then unused. + \section1 Datagram Transport Layer Security Datagram Transport Layer Security (DTLS) is a protocol that enables security -- cgit v1.2.3