QSslConfiguration Class

QSslConfiguration 类保存 SSL 连接的配置和状态。更多

头文件: #include <QSslConfiguration>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network

注意:该类中的所有函数都是可重入的

公共类型

enum NextProtocolNegotiationStatus { NextProtocolNegotiationNone, NextProtocolNegotiationNegotiated, NextProtocolNegotiationUnsupported }

公共函数

QSslConfiguration()
QSslConfiguration(const QSslConfiguration &other)
~QSslConfiguration()
void addCaCertificate(const QSslCertificate &certificate)
void addCaCertificates(const QList<QSslCertificate> &certificates)
bool addCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem, QSslCertificate::PatternSyntax syntax = QSslCertificate::PatternSyntax::FixedString)
QList<QByteArray> allowedNextProtocols() const
QMap<QByteArray, QVariant> backendConfiguration() const
QList<QSslCertificate> caCertificates() const
QList<QSslCipher> ciphers() const
QSslDiffieHellmanParameters diffieHellmanParameters() const
bool dtlsCookieVerificationEnabled() const
QList<QSslEllipticCurve> ellipticCurves() const
QSslKey ephemeralServerKey() const
(since 6.0) bool handshakeMustInterruptOnError() const
bool isNull() const
QSslCertificate localCertificate() const
QList<QSslCertificate> localCertificateChain() const
(since 6.0) bool missingCertificateIsFatal() const
QByteArray nextNegotiatedProtocol() const
QSslConfiguration::NextProtocolNegotiationStatus nextProtocolNegotiationStatus() const
bool ocspStaplingEnabled() const
QSslCertificate peerCertificate() const
QList<QSslCertificate> peerCertificateChain() const
int peerVerifyDepth() const
QSslSocket::PeerVerifyMode peerVerifyMode() const
QByteArray preSharedKeyIdentityHint() const
QSslKey privateKey() const
QSsl::SslProtocol protocol() const
QSslCipher sessionCipher() const
QSsl::SslProtocol sessionProtocol() const
QByteArray sessionTicket() const
int sessionTicketLifeTimeHint() const
void setAllowedNextProtocols(const QList<QByteArray> &protocols)
void setBackendConfiguration(const QMap<QByteArray, QVariant> &backendConfiguration = QMap<QByteArray, QVariant>())
void setBackendConfigurationOption(const QByteArray &name, const QVariant &value)
void setCaCertificates(const QList<QSslCertificate> &certificates)
void setCiphers(const QList<QSslCipher> &ciphers)
(since 6.0) void setCiphers(const QString &ciphers)
void setDiffieHellmanParameters(const QSslDiffieHellmanParameters &dhparams)
void setDtlsCookieVerificationEnabled(bool enable)
void setEllipticCurves(const QList<QSslEllipticCurve> &curves)
(since 6.0) void setHandshakeMustInterruptOnError(bool interrupt)
void setLocalCertificate(const QSslCertificate &certificate)
void setLocalCertificateChain(const QList<QSslCertificate> &localChain)
(since 6.0) void setMissingCertificateIsFatal(bool cannotRecover)
void setOcspStaplingEnabled(bool enabled)
void setPeerVerifyDepth(int depth)
void setPeerVerifyMode(QSslSocket::PeerVerifyMode mode)
void setPreSharedKeyIdentityHint(const QByteArray &hint)
void setPrivateKey(const QSslKey &key)
void setProtocol(QSsl::SslProtocol protocol)
void setSessionTicket(const QByteArray &sessionTicket)
void setSslOption(QSsl::SslOption option, bool on)
void swap(QSslConfiguration &other)
bool testSslOption(QSsl::SslOption option) const
bool operator!=(const QSslConfiguration &other) const
QSslConfiguration &operator=(const QSslConfiguration &other)
bool operator==(const QSslConfiguration &other) const

静态公共成员

const char[] ALPNProtocolHTTP2
const char[] NextProtocolHttp1_1
QSslConfiguration defaultConfiguration()
QSslConfiguration defaultDtlsConfiguration()
void setDefaultConfiguration(const QSslConfiguration &configuration)
void setDefaultDtlsConfiguration(const QSslConfiguration &configuration)
QList<QSslCipher> supportedCiphers()
QList<QSslEllipticCurve> supportedEllipticCurves()
QList<QSslCertificate> systemCaCertificates()

详细说明

QSslConfiguration 被 Qt Network 类用于传递有关打开的 SSL 连接的信息,并允许应用程序控制该连接的某些功能。

QSslConfiguration 当前支持的设置有

  • 要使用的 SSL/TLS 协议
  • 连接期间要向对等方出示的证书及其相关私钥
  • 允许用于加密连接的密码
  • 用于验证对等方证书的证书颁发机构证书列表

这些设置仅在连接握手时应用。在连接建立后再进行设置不会有任何影响。

QSslConfiguration 支持的状态有

  • 对等方在握手期间提交的证书,以及指向 CA 证书的链
  • 用于加密此会话的密码

只有在 SSL 连接开始后才能获得这些状态,但不一定能在连接完成前获得。某些设置可能会在 SSL 连接过程中发生变化,而不需要重新启动(例如,密码可能会随着时间的推移而改变)。

QSslConfiguration 对象中的状态不能更改。

QSslConfiguration 可与QSslSocket 和网络访问 API 一起使用。

请注意,更改 QSslConfiguration 中的设置不足以更改相关 SSL 连接中的设置。为此,必须在修改后的 QSslConfiguration 对象上调用 setSslConfiguration。下面的示例说明了如何在QSslSocket 对象中将协议更改为 TLSv1_2:

QSslConfiguration config = sslSocket.sslConfiguration();
config.setProtocol(QSsl::TlsV1_2);
sslSocket.setSslConfiguration(config);

另请参阅 QSsl::SslProtocol,QSslCertificate,QSslCipher,QSslKey,QSslSocket,QNetworkAccessManager,QSslSocket::sslConfiguration() 和QSslSocket::setSslConfiguration() 。

成员类型文档

enum QSslConfiguration::NextProtocolNegotiationStatus

描述下一步协议协商(NPN)或应用层协议协商(ALPN)的状态。

常数说明
QSslConfiguration::NextProtocolNegotiationNone0尚未协商应用协议。
QSslConfiguration::NextProtocolNegotiationNegotiated1已协商下一协议(见nextNegotiatedProtocol() )。
QSslConfiguration::NextProtocolNegotiationUnsupported2客户端和服务器无法就共同的下一个应用协议达成一致。

成员函数文档

QSslConfiguration::QSslConfiguration()

构造空 SSL 配置。该配置不包含任何有效设置,其状态也将是空的。调用该构造函数后,isNull() 将返回 true。

一旦调用任何设置器方法,isNull() 将返回 false。

QSslConfiguration::QSslConfiguration(const QSslConfiguration &other)

复制other 的配置和状态。如果other 为空,此对象也将为空。

[noexcept] QSslConfiguration::~QSslConfiguration()

释放QSslConfiguration 持有的任何资源。

void QSslConfiguration::addCaCertificate(const QSslCertificate &certificate)

certificate 添加到此配置的 CA 证书数据库。证书数据库必须在 SSL 握手之前设置。在握手阶段,套接字会使用 CA 证书数据库来验证对等方的证书。

注意: 默认配置使用系统 CA 证书数据库。如果系统 CA 证书数据库不可用(在 iOS 上通常是这种情况),则默认数据库为空。

另请参阅 caCertificates()、setCaCertificates() 和addCaCertificates()。

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

certificates 添加到此配置的 CA 证书数据库。证书数据库必须在 SSL 握手之前设置。在握手阶段,套接字会使用 CA 证书数据库来验证对等方的证书。

注意: 默认配置使用系统 CA 证书数据库。如果系统 CA 证书数据库不可用(在 iOS 上通常是这种情况),则默认数据库为空。

另请参阅 caCertificates()、setCaCertificates() 和addCaCertificate()。

bool QSslConfiguration::addCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem, QSslCertificate::PatternSyntax syntax = QSslCertificate::PatternSyntax::FixedString)

搜索path 中的所有文件,查找以指定format 编码的证书,并将其添加到该套接字的 CA 证书数据库。path 必须是一个文件或与一个或多个文件匹配的模式,如syntax 所指定。如果一个或多个证书已添加到套接字的 CA 证书数据库,则返回true ;否则返回false

在握手阶段,套接字会使用 CA 证书数据库来验证对等方的证书。

如需更精确的控制,请使用addCaCertificate() 。

另请参阅 addCaCertificate() 和QSslCertificate::fromPath()。

QList<QByteArray> QSslConfiguration::allowedNextProtocols() const

该函数返回允许通过下一协议协商(NPN)或应用层协议协商(ALPN)TLS 扩展与服务器协商的协议,由setAllowedNextProtocols() 设置。

另请参见 nextNegotiatedProtocol()、nextProtocolNegotiationStatus()、setAllowedNextProtocols() 和QSslConfiguration::NextProtocolHttp1_1

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

返回后端特定配置。

只有通过setBackendConfigurationOption() 或setBackendConfiguration() 设置的选项才会被返回。不报告后端内部标准配置。

另请参阅 setBackendConfigurationOption() 和setBackendConfiguration()。

QList<QSslCertificate> QSslConfiguration::caCertificates() const

返回此连接的 CA 证书数据库。在握手阶段,套接字会使用 CA 证书数据库来验证对等方的证书。可以使用setCaCertificates() 或addCaCertificate() 和addCaCertificates() 在握手之前修改该数据库。

另请参阅 setCaCertificates()、addCaCertificate() 和addCaCertificates()。

QList<QSslCipher> QSslConfiguration::ciphers() const

返回此连接的当前密码套件。该列表用于在握手阶段选择会话密码。返回的密码列表按优先级降序排列。(也就是说,列表中的第一个密码是最优先的密码)。会话密码将是列表中第一个也受对等方支持的密码。

默认情况下,握手阶段可以选择本系统 SSL 库支持的任何一种密码,不同系统支持的密码可能不同。本系统 SSL 库支持的密码列表由supportedCiphers() 返回。通过调用setCiphers() 并使用支持的密码子集,可以限制用于为该套接字选择会话密码的密码列表。您可以使用supportedCiphers() 返回的列表调用setCiphers() 恢复使用整套密码。

另请参阅 setCiphers() 和supportedCiphers()。

[static] QSslConfiguration QSslConfiguration::defaultConfiguration()

返回新 SSL 连接中使用的默认 SSL 配置。

默认 SSL 配置包括

  • 无本地证书和私钥
  • 协议SecureProtocols
  • 系统默认 CA 证书列表
  • 密码列表,等于 SSL 库支持的 128 位或以上 SSL 密码列表

另请参阅 supportedCiphers() 和setDefaultConfiguration()。

[static] QSslConfiguration QSslConfiguration::defaultDtlsConfiguration()

返回用于新 DTLS 连接的默认 DTLS 配置。

默认 DTLS 配置包括

  • 无本地证书和私钥
  • 协议 DtlsV1_2OrLater
  • 系统默认 CA 证书列表
  • 密码列表,等于 SSL 库支持的 TLS 1.2 密码列表,密码使用 128 位或更多密钥。

另请参阅 setDefaultDtlsConfiguration()。

QSslDiffieHellmanParameters QSslConfiguration::diffieHellmanParameters() const

读取当前的 Diffie-Hellman 参数集。

如果没有设置 Diffie-Hellman 参数,QSslConfiguration 对象默认使用 RFC 3526 中的 2048 位 MODP 组。

注意: 默认参数可能会在未来的 Qt 版本中发生变化。请查看您正在使用的Qt 版本的确切文档,以了解该版本使用的默认值。

另请参阅 setDiffieHellmanParameters()。

bool QSslConfiguration::dtlsCookieVerificationEnabled() const

如果在服务器端套接字上启用了 DTLS cookie 校验,则此函数返回 true。

另请参见 setDtlsCookieVerificationEnabled()。

QList<QSslEllipticCurve> QSslConfiguration::ellipticCurves() const

返回此连接当前的椭圆曲线列表。该列表用于在握手阶段选择椭圆曲线(使用椭圆曲线密码时)。返回的曲线列表按优先级降序排列(即列表中的第一条曲线是最优先的曲线)。

默认情况下,握手阶段可以选择本系统 SSL 库支持的任何曲线,不同系统支持的曲线可能不同。本系统 SSL 库支持的曲线列表由 QSslSocket::supportedEllipticCurves() 返回。

通过调用setEllipticCurves() 并使用所支持密码的子集,可以限制用于为该套接字选择会话密码的曲线列表。您可以使用 QSslSocket::supportedEllipticCurves() 返回的列表调用setEllipticCurves() 来恢复使用整个加密集。

另请参见 setEllipticCurves

QSslKey QSslConfiguration::ephemeralServerKey() const

返回用于前向保密密码算法(如 DHE-RSA-AES128-SHA)的服务器临时密钥。

只有在客户端模式(即QSslSocket::SslClientMode )下运行时,短暂密钥才可用。在服务器模式下运行或使用不带前向保密功能的密码算法时,返回的密钥为空。短暂服务器密钥将在发出 encrypted() 信号前设置。

[since 6.0] bool QSslConfiguration::handshakeMustInterruptOnError() const

如果验证回调在握手结束前提前发出QSslSocket::handshakeInterruptedOnError() 返回 true。

注意: 对于除 OpenSSL 之外的所有后端,该函数总是返回 false。

此函数在 Qt 6.0 中引入。

另请参阅 setHandshakeMustInterruptOnError()、QSslSocket::handshakeInterruptedOnError() 和QSslSocket::continueInterruptedHandshake()。

bool QSslConfiguration::isNull() const

如果QSslConfiguration 对象为空,则返回true

如果QSslConfiguration 对象是默认构造的,且未调用任何设置方法,则该对象为空。

另请参阅 setProtocol()、setLocalCertificate()、setPrivateKey()、setCiphers() 和setCaCertificates()。

QSslCertificate QSslConfiguration::localCertificate() const

返回将在 SSL 握手过程中提交给对等方的证书。

另请参阅 setLocalCertificate()。

QList<QSslCertificate> QSslConfiguration::localCertificateChain() const

返回将在 SSL 握手过程中提交给对等方的证书链。

另请参阅 setLocalCertificateChain() 和localCertificate()。

[since 6.0] bool QSslConfiguration::missingCertificateIsFatal() const

如果不能忽略代码为QSslError::NoPeerCertificate 的错误,则返回 true。

注意: 对于除 OpenSSL 之外的所有 TLS 后端,总是返回 false。

此函数在 Qt 6.0 中引入。

另请参阅 QSslSocket::ignoreSslErrors() 和setMissingCertificateIsFatal()。

QByteArray QSslConfiguration::nextNegotiatedProtocol() const

如果启用了下一协议协商(NPN)或应用层协议协商(ALPN)TLS 扩展,则该函数返回与服务器协商的协议。要启用 NPN/ALPN 扩展,需要在连接服务器之前明确调用setAllowedNextProtocols() 。

如果无法协商协议或未启用扩展,该函数将返回QByteArray ,即空值。

另请参阅 setAllowedNextProtocols() 和nextProtocolNegotiationStatus()。

QSslConfiguration::NextProtocolNegotiationStatus QSslConfiguration::nextProtocolNegotiationStatus() const

该函数返回下一步协议协商(NPN)或应用层协议协商(ALPN)的状态。如果尚未通过setAllowedNextProtocols() 启用该功能,该函数将返回NextProtocolNegotiationNone 。状态将在发出 encrypted() 信号前设置。

另请参阅 setAllowedNextProtocols()、allowedNextProtocols()、nextNegotiatedProtocol() 和QSslConfiguration::NextProtocolNegotiationStatus

bool QSslConfiguration::ocspStaplingEnabled() const

如果通过 setOCSPStaplingEnabled() 启用了 OCSP 装订,则返回 true,否则返回 false(默认值)。

另请参阅 setOcspStaplingEnabled().

QSslCertificate QSslConfiguration::peerCertificate() const

返回对等方的数字证书(即所连接主机的直接证书),如果对等方未分配证书,则返回空证书。

在握手阶段会自动检查对等方证书,因此该函数通常用于获取证书以显示或诊断连接。它包含对等方的信息,包括主机名、证书颁发者和对等方的公钥。

由于对等证书是在握手阶段设置的,因此从连接到QSslSocket::sslErrors() 信号、QNetworkReply::sslErrors() 信号或QSslSocket::encrypted() 信号的插槽访问对等证书是安全的。

如果返回空证书,可能意味着 SSL 握手失败,也可能意味着所连接的主机没有证书,还可能意味着没有连接。

如果想检查对等方的完整证书链,可使用peerCertificateChain() 一次获取所有证书。

另请参阅 peerCertificateChain()、QSslSocket::sslErrors()、QSslSocket::ignoreSslErrors()、QNetworkReply::sslErrors() 和QNetworkReply::ignoreSslErrors()。

QList<QSslCertificate> QSslConfiguration::peerCertificateChain() const

返回对等方的数字证书链,从对等方的直接证书开始,到 CA 的证书结束。

在握手阶段会自动检查对等方证书。该函数通常用于获取证书以供显示或执行连接诊断。证书包含对等方和证书颁发者的信息,包括主机名、颁发者名称和颁发者公钥。

由于对等证书是在握手阶段设置的,因此从连接到QSslSocket::sslErrors() 信号、QNetworkReply::sslErrors() 信号或QSslSocket::encrypted() 信号的插槽访问对等证书是安全的。

如果返回的是空列表,可能意味着 SSL 握手失败,也可能意味着所连接的主机没有证书,还可能意味着没有连接。

如果只想获取对等方的即时证书,请使用peerCertificate() 。

另请参阅 peerCertificate()、QSslSocket::sslErrors()、QSslSocket::ignoreSslErrors()、QNetworkReply::sslErrors() 和QNetworkReply::ignoreSslErrors()。

int QSslConfiguration::peerVerifyDepth() const

返回在 SSL 握手阶段要检查的对等方证书链中证书的最大数量,如果没有设置最大深度,则返回 0(默认值),表示要检查整个证书链。

证书按签发顺序检查,从对等方自己的证书开始,然后是其签发者的证书,依此类推。

另请参阅 setPeerVerifyDepth() 和peerVerifyMode()。

QSslSocket::PeerVerifyMode QSslConfiguration::peerVerifyMode() const

返回验证模式。该模式决定QSslSocket 是否应向对等方请求证书(即客户端向服务器请求证书,还是服务器向客户端请求证书),以及是否应要求该证书有效。

默认模式为 AutoVerifyPeer,即告诉QSslSocket 对客户端使用 VerifyPeer,对服务器使用 QueryPeer。

另请参见 setPeerVerifyMode().

QByteArray QSslConfiguration::preSharedKeyIdentityHint() const

返回身份提示。

另请参阅 setPreSharedKeyIdentityHint()。

QSslKey QSslConfiguration::privateKey() const

返回分配给此连接的SSL key ,如果尚未分配任何键,则返回空键。

另请参阅 setPrivateKey() 和localCertificate()。

QSsl::SslProtocol QSslConfiguration::protocol() const

返回此 SSL 配置的协议设置。

另请参阅 setProtocol()。

QSslCipher QSslConfiguration::sessionCipher() const

返回套接字的密码cipher ,如果连接未加密,则返回空密码。会话的套接字密码在握手阶段设置。密码用于加密和解密通过套接字传输的数据。

SSL 基础架构还提供了设置密码有序列表的功能,握手阶段最终将从列表中选择会话密码。该有序列表必须在握手阶段开始前准备就绪。

另请参阅 ciphers()、setCiphers() 和supportedCiphers()。

QSsl::SslProtocol QSslConfiguration::sessionProtocol() const

返回套接字的 SSL/TLS 协议,如果连接未加密,则返回 UnknownProtocol。会话的套接字协议在握手阶段设置。

另请参阅 protocol() 和setProtocol()。

QByteArray QSslConfiguration::sessionTicket() const

如果QSsl::SslOptionDisableSessionPersistence 已关闭,则该函数将以 ASN.1 格式返回 SSL 握手过程中使用的会话票据,适合持久化到磁盘等。如果未使用会话协议或QSsl::SslOptionDisableSessionPersistence 未关闭,则该函数将返回空QByteArray

注意: 将会话票据持久化到磁盘或类似文件时,请注意不要将会话暴露给潜在的攻击者,因为知道了会话就可以窃听用会话参数加密的数据。

另请参阅 setSessionTicket(),QSsl::SslOptionDisableSessionPersistence,setSslOption() 和QSslSocket::newSessionTicketReceived() 。

int QSslConfiguration::sessionTicketLifeTimeHint() const

如果QSsl::SslOptionDisableSessionPersistence 已关闭,则此函数将返回服务器发送的会话票据寿命提示(可能为 0)。如果服务器没有发送会话票据(例如在恢复会话时或服务器不支持会话票据时),或QSsl::SslOptionDisableSessionPersistence 没有关闭,则此函数返回-1。

另请参阅 sessionTicket()、QSsl::SslOptionDisableSessionPersistencesetSslOption() 和QSslSocket::newSessionTicketReceived()。

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

该函数设置允许通过下一协议协商(NPN)或应用层协议协商(ALPN)TLS 扩展与服务器协商的protocolsprotocols 中的每个元素必须定义一个允许的协议。连接前必须明确调用该函数,以便在 SSL 握手过程中发送 NPN/ALPN 扩展。协商是否成功可通过nextProtocolNegotiationStatus() 查询。

另请参阅 nextNegotiatedProtocol(),nextProtocolNegotiationStatus(),allowedNextProtocols() 和QSslConfiguration::NextProtocolHttp1_1

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

设置或清除后端特定配置。

如果没有backendConfiguration 参数,该函数将清除后端特定配置。有关支持选项的更多信息,请参阅setBackendConfigurationOption() 文档。

另请参阅 backendConfiguration() 和setBackendConfigurationOption()。

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

将后端特定配置中的选项name 设置为value

OpenSSL (>= 1.0.2) 后端支持的选项可参见支持的配置文件命令文档。value 参数的预期类型是QByteArray ,适用于所有选项。示例展示了如何使用部分选项。

注意: 后端特定配置将在常规配置之后应用。使用后端特定配置再次设置常规配置选项将覆盖常规配置选项。

另请参阅 backendConfiguration() 和setBackendConfiguration()。

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

将此套接字的 CA 证书数据库设置为certificates 。证书数据库必须在 SSL 握手之前设置。在握手阶段,套接字会使用 CA 证书数据库来验证对等方的证书。

注意: 默认配置使用系统 CA 证书数据库。如果系统 CA 证书数据库不可用(在 iOS 上通常是这种情况),则默认数据库为空。

另请参阅 caCertificates()、addCaCertificates() 和addCaCertificate()。

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

将此套接字的密码套件设置为ciphers ,其中必须包含supportedCiphers() 返回的列表中密码的子集。

限制密码套件必须在选择会话密码的握手阶段之前完成。

另请参阅 ciphers() 和supportedCiphers()。

[since 6.0] void QSslConfiguration::setCiphers(const QString &ciphers)

将此配置的密码套件设置为ciphers ,这是一个以冒号分隔的密码套件名称列表。密码按优先顺序排列,从最优先的密码开始。ciphers 中的每个密码名称必须是supportedCiphers() 返回的列表中的密码名称。限制密码套件必须在选择会话密码的握手阶段之前完成。

注意: 使用 Schannel 后端时,密码的顺序会被忽略,Schannel 会在握手过程中选择最安全的密码。

此函数在 Qt 6.0 中引入。

另请参阅 ciphers()。

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

将用于新 SSL 连接的默认 SSL 配置设置为configuration 。现有连接不受此调用影响。

另请参阅 supportedCiphers() 和defaultConfiguration()。

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

将用于新 DTLS 连接的默认 DTLS 配置设置为configuration 。现有连接不受此调用影响。

另请参阅 defaultDtlsConfiguration().

void QSslConfiguration::setDiffieHellmanParameters(const QSslDiffieHellmanParameters &dhparams)

设置一组自定义的 Diffie-Hellman 参数,供该套接字在作为dhparams 服务器时使用。

如果没有设置 Diffie-Hellman 参数,QSslConfiguration 对象默认使用 RFC 3526 中的 2048 位 MODP 组。

自 6.7 版起,如果 tls 后端支持自动选择(参见 openssl 的 SSL_CTX_set_dh_auto),则可以提供一个空的 Diffie-Hellman 参数。

注意: 默认参数可能会在未来的 Qt 版本中发生变化。请查看您正在使用的Qt 版本的确切文档,以了解该版本使用的默认值。

另请参阅 diffieHellmanParameters().

void QSslConfiguration::setDtlsCookieVerificationEnabled(bool enable)

enable 为 true 时,该函数将启用 DTLS cookie 验证。

另请参见 dtlsCookieVerificationEnabled().

void QSslConfiguration::setEllipticCurves(const QList<QSslEllipticCurve> &curves)

将此套接字使用的椭圆曲线列表设置为curves ,其中必须包含supportedEllipticCurves() 返回的列表中曲线的子集。

限制椭圆曲线必须在选择会话密码的握手阶段之前完成。

另请参见 ellipticCurves

[since 6.0] void QSslConfiguration::setHandshakeMustInterruptOnError(bool interrupt)

如果interrupt 为真且底层后端支持该选项,则在证书验证过程中发现错误时会立即发出QSslSocket::handshakeInterruptedOnError() 报告。这样就可以停止未完成的握手,并向对等方发送适当的警报信息。在这种情况下,应用程序无需采取任何特殊措施。QSslSocket 会在发送警报信息后关闭连接。如果应用程序在检查错误后希望继续握手,则必须从其槽函数中调用QSslSocket::continueInterruptedHandshake() 。信号槽连接必须是直接连接。

注: 启用中断握手后,本应由QSslSocket::peerVerifyError() 报告的错误只能由QSslSocket::handshakeInterruptedOnError() 报告。

注: 即使握手继续进行,这些错误也会在发出QSslSocket::sslErrors() 信号时报告(因此必须在相应的函数槽中忽略)。

此函数在 Qt 6.0 中引入。

另请参阅 handshakeMustInterruptOnError()、QSslSocket::handshakeInterruptedOnError() 和QSslSocket::continueInterruptedHandshake()。

void QSslConfiguration::setLocalCertificate(const QSslCertificate &certificate)

将在 SSL 握手过程中提交给对等方的证书设置为certificate

建立连接后,设置证书将不起作用。

证书是 SSL 过程中使用的身份识别手段。远程端使用本地证书对照其认证机构列表验证本地用户的身份。在大多数情况下,例如在 HTTP 网页浏览中,只有服务器会向客户端表明身份,因此客户端不会发送证书。

另请参阅 localCertificate().

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

将在 SSL 握手过程中提交给对等方的证书链设置为localChain

建立连接后,设置证书链不会产生任何影响。

证书是 SSL 过程中使用的身份识别手段。远程端使用本地证书根据其认证机构列表验证本地用户的身份。在大多数情况下,例如在 HTTP 网页浏览中,只有服务器会向客户端表明身份,因此客户端不会发送证书。

QSslConfiguration::setLocalCertificate() 不同,该方法允许您指定验证证书所需的任何中间证书。列表中的第一项必须是叶证书。

另请参阅 localCertificateChain()。

[since 6.0] void QSslConfiguration::setMissingCertificateIsFatal(bool cannotRecover)

如果cannotRecover 为 true,且使用的验证模式为QSslSocket::VerifyPeerQSslSocket::AutoVerifyPeer (客户端套接字),则丢失的对等方证书将被视为不可恢复的错误,不能被忽略。在关闭连接前,将向对方发送一条适当的警报信息。

注: 仅在 Qt 已配置并使用 OpenSSL 后端时可用。

此函数在 Qt 6.0 中引入。

另请参阅 QSslSocket::ignoreSslErrors(),QSslSocket::PeerVerifyMode, 和missingCertificateIsFatal().

void QSslConfiguration::setOcspStaplingEnabled(bool enabled)

如果enabled 为真,客户端QSslSocket 将在启动握手时向其对等程序发送证书状态请求。在握手过程中,QSslSocket 将验证服务器的响应。该值必须在握手开始前设置。

另请参阅 ocspStaplingEnabled().

void QSslConfiguration::setPeerVerifyDepth(int depth)

设置在 SSL 握手阶段要检查的对等方证书链中证书的最大数量(depth )。设置深度为 0 意味着不设置最大深度,表示要检查整个证书链。

证书按签发顺序检查,从对等方自己的证书开始,然后是其签发者的证书,依此类推。

另请参阅 peerVerifyDepth() 和setPeerVerifyMode()。

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

将验证模式设为mode 。该模式决定QSslSocket 是否应向对等方请求证书(即客户端向服务器请求证书,还是服务器向客户端请求证书),以及是否应要求该证书有效。

默认模式为 AutoVerifyPeer,即告诉QSslSocket 对客户端使用 VerifyPeer,对服务器使用 QueryPeer。

另请参见 peerVerifyMode().

void QSslConfiguration::setPreSharedKeyIdentityHint(const QByteArray &hint)

将预共享密钥验证的身份提示设置为hint 。这将影响下一次启动的握手;在已加密的套接字上调用此函数不会影响套接字的身份提示。

身份提示仅用于QSslSocket::SslServerMode

另请参见 preSharedKeyIdentityHint()。

void QSslConfiguration::setPrivateKey(const QSslKey &key)

将连接的私钥key 设置为key 。私钥和本地certificate 用于必须向 SSL 对等方证明其身份的客户端和服务器。

如果创建的是 SSL 服务器套接字,则密钥和本地证书都是必需的。创建 SSL 客户端套接字时,如果客户端必须向 SSL 服务器表明身份,则需要密钥和本地证书。

另请参阅 privateKey() 和setLocalCertificate()。

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

将此配置的协议设置设为protocol

连接已建立后再设置协议将无效。

另请参阅 protocol() 。

void QSslConfiguration::setSessionTicket(const QByteArray &sessionTicket)

设置在 SSL 握手过程中使用的会话票据。QSsl::SslOptionDisableSessionPersistence 必须关闭才能正常工作,sessionTicket 必须是由sessionTicket() 返回的 ASN.1 格式。

另请参阅 sessionTicket()、QSsl::SslOptionDisableSessionPersistencesetSslOption() 和QSslSocket::newSessionTicketReceived()。

void QSslConfiguration::setSslOption(QSsl::SslOption option, bool on)

启用或禁用 SSL 兼容性option 。如果on 为真,则启用option 。如果on 为假,则禁用option

另请参阅 testSslOption() 。

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

返回本系统支持的加密算法列表。该列表由系统的 SSL 库设置,可能因系统而异。

另请参阅 ciphers() 和setCiphers()。

[static] QList<QSslEllipticCurve> QSslConfiguration::supportedEllipticCurves()

返回本系统支持的椭圆曲线列表。该列表由系统的 SSL 库设置,可能因系统而异。

另请参阅 ellipticCurves() 和setEllipticCurves()。

[noexcept] void QSslConfiguration::swap(QSslConfiguration &other)

将此 SSL 配置实例与other 互换。此操作速度非常快,从未出现过故障。

[static] QList<QSslCertificate> QSslConfiguration::systemCaCertificates()

该函数提供操作系统提供的 CA 证书数据库。该函数返回的 CA 证书数据库用于初始化caCertificates() 在默认QSslConfiguration 上返回的数据库。

另请参阅 caCertificates()、setCaCertificates()、defaultConfiguration()、addCaCertificate() 和addCaCertificates() 。

bool QSslConfiguration::testSslOption(QSsl::SslOption option) const

如果指定的 SSL 兼容性option 已启用,则返回true

另请参阅 setSslOption().

bool QSslConfiguration::operator!=(const QSslConfiguration &other) const

如果该QSslConfigurationother 不同,则返回true 。如果两个QSslConfiguration 对象的任何状态或设置不同,则视为不同。

另请参阅 operator==().

QSslConfiguration &QSslConfiguration::operator=(const QSslConfiguration &other)

复制other 的配置和状态。如果other 为空,此对象也将为空。

bool QSslConfiguration::operator==(const QSslConfiguration &other) const

如果QSslConfiguration 对象等于other ,则返回true

如果两个QSslConfiguration 对象的设置和状态完全相同,则视为相等。

另请参阅 operator!=() 。

成员变量文档

const char[] QSslConfiguration::ALPNProtocolHTTP2

该变量用于保存应用层协议协商期间协商 HTTP 2 时使用的值。

const char[] QSslConfiguration::NextProtocolHttp1_1

该变量用于保存下一协议协商期间协商 HTTP 1.1 时使用的值。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.