QTlsBackend Class

QTlsBackend is a factory class, providing implementations for the QSsl classes. More...

Header: #include <QTlsBackend>
Inherits: QObject

Public Functions

QTlsBackend()
virtual ~QTlsBackend() override
virtual QTlsPrivate::X509DerReaderPtr X509DerReader() const
virtual QTlsPrivate::X509PemReaderPtr X509PemReader() const
virtual QTlsPrivate::X509Pkcs12ReaderPtr X509Pkcs12Reader() const
virtual QTlsPrivate::X509ChainVerifyPtr X509Verifier() const
virtual QTlsPrivate::X509Certificate *createCertificate() const
virtual QTlsPrivate::DtlsCookieVerifier *createDtlsCookieVerifier() const
virtual QTlsPrivate::TlsKey *createKey() const
virtual QTlsPrivate::TlsCryptograph *createTlsCryptograph() const
virtual int curveIdFromLongName(const QString &name) const
virtual int curveIdFromShortName(const QString &name) const
virtual int dhParametersFromDer(const QByteArray &derData, QByteArray *data) const
virtual int dhParametersFromPem(const QByteArray &pemData, QByteArray *data) const
virtual QList<int> ellipticCurvesIds() const
virtual void ensureInitialized() const
virtual void forceAutotestSecurityLevel()
virtual bool isTlsNamedCurve(int cid) const
virtual bool isValid() const
virtual QString longNameForId(int cid) const
virtual QString shortNameForId(int cid) const
virtual QList<QSslCertificate> systemCaCertificates() const
virtual long tlsLibraryBuildVersionNumber() const
virtual QString tlsLibraryBuildVersionString() const
virtual long tlsLibraryVersionNumber() const
virtual QString tlsLibraryVersionString() const

Static Public Members

QTlsBackend *activeOrAnyBackend()
void addTustedRoot(QSslSocketPrivate *d, const QSslCertificate &rootCert)
QList<QString> availableBackendNames()
void clearPeerCertificates(QSslConfiguration &configuration)
void clearPeerCertificates(QSslSocketPrivate *d)
QSslCipher createCipher(const QString &name, QSsl::SslProtocol protocol, const QString &protocolString)
QSslCipher createCiphersuite(const QString &descriptionOneLine, int bits, int supportedBits)
QSslCipher createCiphersuite(const QString &suiteName, QSsl::SslProtocol protocol, const QString &protocolString)
QString defaultBackendName()
QList<QSslCipher> defaultCiphers()
QList<QSslCipher> defaultDtlsCiphers()
QTlsBackend *findBackend(const QString &backendName)
QList<QSsl::ImplementedClass> implementedClasses(const QString &backendName)
void resetBackend(QSslKey &key, QTlsPrivate::TlsKey *keyBackend)
void resetDefaultEllipticCurves()
bool rootLoadingOnDemandAllowed(const QSslConfiguration &configuration)
void setAlpnStatus(QSslSocketPrivate *d, AlpnNegotiationStatus st)
void setDefaultCaCertificates(const QList<QSslCertificate> &certs)
void setDefaultCiphers(const QList<QSslCipher> &ciphers)
void setDefaultDtlsCiphers(const QList<QSslCipher> &ciphers)
void setDefaultSupportedCiphers(const QList<QSslCipher> &ciphers)
void setEphemeralKey(QSslSocketPrivate *d, const QSslKey &key)
void setNegotiatedProtocol(QSslSocketPrivate *d, const QByteArray &protocol)
void setPeerSessionShared(QSslSocketPrivate *d, bool shared)
void setSessionAsn1(QSslSocketPrivate *d, const QByteArray &asn1)
void setSessionLifetimeHint(QSslSocketPrivate *d, int hint)
void setupClientPskAuth(QSslPreSharedKeyAuthenticator *auth, const char *hint, int hintLength, unsigned int maxIdentityLen, unsigned int maxPskLen)
void setupServerPskAuth(QSslPreSharedKeyAuthenticator *auth, const char *identity, const QByteArray &identityHint, unsigned int maxPskLen)
void storePeerCertificate(QSslConfiguration &configuration, const QSslCertificate &peerCert)
void storePeerCertificate(QSslSocketPrivate *d, const QSslCertificate &peerCert)
void storePeerCertificateChain(QSslConfiguration &configuration, const QList<QSslCertificate> &peerChain)
void storePeerCertificateChain(QSslSocketPrivate *d, const QList<QSslCertificate> &peerChain)
QList<QSsl::SupportedFeature> supportedFeatures(const QString &backendName)
QList<QSsl::SslProtocol> supportedProtocols(const QString &backendName)

Detailed Description

\internal(Network-private)

The purpose of QTlsBackend is to enable and simplify the addition of new TLS backends to be used by QSslSocket and related classes. Starting from Qt 6.1, these backends have plugin-based design (and thus can co-exist simultaneously, unlike pre 6.1 times), although any given run of a program can only use one of them.

Inheriting from QTlsBackend and creating an object of such a class adds a new backend into the list of available TLS backends.

A new backend must provide a list of classes, features and protocols it supports, and override the corresponding virtual functions that create backend-specific implementations for these QSsl-classes.

The base abstract class - QTlsBackend - provides, where possible, default implementations of its virtual member functions. These default implementations can be overridden by a derived backend class, if needed.

QTlsBackend also provides some auxiliary functions that a derived backend class can use to interact with the internals of network-private classes.

See also QSslSocket::availableBackends(), supportedFeatures(), supportedProtocols(), and implementedClasses().

Member Function Documentation

QTlsBackend::QTlsBackend()

\internalThe default constructor, adds a new backend to the list of available backends.

See also ~QTlsBackend(), availableBackendNames(), and QSslSocket::availableBackends().

[override virtual noexcept] QTlsBackend::~QTlsBackend()

\internalRemoves this backend from the list of available backends.

See also QTlsBackend(), availableBackendNames(), and QSslSocket::availableBackends().

[virtual] QTlsPrivate::X509DerReaderPtr QTlsBackend::X509DerReader() const

\internalReturns a pointer to function, that can read certificates in DER format. The default implementation returns nullptr.

See also QSslCertificate.

[virtual] QTlsPrivate::X509PemReaderPtr QTlsBackend::X509PemReader() const

\internalReturns a pointer to function, that reads certificates in PEM format. The default implementation returns nullptr.

See also QSslCertificate.

[virtual] QTlsPrivate::X509Pkcs12ReaderPtr QTlsBackend::X509Pkcs12Reader() const

\internalReturns a pointer to function, that can read certificates in PKCS 12 format. The default implementation returns nullptr.

See also QSslCertificate.

[virtual] QTlsPrivate::X509ChainVerifyPtr QTlsBackend::X509Verifier() const

\internalIf QSsl::SupportedFeature::CertificateVerification is present in this backend's supportedFeatures(), the backend must reimplement this method to return a pointer to a function, that checks a certificate (or a chain of certificates) against available CA certificates. The default implementation returns nullptr.

See also supportedFeatures() and QSslCertificate.

[static] QTlsBackend *QTlsBackend::activeOrAnyBackend()

\internalReturns the backend that QSslSocket is using. If Qt was built without TLS support, this function returns a minimal backend that only supports QSslCertificate.

See also defaultBackend().

[static] void QTlsBackend::addTustedRoot(QSslSocketPrivate *d, const QSslCertificate &rootCert)

\internal

Adds rootCert to the list of trusted root certificates in d.

Note: In Qt 6.1 it's only used on Windows, during so called 'CA fetch'.

[static] QList<QString> QTlsBackend::availableBackendNames()

\internalReturns a list of names of available backends.

Note: This list contains only properly initialized backends.

See also QTlsBackend() and isValid().

[static] void QTlsBackend::clearPeerCertificates(QSslConfiguration &configuration)

\internalClears the peer certificate chain in configuration.

[static] void QTlsBackend::clearPeerCertificates(QSslSocketPrivate *d)

\internalClears the peer certificate chain in d.

[virtual] QTlsPrivate::X509Certificate *QTlsBackend::createCertificate() const

\internalIf QSsl::ImplementedClass::Certificate is present in this backend's implementedClasses(), the backend must reimplement this method to return a dynamically-allocated instance of an implementation-specific type, inheriting from the class QTlsPrivate::X509Certificate. The default implementation of this function returns nullptr.

See also QSslCertificate, QTlsPrivate::X509Certificate, and implementedClasses().

[static] QSslCipher QTlsBackend::createCipher(const QString &name, QSsl::SslProtocol protocol, const QString &protocolString)

\internalAuxiliary function. Creates a new QSslCipher from name (which is an implementation-specific string), protocol and protocolString, e.g.:

 createCipher(QStringLiteral("schannel"), QSsl::TlsV1_2, "TLSv1.2"_L1);

[static] QSslCipher QTlsBackend::createCiphersuite(const QString &descriptionOneLine, int bits, int supportedBits)

\internalAuxiliary function. Creates a new QSslCipher from descriptionOneLine, bits and supportedBits. descriptionOneLine consists of several fields, separated by whitespace. These include: cipher name, protocol version, key exchange method, authentication method, encryption method, message digest (Mac). Example: "ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD"

[static] QSslCipher QTlsBackend::createCiphersuite(const QString &suiteName, QSsl::SslProtocol protocol, const QString &protocolString)

\internalAuxiliary function. Creates a new QSslCipher from suiteName, protocol version and protocolString. For example:

 createCiphersuite("ECDHE-RSA-AES256-GCM-SHA256"_L1, QSsl::TlsV1_2, "TLSv1.2"_L1);

[virtual] QTlsPrivate::DtlsCookieVerifier *QTlsBackend::createDtlsCookieVerifier() const

\internalIf QSsl::ImplementedClass::DtlsCookie is present in this backend's implementedClasses(), the backend must reimplement this method to return a dynamically-allocated instance of an implementation-specific type, inheriting from the class QTlsPrivate::DtlsCookieVerifier. The default implementation returns nullptr.

See also QDtlsClientVerifier, QTlsPrivate::DtlsCookieVerifier, and implementedClasses().

[virtual] QTlsPrivate::TlsKey *QTlsBackend::createKey() const

\internalIf QSsl::ImplementedClass::Key is present in this backend's implementedClasses(), the backend must reimplement this method to return a dynamically-allocated instance of an implementation-specific type, inheriting from the class QTlsPrivate::TlsKey. The default implementation of this function returns nullptr.

See also QSslKey, implementedClasses(), and QTlsPrivate::TlsKey.

[virtual] QTlsPrivate::TlsCryptograph *QTlsBackend::createTlsCryptograph() const

\internalIf QSsl::ImplementedClass::Socket is present in this backend's implementedClasses(), the backend must reimplement this method to return a dynamically-allocated instance of an implementation-specific type, inheriting from the class QTlsPrivate::TlsCryptograph. The default implementation of this function returns nullptr.

See also QSslSocket, QTlsPrivate::TlsCryptograph, and implementedClasses().

[virtual] int QTlsBackend::curveIdFromLongName(const QString &name) const

\internalIf this backend provides information about available elliptic curves, this function should return a unique integer identifier for a curve named name, which is a conventional long name for the curve. The default implementation returns 0.

Note: The meaning of a curve identifier is implementation-specific.

See also QSslElliptiCurve::longName().

[virtual] int QTlsBackend::curveIdFromShortName(const QString &name) const

\internalIf this backend provides information about available elliptic curves, this function should return a unique integer identifier for a curve named name, which is a conventional short name for the curve. The default implementation returns 0.

Note: The meaning of a curve identifier is implementation-specific.

See also QSslEllipticCurve::shortName().

[static] QString QTlsBackend::defaultBackendName()

\internalReturns the name of the backend that QSslSocket() would use by default. If no backend was found, the function returns an empty string.

[static] QList<QSslCipher> QTlsBackend::defaultCiphers()

\internalReturns an implementation-specific list of ciphersuites that can be used by QSslSocket.

See also setDefaultCiphers() and QSslConfiguration::defaultCiphers().

[static] QList<QSslCipher> QTlsBackend::defaultDtlsCiphers()

\internalReturns an implementation-specific list of ciphersuites that can be used by QDtls.

See also setDefaultDtlsCiphers().

[virtual] int QTlsBackend::dhParametersFromDer(const QByteArray &derData, QByteArray *data) const

\internalIf this backend supports the class QSslDiffieHellmanParameters, this function is needed for construction of a QSslDiffieHellmanParameters from DER encoded data. This function is expected to return a value that matches an enumerator in QSslDiffieHellmanParameters::Error enumeration. The default implementation of this function returns 0 (equals to QSslDiffieHellmanParameters::NoError).

See also QSslDiffieHellmanParameters and implementedClasses().

[virtual] int QTlsBackend::dhParametersFromPem(const QByteArray &pemData, QByteArray *data) const

\internalIf this backend supports the class QSslDiffieHellmanParameters, this function is is needed for construction of a QSslDiffieHellmanParameters from PEM encoded data. This function is expected to return a value that matches an enumerator in QSslDiffieHellmanParameters::Error enumeration. The default implementation of this function returns 0 (equals to QSslDiffieHellmanParameters::NoError).

See also QSslDiffieHellmanParameters and implementedClasses().

[virtual] QList<int> QTlsBackend::ellipticCurvesIds() const

\internalIf QSsl::ImplementedClass::EllipticCurve is present in this backend's implementedClasses(), and the backend provides information about supported curves, it must reimplement this method to return a list of unique identifiers of the supported elliptic curves. The default implementation returns an empty list.

Note: The meaning of a curve identifier is implementation-specific.

See also implemenedClasses() and QSslEllipticCurve.

[virtual] void QTlsBackend::ensureInitialized() const

\internalQSslSocket and related classes call this function to ensure that backend's internal resources - e.g. CA certificates, or ciphersuites - were properly initialized.

[static] QTlsBackend *QTlsBackend::findBackend(const QString &backendName)

\internalReturns a backend named backendName, if it exists. Otherwise, it returns nullptr.

See also backendName() and QSslSocket::availableBackends().

[virtual] void QTlsBackend::forceAutotestSecurityLevel()

\internal

Implementation-specific. Sets the security level suitable for Qt's auto-tests.

[static] QList<QSsl::ImplementedClass> QTlsBackend::implementedClasses(const QString &backendName)

\internalReturns a list of classes that a backend named backendName supports. E.g. a backend may implement QSslSocket (QSsl::ImplementedClass::Socket), and QDtls (QSsl::ImplementedClass::Dtls).

See also QSsl::ImplementedClass.

[virtual] bool QTlsBackend::isTlsNamedCurve(int cid) const

\internalReturns true if the elliptic curve identified by cid is one of the named curves, that can be used in the key exchange when using an elliptic curve cipher with TLS; false otherwise. The default implementation returns false.

Note: The meaning of curve identifier is implementation-specific.

[virtual] bool QTlsBackend::isValid() const

\internalReturns true if this backend was initialised successfully. The default implementation always returns true.

Note: This function must be overridden if a particular backend has a non-trivial initialization that can fail. If reimplemented, returning false will exclude this backend from the list of backends, reported as available by QSslSocket.

See also QSslSocket::availableBackends().

[virtual] QString QTlsBackend::longNameForId(int cid) const

\internalIf this backend provides information about available elliptic curves, this function should return a conventional long name for a curve identified by cid. The default implementation returns an empty string.

Note: The meaning of a curve identifier is implementation-specific.

See also ellipticCurvesIds() and QSslEllipticCurve::shortName().

[static] void QTlsBackend::resetBackend(QSslKey &key, QTlsPrivate::TlsKey *keyBackend)

\internalAuxiliary function. Initializes key to use keyBackend.

[static] void QTlsBackend::resetDefaultEllipticCurves()

\internalSets the list of QSslEllipticCurve objects, that QSslConfiguration::supportedEllipticCurves() returns, to ones that are supported by this backend.

[static] bool QTlsBackend::rootLoadingOnDemandAllowed(const QSslConfiguration &configuration)

\internalReturns true if configuration allows loading root certificates on demand.

[static] void QTlsBackend::setAlpnStatus(QSslSocketPrivate *d, AlpnNegotiationStatus st)

\internalSets application layer protocol negotiation status in d to st.

[static] void QTlsBackend::setDefaultCaCertificates(const QList<QSslCertificate> &certs)

Sets certs as a list of certificates, that QSslConfiguration::caCertificates() reports.

See also QSslConfiguration::defaultConfiguration() and QSslConfiguration::caCertificates().

[static] void QTlsBackend::setDefaultCiphers(const QList<QSslCipher> &ciphers)

\internalSets ciphers as defaults ciphers that QSslSocket can use.

See also defaultCiphers().

[static] void QTlsBackend::setDefaultDtlsCiphers(const QList<QSslCipher> &ciphers)

\internalSets ciphers as defaults ciphers that QDtls can use.

See also defaultDtlsCiphers().

[static] void QTlsBackend::setDefaultSupportedCiphers(const QList<QSslCipher> &ciphers)

\internalSets ciphers as a list of supported ciphers.

See also QSslConfiguration::supportedCiphers().

[static] void QTlsBackend::setEphemeralKey(QSslSocketPrivate *d, const QSslKey &key)

\internal

Saves ephemeral key in d.

See also QSslConfiguration::ephemeralKey().

[static] void QTlsBackend::setNegotiatedProtocol(QSslSocketPrivate *d, const QByteArray &protocol)

\internalSets protocol in d as a negotiated application layer protocol.

[static] void QTlsBackend::setPeerSessionShared(QSslSocketPrivate *d, bool shared)

\internalUpdates the configuration in d with shared value.

[static] void QTlsBackend::setSessionAsn1(QSslSocketPrivate *d, const QByteArray &asn1)

\internalSets TLS session in d to asn1.

[static] void QTlsBackend::setSessionLifetimeHint(QSslSocketPrivate *d, int hint)

\internalSets TLS session lifetime hint in d to hint.

[static] void QTlsBackend::setupClientPskAuth(QSslPreSharedKeyAuthenticator *auth, const char *hint, int hintLength, unsigned int maxIdentityLen, unsigned int maxPskLen)

\internalAuxiliary function. Initializes client-side auth using the hint, hintLength, maxIdentityLength and maxPskLen.

[static] void QTlsBackend::setupServerPskAuth(QSslPreSharedKeyAuthenticator *auth, const char *identity, const QByteArray &identityHint, unsigned int maxPskLen)

\internalAuxiliary function. Initializes server-side auth using the identity, identityHint and maxPskLen.

[virtual] QString QTlsBackend::shortNameForId(int cid) const

\internalIf this backend provides information about available elliptic curves, this function should return a conventional short name for a curve identified by cid. The default implementation returns an empty string.

Note: The meaning of a curve identifier is implementation-specific.

See also ellipticCurvesIds() and QSslEllipticCurve::shortName().

[static] void QTlsBackend::storePeerCertificate(QSslConfiguration &configuration, const QSslCertificate &peerCert)

\internalStores peerCert in the configuration.

[static] void QTlsBackend::storePeerCertificate(QSslSocketPrivate *d, const QSslCertificate &peerCert)

\internalStores peerCert in the TLS configuration of d.

[static] void QTlsBackend::storePeerCertificateChain(QSslConfiguration &configuration, const QList<QSslCertificate> &peerChain)

\internalStores peerChain in the configuration.

[static] void QTlsBackend::storePeerCertificateChain(QSslSocketPrivate *d, const QList<QSslCertificate> &peerChain)

\internal

Stores peerChain in the TLS configuration of d.

Note: This is a helper function that TlsCryptograph and DtlsCryptograph call during a handshake.

[static] QList<QSsl::SupportedFeature> QTlsBackend::supportedFeatures(const QString &backendName)

\internalReturns a list of features that a backend named backendName supports. E.g. a backend may support PSK (pre-shared keys, defined as QSsl::SupportedFeature::Psk) or ALPN (application layer protocol negotiation, identified by QSsl::SupportedFeature::ClientSideAlpn or QSsl::SupportedFeature::ServerSideAlpn).

See also QSsl::SupportedFeature.

[static] QList<QSsl::SslProtocol> QTlsBackend::supportedProtocols(const QString &backendName)

\internalReturns a list of TLS and DTLS protocol versions, that a backend named backendName supports.

Note: This list is supposed to also include range-based versions, which allows negotiation of protocols during the handshake, so that these versions can be used when configuring QSslSocket (e.g. QSsl::TlsV1_2OrLater).

See also QSsl::SslProtocol.

[virtual] QList<QSslCertificate> QTlsBackend::systemCaCertificates() const

\internalThis function returns a list of system CA certificates - e.g. certificates, loaded from a system store, if available. This function allows implementation of the class QSslConfiguration. The default implementation of this function returns an empty list.

See also QSslCertificate and QSslConfiguration.

[virtual] long QTlsBackend::tlsLibraryBuildVersionNumber() const

\internalReturns an implementation-specific integer value, representing the TLS library's version that this backend was built against (i.e. compile-time library version). The default implementation returns 0.

See also tlsLibraryVersionNumber().

[virtual] QString QTlsBackend::tlsLibraryBuildVersionString() const

\internalReturns an implementation-specific string, representing the TLS library's version that this backend was built against (i.e. compile-time version). The default implementation returns an empty string.

See also tlsLibraryVersionString().

[virtual] long QTlsBackend::tlsLibraryVersionNumber() const

\internalReturns an implementations-specific integer value, representing the TLS library's version, that is currently used by this backend (i.e. runtime library version). The default implementation returns 0.

See also tlsLibraryBuildVersionNumber().

[virtual] QString QTlsBackend::tlsLibraryVersionString() const

\internalReturns an implementation-specific string, representing the TLS library's version, that is currently used by this backend (i.e. runtime library version). The default implementation returns an empty string.

See also tlsLibraryBuildVersionString().