QSslConfiguration Class

The QSslConfiguration class holds the settings of a TLS connection. More…

List of all members, including inherited members

Public Functions

Static Public Members

Detailed Description

The default verifies peers against the system's trusted certificates and requires TLS 1.2 or newer. To trust a private CA alongside them:

QSslConfiguration config = QSslConfiguration::defaultConfiguration();
config.addCaCertificates(QSslCertificate::fromPath("company-ca.pem"));
socket.setSslConfiguration(config);

Use setCaCertificates() instead to trust only the certificates you list.

See also QSslSocket.

Differences from Qt

Member Function Documentation

QSslConfiguration::QSslConfiguration()

Constructs a configuration with the default settings.

See also defaultConfiguration().

void QSslConfiguration::addCaCertificate(const QSslCertificate &certificate)

Trusts certificate as well as the current set.

See also setCaCertificates().

void QSslConfiguration::addCaCertificates(const QList<QSslCertificate> &certificates)

Trusts certificates as well as the current set.

See also setCaCertificates().

QList<QByteArray> QSslConfiguration::allowedNextProtocols() const

Returns the application protocols offered during the handshake.

See also setAllowedNextProtocols().

QMap<QByteArray, QVariant> QSslConfiguration::backendConfiguration() const

Returns the options that were set for the TLS library with setBackendConfigurationOption().

See also setBackendConfiguration().

QList<QSslCertificate> QSslConfiguration::caCertificates() const

Returns the certificates added to the trusted set. System certificates are not listed.

See also setCaCertificates() and addCaCertificate().

QList<QSslCipher> QSslConfiguration::ciphers() const

Returns the ciphers that a connection with this configuration offers and accepts, in the order of preference: those given to setCiphers(), or, if it was never called, the ones that OpenSSL enables by default.

See also setCiphers() and supportedCiphers().

[static] QSslConfiguration QSslConfiguration::defaultConfiguration()

Returns the configuration new sockets start with.

See also setDefaultConfiguration().

bool QSslConfiguration::isNull() const

Returns true if every setting has its initial value.

QSslCertificate QSslConfiguration::localCertificate() const

Returns the certificate this side presents.

See also setLocalCertificate().

QList<QSslCertificate> QSslConfiguration::localCertificateChain() const

Returns the local certificate and any intermediate certificates.

See also setLocalCertificateChain().

QByteArray QSslConfiguration::nextNegotiatedProtocol() const

Returns the application protocol agreed with the peer. This is set on the configuration returned by QSslSocket::sslConfiguration().

QSslCertificate QSslConfiguration::peerCertificate() const

Returns the peer's certificate. This is set on the configuration returned by QSslSocket::sslConfiguration().

QList<QSslCertificate> QSslConfiguration::peerCertificateChain() const

Returns the peer's certificate chain, leaf first. This is set on the configuration returned by QSslSocket::sslConfiguration().

int QSslConfiguration::peerVerifyDepth() const

Returns the longest certificate chain accepted; 0 means no limit.

See also setPeerVerifyDepth().

QSslSocket::PeerVerifyMode QSslConfiguration::peerVerifyMode() const

Returns how the peer is verified.

See also setPeerVerifyMode().

QSslKey QSslConfiguration::privateKey() const

Returns the private key of the local certificate.

See also setPrivateKey().

QSsl::SslProtocol QSslConfiguration::protocol() const

Returns the allowed TLS versions.

See also setProtocol().

QSslCipher QSslConfiguration::sessionCipher() const

Returns the cipher in use. This is set on the configuration returned by QSslSocket::sslConfiguration().

QSsl::SslProtocol QSslConfiguration::sessionProtocol() const

Returns the TLS version in use. This is set on the configuration returned by QSslSocket::sslConfiguration().

void QSslConfiguration::setAllowedNextProtocols(const QList<QByteArray> &protocols)

Sets the application protocols offered during the handshake to protocols, most preferred first, using ALPN.

See also nextNegotiatedProtocol().

void QSslConfiguration::setBackendConfiguration(const QMap<QByteArray, QVariant> &backendConfiguration = QMap<QByteArray, QVariant>())

Replaces all options of the TLS library with backendConfiguration. Without an argument, the options are removed.

See also setBackendConfigurationOption().

void QSslConfiguration::setBackendConfigurationOption(const QByteArray &name, const QVariant &value)

Sets the option name of the TLS library to value. The options are those of OpenSSL's configuration files, as SSL_CONF_cmd() documents them: Groups (or Curves) for the key exchange groups, SignatureAlgorithms, MinProtocol, MaxProtocol, Options and others. value is given to OpenSSL as text.

config.setBackendConfigurationOption("Groups", "P-384:P-521");

The options are applied when a handshake starts, in the order of their names and after the other settings of the configuration, which they can therefore override. If OpenSSL does not accept an option or its value, the handshake fails with SslInvalidUserDataError: a restriction that cannot be applied is never silently dropped.

See also backendConfiguration() and setBackendConfiguration().

void QSslConfiguration::setCaCertificates(const QList<QSslCertificate> &certificates)

Trusts only certificates, and no system certificates.

See also addCaCertificates().

void QSslConfiguration::setCiphers(const QList<QSslCipher> &ciphers)

Restricts the connection to the ciphers in ciphers, in that order of preference. Ciphers that are not among supportedCiphers() are left out. Only these ciphers are offered and accepted: a handshake with a peer that has none of them fails, and so does one with an empty list. TLS 1.3 and the earlier versions have separate sets of ciphers, so a list without any cipher of TLS 1.3 rules that version out, and a list with only such ciphers rules out the earlier ones.

See also ciphers() and supportedCiphers().

void QSslConfiguration::setCiphers(const QString &ciphers)

This is an overloaded function.

Restricts the connection to the ciphers named in ciphers, a list of names separated by colons, as in "TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES256-GCM-SHA384". A name that this build of OpenSSL does not know is left out, which makes the list shorter, never wider; if no name is known, every handshake fails.

[static] void QSslConfiguration::setDefaultConfiguration(const QSslConfiguration &configuration)

Sets the configuration new sockets start with to configuration.

See also defaultConfiguration().

void QSslConfiguration::setLocalCertificate(const QSslCertificate &certificate)

Sets the certificate this side presents to certificate.

See also localCertificate() and setPrivateKey().

void QSslConfiguration::setLocalCertificateChain(const QList<QSslCertificate> &localChain)

Sets the local certificate and intermediates to localChain, leaf first.

See also localCertificateChain().

void QSslConfiguration::setPeerVerifyDepth(int depth)

Sets the longest certificate chain accepted to depth.

See also peerVerifyDepth().

void QSslConfiguration::setPeerVerifyMode(QSslSocket::PeerVerifyMode mode)

Sets how the peer is verified to mode.

See also peerVerifyMode().

void QSslConfiguration::setPrivateKey(const QSslKey &key)

Sets the private key of the local certificate to key.

See also privateKey().

void QSslConfiguration::setProtocol(QSsl::SslProtocol protocol)

Sets the allowed TLS versions to protocol.

See also protocol().

[static] QList<QSslCipher> QSslConfiguration::supportedCiphers()

Returns the ciphers that this build of OpenSSL can use: every cipher with encryption and authentication, of TLS 1.3 and of the earlier versions. Many of them are not enabled by default; see ciphers().

See also setCiphers().

bool QSslConfiguration::usesSystemCaCertificates() const

Returns true if the system's trusted certificates are used.