class QSslConfiguration#

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

摘要#

方法#

静态函数#

备注

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译中的问题,也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建工单来通知我们

详细描述#

警告

本节包含从C++自动翻译到Python的代码片段,可能包含错误。

QSslConfiguration 用来由Qt网络类传递关于打开的SSL连接的信息,并允许应用程序控制该连接的一些特定功能。

QSslConfiguration 当前支持的设置包括

  • 要使用的SSL/TLS协议

  • 在连接期间向对方呈现的证书及其关联的私钥

  • 允许用于加密连接的加密套件

  • 用于验证对方证书的证书颁发机构证书列表

这些设置仅在连接握手期间应用。在连接建立后设置它们没有任何效果。

QSslConfiguration 支持的状态包括

  • 对方在握手期间呈现的证书,以及通向CA证书的链

  • 加密此会话所使用的加密套件

状态只能在SSL连接开始后获得,但不一定是完成后。一些设置可能在SSL连接期间发生变化,而无需重新启动(例如,加密套件可能会随时间改变)。

QSslConfiguration 对象中的状态无法更改。

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

注意,在 QSslConfiguration 中更改设置不足以更改相关SSL连接中的设置。您必须调用修改后的 QSslConfiguration 对象上的 `setSslConfiguration` 方法以实现这一点。以下示例展示了如何在 QSslSocket 对象中更改协议为 TLSv1_2

config = sslSocket.sslConfiguration()
config.setProtocol(QSsl.TlsV1_2)
sslSocket.setSslConfiguration(config)
class NextProtocolNegotiationStatus#

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

常量

描述

QSslConfiguration.NextProtocolNegotiationNone

尚未协商应用协议。

QSslConfiguration.NextProtocolNegotiationNegotiated

已协商下一个协议(请参阅 nextNegotiatedProtocol())。

QSslConfiguration.NextProtocolNegotiationUnsupported

客户端和服务器无法就共同的应用协议达成一致。

PySide6.QtNetwork.QSslConfiguration.ALPNProtocolHTTP2#
PySide6.QtNetwork.QSslConfiguration.NextProtocolHttp1_1#
__init__(other)#
参数:

otherQSslConfiguration

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

__init__()

构建一个空的 SSL 配置。该配置不包含有效的设置,状态将为空。调用此构造函数后,isNull() 将返回 true。

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

addCaCertificate(certificate)#
参数:

certificateQSslCertificate

将指定的证书 certificate 添加到此配置的 CA 证书数据库中。必须在 SSL 握手中设置证书数据库。CA 证书数据库由套接字在握手阶段用于验证对方的证书。

备注

默认配置使用系统 CA 证书数据库。如果不可用(如在 iOS 上常见的情况),则默认数据库为空。

addCaCertificates(certificates)#
参数:

certificates – QSslCertificate 列表

将指定的 certificates 添加到此配置的 CA 证书数据库中。必须在 SSL 握手中设置证书数据库。CA 证书数据库由套接字在握手阶段用于验证对方的证书。

备注

默认配置使用系统 CA 证书数据库。如果不可用(如在 iOS 上常见的情况),则默认数据库为空。

addCaCertificates(path[, format=QSsl.Pem[, syntax=QSslCertificate.PatternSyntax.FixedString]])
参数:
返回类型::

布尔值

在指定路径 path 中搜索使用指定格式 format 编码的证书,并将它们添加到套接字的 CA 证书数据库中。路径必须是文件或与文件匹配的模式,具体取决于 syntax 的指定。如果向套接字的 CA 证书数据库添加了一个或多个证书,则返回 true;否则返回 false

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

为了更精确的控制,请使用addCaCertificate()

allowedNextProtocols()#
返回类型::

Qt::QByteArray 列表

此函数返回通过Next Protocol Negotiation(NPN)或Application-Layer Protocol Negotiation(ALPN)TLS扩展与服务器协商的允许协议,如setAllowedNextProtocols()所设置。

backendConfiguration()#
返回类型::

键为QByteArray类型,值为QVariant类型的字典。

返回后端特定配置。

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

caCertificates()#
返回类型::

Qt::QSslCertificate 列表

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

ciphers()#
返回类型::

.QSslCipher列表

返回此连接的当前加密套件。在握手阶段选择会话加密套件时使用此列表。返回的加密套件列表按优先级降序排列。(即,列表中的第一个加密套件是最受推崇的加密套件)。会话加密套件将是列表中支持的第一个加密套件。

默认情况下,握手阶段可以选择系统SSL库支持的任何加密套件,这可能会因系统而异。返回系统SSL库支持的加密套件列表的函数是supportedCiphers()。通过调用setCiphers()并传入支持套件的子集,可以限制用于选择套接字的会话加密套件的列表。通过使用supportedCiphers()返回的列表调用setCiphers(),可以恢复使用整个集合。

static defaultConfiguration()#
返回类型::

QSslConfiguration

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

默认SSL配置包括

  • 无本地证书和无私钥

  • 协议 SecureProtocols

  • 系统默认的CA证书列表

  • 与SSL库支持的128位以上SSL密码列表相等的密码列表

static defaultDtlsConfiguration()#
返回类型::

QSslConfiguration

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

默认的DTLS配置包括

  • 无本地证书和无私钥

  • 协议 DtlsV1_2OrLater

  • 系统默认的CA证书列表

  • 与SSL库支持的TLS 1.2密码列表相等的密码列表,这些密码使用128位以上的密钥

diffieHellmanParameters()#
返回类型::

QSslDiffieHellmanParameters

检索当前设置的Diffie-Hellman参数。

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

备注

默认参数可能在未来的Qt版本中更改。请根据正在使用的Qt版本的文档检查,以了解该版本使用哪些默认值。

dtlsCookieVerificationEnabled()#
返回类型::

布尔值

如果服务器端套接字已启用DTLS Cookie验证,此函数返回true。

ellipticCurves()#
返回类型::

. QSslEllipticCurve 列表

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

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

您可以通过调用具有支持密码子集的setEllipticCurves()来限制用于选择此套接字会话密码的曲线列表。您可以通过调用具有由QSslSocket::supportedEllipticCurves()返回的列表的setEllipticCurves()来恢复使用整个集合。

另请参阅

setEllipticCurves

ephemeralServerKey()#
返回类型::

QSslKey

返回用于具有前向安全的加密算法的临时服务器密钥,例如 DHE-RSA-AES128-SHA。

当以客户端模式运行时,临时密钥才可用,例如 SslClientMode 。当以服务器模式运行或使用无前向安全的加密算法时,将返回空密钥。在发出 encrypted() 信号之前,将设置临时服务器密钥。

handshakeMustInterruptOnError()#
返回类型::

布尔值

如果验证回调在完成握手之前会提前发出 handshakeInterruptedOnError(),则返回 true。

备注

此函数除了 OpenSSL 以外,对所有后端总是返回 false。

isNull()#
返回类型::

布尔值

如果此是空的 QSslConfiguration 对象,返回 true

当使用默认构造函数创建且未调用任何设置方法时,QSslConfiguration 对象将是空的。

在 SSL 握手过程中向对方展示的证书。

另请参阅

setLocalCertificate()

localCertificateChain()#
返回类型::

Qt::QSslCertificate 列表

在 SSL 握手过程中向对方展示的证书链。

missingCertificateIsFatal()#
返回类型::

布尔值

如果无法忽略代码中NoPeerCertificate(无对方证书)错误,则返回true。

备注

除OpenSSL之外的所有TLS后端始终返回false。

nextNegotiatedProtocol()#
返回类型::

QByteArray

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

如果没有协商出任何协议或没有启用扩展,此函数返回一个空的QByteArray。

nextProtocolNegotiationStatus()#
返回类型::

NextProtocolNegotiationStatus

此函数返回下一个协议协商(NPN)或应用层协议协商(ALPN)的状态。如果通过setAllowedNextProtocols() 没有启用此功能,则此函数返回NextProtocolNegotiationNone 。状态将在发出加密()信号之前设置。

ocspStaplingEnabled()#
返回类型::

布尔值

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

__ne__(other)#
参数:

otherQSslConfiguration

返回类型::

布尔值

如果这个 QSslConfiguration 对象与 other 不同,则返回 true。如果两个 QSslConfiguration 对象的任何状态或设置不同,则认为它们是不同的。

另请参阅

operator==()

__eq__(other)#
参数:

otherQSslConfiguration

返回类型::

布尔值

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

如果两个 QSslConfiguration 对象拥有完全相同的设置和状态,则认为它们是相等的。

另请参阅

operator!=()

peerCertificate()#
返回类型::

QSslCertificate

返回对方的数字证书(即您所连接的主机的直接证书),或返回一个空证书,如果对方没有分配证书。

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

由于对方证书是在握手阶段设置的,因此可以从连接到 sslErrors() 信号、sslErrors() 信号或 encrypted() 信号的槽来安全地访问对方证书。

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

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

peerCertificateChain()#
返回类型::

Qt::QSslCertificate 列表

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

在握手阶段自动检查对方证书。此函数通常用于检索用于显示的证书,或用于执行连接诊断。证书包含有关对方和证书颁发机构的信息,包括主机名、颁发者名称和颁发者公钥。

由于对方证书是在握手阶段设置的,因此可以从连接到 sslErrors() 信号、sslErrors() 信号或 encrypted() 信号的槽来安全地访问对方证书。

如果返回一个空列表,可能意味着SSL握手失败,或者你连接的主机没有证书,或者没有连接。

如果你只想获取对方的直接证书,请使用peerCertificate()

peerVerifyDepth()#
返回类型::

整型

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

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

peerVerifyMode()#
返回类型::

PeerVerifyMode

获取验证模式。此模式决定是否请求从对等方(即客户端从服务器请求证书,或服务器请求客户端的证书),并且是否需要验证此证书的有效性。

默认模式为自动验证对等方,该模式要求QSslSocket 对于客户端使用验证对等方,对于服务器使用查询对等方。

另请参阅

setPeerVerifyMode()

preSharedKeyIdentityHint()#
返回类型::

QByteArray

返回标识提示。

privateKey()#
返回类型::

QSslKey

返回分配给此连接的SSL 密钥 或尚未分配则返回空密钥。

protocol()#
返回类型::

Ssl协议

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

另请参阅

setProtocol()

sessionCipher()#
返回类型::

QSslCipher

返回套接字的加密 密文 ,如果没有加密则返回空密文。套接字在握手阶段设置会话的密文。密文用于通过套接字加密和解密数据。

SSL基础架构还提供函数来设置握手阶段最终选择的会话密文的有序密文列表。此有序列表必须在握手阶段开始之前就位。

sessionProtocol()#
返回类型::

Ssl协议

返回套接字的SSL/TLS协议或UnknownProtocol(如果没有加密则返回未知协议)。套接字在握手阶段为会话设置协议。

另请参阅

protocol() setProtocol()

sessionTicket()#
返回类型::

QByteArray

如果关闭了 SslOptionDisableSessionPersistence,此函数将返回SSL握手使用的会话票据,格式为ASN.1,可用于例如持久化到磁盘。如果没有使用会话票据或没有关闭 SslOptionDisableSessionPersistence,则此函数返回空的QByteArray。

备注

在将会话票据持久化到磁盘或类似位置时,请小心,不要将会话暴露给潜在的攻击者,因为了解会话允许对使用会话参数加密的数据进行监听。

sessionTicketLifeTimeHint()#
返回类型::

整型

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

setAllowedNextProtocols(protocols)#
参数:

protocols – QByteArray列表

此函数设置通过与服务器通过Next Protocol Negotiation (NPN)或Application-Layer Protocol Negotiation (ALPN) TLS扩展协商的允许的协议;protocols中的每个元素必须定义一个允许的协议。必须在连接之前显式调用此函数,以便在SSL握手发送NPN/ALPN扩展。可以通过nextProtocolNegotiationStatus() 查询协商是否成功。

setBackendConfiguration([backendConfiguration=QMap<QByteArray, QVariant>()])#
参数:

backendConfiguration – 类型为 .QByteArray 的键和类型为 QVariant 的值的字典。

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

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

setBackendConfigurationOption(name, value)#
参数:

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

OpenSSL (>= 1.0.2) 后端支持的选项可在 支持的配置文件命令 文档中找到。对于所有选项,value 参数的预期类型为 QByteArray。以下示例 展示了如何使用一些选项。

备注

将后端特定配置应用于普通配置之后。使用后端特定配置再次设置普通配置选项将覆盖普通配置选项。

setCaCertificates(certificates)#
参数:

certificates – QSslCertificate 列表

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

备注

默认配置使用系统 CA 证书数据库。如果不可用(如在 iOS 上常见的情况),则默认数据库为空。

setCiphers(ciphers)#
参数:

ciphers – .list of QSslCipher

设置此套接字的加密密码组为 ciphers,该密码组必须包含由 supportedCiphers() 返回的密码列表的一个子集。

必须在与选择会话密码的握手阶段之前限制密码组。

setCiphers(ciphers)
参数:

ciphers - 字符串

将此配置的加密密码组设置为 ciphers,它是一个由冒号分隔的密码组名称列表。密码列表中选择顺序(从最优先的密码开始)。在 ciphers 中的每个密码名称都必须 是由 supportedCiphers() 返回的密码列表中的一个。在与选择会话密码的握手阶段之前必须限制密码组。

备注

使用 Schannel 后端,密码的顺序被忽略,Schannel 在握手过程中选择最安全的一个。

另请参阅

密码函数

静态setDefaultConfiguration(configuration)#
参数:

configurationQSslConfiguration

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

静态setDefaultDtlsConfiguration(configuration)#
参数:

configurationQSslConfiguration

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

setDiffieHellmanParameters(dhparams)#
参数:

dhparams - QSslDiffieHellmanParameters

为此套接字设置为服务器时使用,设置自定义 Diffie-Hellman 参数到 dhparams

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

自 6.7 以来,您可以为空 Diffie-Hellman 参数提供自动选择(请参阅 openssl 的 SSL_CTX_set_dh_auto),如果 TLS 后端支持的话。

备注

默认参数可能在未来的Qt版本中更改。请根据正在使用的Qt版本的文档检查,以了解该版本使用哪些默认值。

setDtlsCookieVerificationEnabled(enable)#
参数:

enable - 布尔值

enable 为 true 时,此函数启用 DTLS 饼干验证。

setEllipticCurves(curves)#
参数:

curves - .QSslEllipticCurve 列表

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

必须在与选择会话密钥的同时握手阶段之前限制椭圆曲线。

另请参阅

ellipticCurves

setHandshakeMustInterruptOnError(interrupt)#
参数:

interrupt - 布尔值

如果 interrupt 为 true 并且底层后端支持此选项,则在证书验证期间发现的错误会立即通过发出 handshakeInterruptedOnError 来报告。这允许停止未完成的握手并发送适当的警报消息到对等方。在这种情况下,不需要应用程序进行特殊操作。 QSslSocket 将在发送警报消息后关闭连接。如果应用程序在检查错误后想继续握手,则必须从其槽函数中调用 continueInterruptedHandshake。信号-槽连接必须是直接的。

备注

当启用中断握手时,peerVerifyError 会报错的错误现在只由 handshakeInterruptedOnError 报告。

备注

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

setLocalCertificate(certificate)#
参数:

certificateQSslCertificate

将要在 SSL 握手过程中呈现给对等方的证书设置为 `certificate`

一旦建立连接,设置证书将不会产生效果。

证书是在 SSL 过程中使用的一种识别手段。本地证书由远程端用于将其与证书授权机构列表验证本地用户身份。在大多数情况下,例如在 HTTP 网页浏览中,仅服务器向客户端进行身份验证,因此客户端不会发送证书。

另请参阅

localCertificate()

setLocalCertificateChain(localChain)#
参数:

localChain – QSslCertificate 列表

设置 SSL 握手过程中呈现给对等方的证书链为 `localChain`

一旦建立连接,设置证书链将不会产生效果。

证书是在 SSL 过程中使用的一种识别手段。本地证书由远程端用于将其与证书授权机构列表验证本地用户身份。在大多数情况下,例如在 HTTP 网页浏览中,仅服务器向客户端进行身份验证,因此客户端不会发送证书。

`setLocalCertificate()` 不同,此方法允许您指定验证您的证书所需的所有中间证书。列表中的第一个项目必须是叶证书。

setMissingCertificateIsFatal(cannotRecover)#
参数:

cannotRecover – bool

如果 `cannotRecover` 为真,并且正在使用的验证模式是 `VerifyPeer``AutoVerifyPeer`(对于客户端套接字),则缺失的对等方证书将被视为无法恢复的错误,无法忽略。在关闭连接之前将向对等方发送适当的警报消息。

备注

仅在 Qt 配置和配置有 OpenSSL 后端构建时可用。

setOcspStaplingEnabled(enable)#
参数:

enable - 布尔值

如果 enabled 为 true,客户端 QSslSocket 在进行握手时会向其对方发送证书状态请求。在握手过程中,QSslSocket 将验证服务器的响应。此值必须在握手开始之前设置。

另请参阅

ocspStaplingEnabled()

setPeerVerifyDepth(depth)#
参数:

深度 – int

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

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

setPeerVerifyMode(mode)#
参数:

模式PeerVerifyMode

将验证模式设置为 mode。此模式决定了 QSslSocket 是否应从对方请求证书(即客户端从服务器请求证书或服务器从客户端请求证书),以及是否需要要求此证书有效。

默认模式为自动验证对等方,该模式要求QSslSocket 对于客户端使用验证对等方,对于服务器使用查询对等方。

另请参阅

peerVerifyMode()

setPreSharedKeyIdentityHint(hint)#
参数:

提示QByteArray

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

仅用于 SslServerMode 的身份提示!

setPrivateKey(key)#
参数:

keyQSslKey

设置连接的私钥 QSslKeykey。私钥和本地 证书 由客户端和服务器使用,以证明其身份给 SSL 对等方。

如果您正在创建 SSL 服务器套接字,则需要键和本地证书。如果您正在创建 SSL 客户端套接字,则需要键和本地证书以使您的客户端能够对 SSL 服务器进行身份验证。

setProtocol(protocol)#
参数:

protocolSslProtocol

将此配置的协议设置为 protocol

在连接已经建立后设置协议不会产生效果。

另请参阅

protocol()

setSessionTicket(sessionTicket)#
参数:

sessionTicketQByteArray

设置用于 SSL 握手的会话票据。必须关闭 SslOptionDisableSessionPersistence 以使其工作,并且 sessionTicket 必须采用 ASN.1 格式,如 sessionTicket() 返回的那样。

setSslOption(option, on)#
参数:

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

另请参阅

testSslOption()

静态supportedCiphers()#
返回类型::

.QSslCipher列表

返回此系统支持的加密密码列表。此列表由系统的 SSL 库设置,可能因系统而异。

另请参阅

ciphers() setCiphers()

静态supportedEllipticCurves()#
返回类型::

. QSslEllipticCurve 列表

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

swap(other)#
参数:

otherQSslConfiguration

与此 SSL 配置实例交换 other。此函数非常快且从不失败。

静态systemCaCertificates()#
返回类型::

Qt::QSslCertificate 列表

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

testSslOption(option)#
参数:

optionSslOption

返回类型::

布尔值

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

另请参阅

setSslOption()