- Qt 6.9
- Qt Network
- Secure Sockets Layer (SSL) Classes
- Qt 6.9.3 Reference Documentation

Network Programming API ◦ Upgrading from Qt 5

# Secure Sockets Layer (SSL) Classes

The classes below provide support for secure network communication using the Secure Sockets Layer (SSL) protocol, using a native TLS backend, the OpenSSL Toolkit, or any appropriate TLS plugin to perform encryption and protocol handling.

QDtls | This class provides encryption for UDP sockets
QDtlsClientVerifier | This class implements server-side DTLS cookie generation and verification
QDtlsClientVerifier::GeneratorParameters | This class defines parameters for DTLS cookie generator
QOcspResponse | This class represents Online Certificate Status Protocol response
QSsl | Declares enums common to all SSL classes in Qt Network
QSslCertificate | Convenient API for an X509 certificate
QSslCertificateExtension | API for accessing the extensions of an X509 certificate
QSslCipher | Represents an SSL cryptographic cipher
QSslConfiguration | Holds the configuration and state of an SSL connection
QSslDiffieHellmanParameters | Interface for Diffie-Hellman parameters for servers
QSslEllipticCurve | Represents an elliptic curve for use by elliptic-curve cipher algorithms
QSslError | SSL error
QSslKey | Interface for private and public keys
QSslPreSharedKeyAuthenticator | Authentication data for pre shared keys (PSK) ciphersuites
QSslServer | Implements an encrypted, secure TCP server over TLS
QSslSocket | SSL encrypted socket for both clients and servers
QSslSocket::AlertLevel | Describes the level of an alert message
QSslSocket::AlertType | Enumerates possible codes that an alert message can have
QDtls::HandshakeState | Describes the current state of DTLS handshake
QSslSocket::ImplementedClass | Enumerates classes that a TLS backend implements
QDtls::QDtlsError | Describes errors that can be found by QDtls and QDtlsClientVerifier
QOcspResponse::QOcspCertificateStatus | Describes the Online Certificate Status
QOcspResponse::QOcspRevocationReason | Describes the reason for revocation
QSslSocket::SupportedFeature | Enumerates possible features that a TLS backend supports

For Android applications see Adding OpenSSL Support for Android.

## Using Encryption in Networked Applications

Use encryption when transporting data on any network whenever possible. Plaintext, which is unencrypted data that is easily readable, exposes sensitive data such as user information and information about network systems.

Use QSslSocket::connectToHostEncrypted() to connect using encryption and check for SSL issues using QSslSocket::sslHandshakeErrors(). Use QSslSocket::ignoreSslErrors() with caution as it will create security risks in your application.

Use QSslConfiguration to enforce strong security settings. The supported protocols depend on the SSL backend and the risk level of a protocol could change in the future. You can use a newer and more secure protocol using QSslConfiguration::setProtocol(). For more information, refer to QSsl::SslProtocol for the available protocols.

## Enabling and Disabling SSL Support when Building Qt from Source

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 Schannel, while for macOS this is Secure Transport.

On all platforms, the configuration system checks for the presence of the `openssl/opensslv.h` header provided by source or developer packages of OpenSSL. If found, it will enable and build the OpenSSL backend for Qt.

Note: While Qt can still support the older OpenSSL 1.1.1 version when built from sources, the builds of Qt in the Qt Online Installer require OpenSSL 3 at runtime.

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 `-openssl-linked` option.

When building a version of Qt linked against OpenSSL, Qt's build system will use CMake's `FindOpenSSL` command to find OpenSSL in several standard locations. You can set the CMake variable OPENSSL_ROOT_DIR to force a specific location.

For example:

     configure -openssl-linked -- -D OPENSSL_ROOT_DIR=<openssl_dir>

To disable SSL support in a Qt build, configure Qt with the `-no-openssl` option.

## Considerations While Packaging Your Application

When you package your application, you may run a tool like windeployqt. This copies all the plugins for the libraries you use to the `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 `qopensslbackend` plugin as well as the OpenSSL library, and simply ship the `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.

## Datagram Transport Layer Security

Datagram Transport Layer Security (DTLS) is a protocol that enables security for datagram-based applications, providing them with protection against eavesdropping, tampering, or message forgery. The DTLS protocol is based on the stream-oriented Transport Layer Security (TLS) protocol. QtNetwork enables the use of DTLS with User Datagram Protocol (UDP), as defined by RFC 6347.

## Import and Export Restrictions

Import and export restrictions apply for some types of software, and for some parts of the world. Developers wishing to use SSL communication in their deployed applications should either ensure that their users have the appropriate libraries installed, or they should consult a suitably qualified legal professional to ensure that applications using code from the OpenSSL project are correctly certified for import and export in relevant regions of the world.

Refer to Export Control of Qt Framework and Tools for more information.