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()
\internal
The default constructor, adds a new backend to the list of available backends.
See also ~QTlsBackend(), availableBackendNames(), and QSslSocket::availableBackends().
[override virtual noexcept]
QTlsBackend::~QTlsBackend()
\internal
Removes this backend from the list of available backends.
See also QTlsBackend(), availableBackendNames(), and QSslSocket::availableBackends().
[virtual]
QTlsPrivate::X509DerReaderPtr QTlsBackend::X509DerReader() const
\internal
Returns 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
\internal
Returns a pointer to function, that reads certificates in PEM format. The default implementation returns nullptr
.
See also QSslCertificate.
[virtual]
QTlsPrivate::X509Pkcs12ReaderPtr QTlsBackend::X509Pkcs12Reader() const
\internal
Returns 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
\internal
If 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()
\internal
Returns 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()
\internal
Returns 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)
\internal
Clears the peer certificate chain in configuration.
[static]
void QTlsBackend::clearPeerCertificates(QSslSocketPrivate *d)
\internal
Clears the peer certificate chain in d.
[virtual]
QTlsPrivate::X509Certificate *QTlsBackend::createCertificate() const
\internal
If 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)
\internal
Auxiliary 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)
\internal
Auxiliary 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)
\internal
Auxiliary 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
\internal
If 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
\internal
If 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
\internal
If 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
\internal
If 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
\internal
If 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()
\internal
Returns 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()
\internal
Returns an implementation-specific list of ciphersuites that can be used by QSslSocket.
See also setDefaultCiphers() and QSslConfiguration::defaultCiphers().
[static]
QList<QSslCipher> QTlsBackend::defaultDtlsCiphers()
\internal
Returns 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
\internal
If 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
\internal
If 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
\internal
If 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
\internal
QSslSocket 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)
\internal
Returns 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)
\internal
Returns 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
\internal
Returns 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
\internal
Returns 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
\internal
If 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)
\internal
Auxiliary function. Initializes key to use keyBackend.
[static]
void QTlsBackend::resetDefaultEllipticCurves()
\internal
Sets the list of QSslEllipticCurve objects, that QSslConfiguration::supportedEllipticCurves() returns, to ones that are supported by this backend.
[static]
bool QTlsBackend::rootLoadingOnDemandAllowed(const QSslConfiguration &configuration)
\internal
Returns true if configuration allows loading root certificates on demand.
[static]
void QTlsBackend::setAlpnStatus(QSslSocketPrivate *d, AlpnNegotiationStatus st)
\internal
Sets 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)
\internal
Sets ciphers as defaults ciphers that QSslSocket can use.
See also defaultCiphers().
[static]
void QTlsBackend::setDefaultDtlsCiphers(const QList<QSslCipher> &ciphers)
\internal
Sets ciphers as defaults ciphers that QDtls can use.
See also defaultDtlsCiphers().
[static]
void QTlsBackend::setDefaultSupportedCiphers(const QList<QSslCipher> &ciphers)
\internal
Sets 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)
\internal
Sets protocol in d as a negotiated application layer protocol.
[static]
void QTlsBackend::setPeerSessionShared(QSslSocketPrivate *d, bool shared)
\internal
Updates the configuration in d with shared value.
[static]
void QTlsBackend::setSessionAsn1(QSslSocketPrivate *d, const QByteArray &asn1)
\internal
Sets TLS session in d to asn1.
[static]
void QTlsBackend::setSessionLifetimeHint(QSslSocketPrivate *d, int hint)
\internal
Sets 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)
\internal
Auxiliary 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)
\internal
Auxiliary function. Initializes server-side auth using the identity, identityHint and maxPskLen.
[virtual]
QString QTlsBackend::shortNameForId(int cid) const
\internal
If 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)
\internal
Stores peerCert in the configuration.
[static]
void QTlsBackend::storePeerCertificate(QSslSocketPrivate *d, const QSslCertificate &peerCert)
\internal
Stores peerCert in the TLS configuration of d.
[static]
void QTlsBackend::storePeerCertificateChain(QSslConfiguration &configuration, const QList<QSslCertificate> &peerChain)
\internal
Stores 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)
\internal
Returns 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)
\internal
Returns 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
\internal
This 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
\internal
Returns 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
\internal
Returns 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
\internal
Returns 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
\internal
Returns 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().