- class QSslConfiguration#
QSslConfiguration
类保存了 SSL 连接的配置和状态。 更多信息…摘要#
方法#
定义
__init__()
定义
ciphers()
定义
isNull()
定义
__ne__()
def
__eq__()
def
peerVerifyMode()
def
privateKey()
def
protocol()
def
sessionCipher()
def
sessionTicket()
def
setCiphers()
定义
swap()
静态函数#
备注
本文档可能包含从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_2config = 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)#
- 参数:
other –
QSslConfiguration
复制
other
的配置和状态。如果other
为空,则此对象也将为空。- __init__()
构建一个空的 SSL 配置。该配置不包含有效的设置,状态将为空。调用此构造函数后,
isNull()
将返回 true。一旦调用任何设置方法,
isNull()
将返回 false。- addCaCertificate(certificate)#
- 参数:
certificate –
QSslCertificate
将指定的证书
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 –
EncodingFormat
syntax –
PatternSyntax
- 返回类型::
布尔值
在指定路径
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()#
- 返回类型::
返回用于新SSL连接的默认SSL配置。
默认SSL配置包括
无本地证书和无私钥
系统默认的CA证书列表
与SSL库支持的128位以上SSL密码列表相等的密码列表
- static defaultDtlsConfiguration()#
- 返回类型::
返回用于新DTLS连接的默认DTLS配置。
默认的DTLS配置包括
无本地证书和无私钥
协议 DtlsV1_2OrLater
系统默认的CA证书列表
与SSL库支持的TLS 1.2密码列表相等的密码列表,这些密码使用128位以上的密钥
- diffieHellmanParameters()#
- 返回类型::
检索当前设置的Diffie-Hellman参数。
如果没有设置Diffie-Hellman参数,则
QSslConfiguration
对象默认使用RFC 3526的第2048位MODP组。- dtlsCookieVerificationEnabled()#
- 返回类型::
布尔值
如果服务器端套接字已启用DTLS Cookie验证,此函数返回true。
- ellipticCurves()#
- 返回类型::
. QSslEllipticCurve 列表
返回此连接当前椭圆曲线列表。此列表在握手阶段用于选择椭圆曲线(当使用椭圆曲线密码时)。返回的曲线列表按降序优先级排序(即列表中的第一个曲线是最优选的)。
默认情况下,握手阶段可以选择系统SSL库支持的任何曲线,这可能会因系统而异。系统SSL库支持的曲线列表由QSslSocket::supportedEllipticCurves()返回。
您可以通过调用具有支持密码子集的
setEllipticCurves()
来限制用于选择此套接字会话密码的曲线列表。您可以通过调用具有由QSslSocket::supportedEllipticCurves()返回的列表的setEllipticCurves()
来恢复使用整个集合。另请参阅
返回用于具有前向安全的加密算法的临时服务器密钥,例如 DHE-RSA-AES128-SHA。
当以客户端模式运行时,临时密钥才可用,例如
SslClientMode
。当以服务器模式运行或使用无前向安全的加密算法时,将返回空密钥。在发出 encrypted() 信号之前,将设置临时服务器密钥。- handshakeMustInterruptOnError()#
- 返回类型::
布尔值
如果验证回调在完成握手之前会提前发出
handshakeInterruptedOnError()
,则返回 true。备注
此函数除了 OpenSSL 以外,对所有后端总是返回 false。
- isNull()#
- 返回类型::
布尔值
如果此是空的
QSslConfiguration
对象,返回true
。当使用默认构造函数创建且未调用任何设置方法时,
QSslConfiguration
对象将是空的。另请参阅
setProtocol()
setLocalCertificate()
setPrivateKey()
setCiphers()
- localCertificate()#
- 返回类型::
在 SSL 握手过程中向对方展示的证书。
- localCertificateChain()#
- 返回类型::
Qt::QSslCertificate 列表
在 SSL 握手过程中向对方展示的证书链。
- missingCertificateIsFatal()#
- 返回类型::
布尔值
如果无法忽略代码中
NoPeerCertificate
(无对方证书)错误,则返回true。- nextNegotiatedProtocol()#
- 返回类型::
如果启用了下一个协议协商(NPN)或应用层协议协商(ALPN)TLS扩展,则此函数返回与服务器协商的协议。为了启用NPN/ALPN扩展,需要在连接服务器之前显式调用
setAllowedNextProtocols()
。如果没有协商出任何协议或没有启用扩展,此函数返回一个空的QByteArray。
- nextProtocolNegotiationStatus()#
此函数返回下一个协议协商(NPN)或应用层协议协商(ALPN)的状态。如果通过
setAllowedNextProtocols()
没有启用此功能,则此函数返回NextProtocolNegotiationNone
。状态将在发出加密()信号之前设置。- ocspStaplingEnabled()#
- 返回类型::
布尔值
如果通过 setOCSPStaplingEnabled() 启用了 OCSP Stapling,则返回 true,否则返回 false(默认值)。
- __ne__(other)#
- 参数:
other –
QSslConfiguration
- 返回类型::
布尔值
如果这个
QSslConfiguration
对象与other
不同,则返回true
。如果两个QSslConfiguration
对象的任何状态或设置不同,则认为它们是不同的。另请参阅
operator==()
- __eq__(other)#
- 参数:
other –
QSslConfiguration
- 返回类型::
布尔值
如果这个
QSslConfiguration
对象等于other
,则返回true
。如果两个
QSslConfiguration
对象拥有完全相同的设置和状态,则认为它们是相等的。另请参阅
operator!=()
- peerCertificate()#
- 返回类型::
返回对方的数字证书(即您所连接的主机的直接证书),或返回一个空证书,如果对方没有分配证书。
在握手阶段会自动检查对方证书,因此这个函数通常用于获取显示或用于连接诊断的证书。它包含有关对方的信息,包括其主机名、证书颁发者和对方的公钥。
由于对方证书是在握手阶段设置的,因此可以从连接到
sslErrors()
信号、sslErrors()
信号或encrypted()
信号的槽来安全地访问对方证书。如果返回空证书,这可能意味着 SSL 握手失败,或者您所连接的主机没有证书,或者没有连接。
如果要检查对方完整的证书链,请使用
peerCertificateChain()
一次性获取所有证书。- peerCertificateChain()#
- 返回类型::
Qt::QSslCertificate 列表
返回对方的数字证书链,从对方的直接证书开始,以CA证书结束。
在握手阶段自动检查对方证书。此函数通常用于检索用于显示的证书,或用于执行连接诊断。证书包含有关对方和证书颁发机构的信息,包括主机名、颁发者名称和颁发者公钥。
由于对方证书是在握手阶段设置的,因此可以从连接到
sslErrors()
信号、sslErrors()
信号或encrypted()
信号的槽来安全地访问对方证书。如果返回一个空列表,可能意味着SSL握手失败,或者你连接的主机没有证书,或者没有连接。
如果你只想获取对方的直接证书,请使用
peerCertificate()
。- peerVerifyDepth()#
- 返回类型::
整型
返回在SSL握手阶段要检查的对方证书链中最大证书数量,如果没有设置最大深度(默认值为0),则表示应检查整个证书链。
按照颁发顺序检查证书,从对方的证书开始,然后是其颁发者的证书,依此类推。
- peerVerifyMode()#
- 返回类型::
获取验证模式。此模式决定是否请求从对等方(即客户端从服务器请求证书,或服务器请求客户端的证书),并且是否需要验证此证书的有效性。
默认模式为自动验证对等方,该模式要求
QSslSocket
对于客户端使用验证对等方,对于服务器使用查询对等方。另请参阅
- 返回类型::
返回标识提示。
返回分配给此连接的
SSL 密钥
或尚未分配则返回空密钥。返回此SSL配置的协议设置。
另请参阅
- sessionCipher()#
- 返回类型::
返回套接字的加密
密文
,如果没有加密则返回空密文。套接字在握手阶段设置会话的密文。密文用于通过套接字加密和解密数据。SSL基础架构还提供函数来设置握手阶段最终选择的会话密文的有序密文列表。此有序列表必须在握手阶段开始之前就位。
返回套接字的SSL/TLS协议或UnknownProtocol(如果没有加密则返回未知协议)。套接字在握手阶段为会话设置协议。
另请参阅
- sessionTicket()#
- 返回类型::
如果关闭了
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 –
QByteArray
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()
返回的密码列表中的一个。在与选择会话密码的握手阶段之前必须限制密码组。- 静态setDefaultConfiguration(configuration)#
- 参数:
configuration –
QSslConfiguration
将默认 SSL 配置设置为用于新 SSL 连接的
configuration
。现有的连接不受到影响。- 静态setDefaultDtlsConfiguration(configuration)#
- 参数:
configuration –
QSslConfiguration
将用于新 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 后端支持的话。
- setDtlsCookieVerificationEnabled(enable)#
- 参数:
enable - 布尔值
当
enable
为 true 时,此函数启用 DTLS 饼干验证。- setEllipticCurves(curves)#
- 参数:
curves - .QSslEllipticCurve 列表
设置此套接字应使用的椭圆曲线列表为
curves
,该列表必须包含supportedEllipticCurves
返回的列表的子集。必须在与选择会话密钥的同时握手阶段之前限制椭圆曲线。
另请参阅
- setHandshakeMustInterruptOnError(interrupt)#
- 参数:
interrupt - 布尔值
如果
interrupt
为 true 并且底层后端支持此选项,则在证书验证期间发现的错误会立即通过发出handshakeInterruptedOnError
来报告。这允许停止未完成的握手并发送适当的警报消息到对等方。在这种情况下,不需要应用程序进行特殊操作。QSslSocket
将在发送警报消息后关闭连接。如果应用程序在检查错误后想继续握手,则必须从其槽函数中调用continueInterruptedHandshake
。信号-槽连接必须是直接的。备注
当启用中断握手时,
peerVerifyError
会报错的错误现在只由handshakeInterruptedOnError
报告。备注
即使握手继续,这些错误也会在发出 `sslErrors()` 信号时报告(因此必须在相应的函数槽中忽略)。
- setLocalCertificate(certificate)#
- 参数:
certificate –
QSslCertificate
将要在 SSL 握手过程中呈现给对等方的证书设置为
`certificate`
。一旦建立连接,设置证书将不会产生效果。
证书是在 SSL 过程中使用的一种识别手段。本地证书由远程端用于将其与证书授权机构列表验证本地用户身份。在大多数情况下,例如在 HTTP 网页浏览中,仅服务器向客户端进行身份验证,因此客户端不会发送证书。
另请参阅
- setLocalCertificateChain(localChain)#
- 参数:
localChain – QSslCertificate 列表
设置 SSL 握手过程中呈现给对等方的证书链为
`localChain`
。一旦建立连接,设置证书链将不会产生效果。
证书是在 SSL 过程中使用的一种识别手段。本地证书由远程端用于将其与证书授权机构列表验证本地用户身份。在大多数情况下,例如在 HTTP 网页浏览中,仅服务器向客户端进行身份验证,因此客户端不会发送证书。
与
`setLocalCertificate()`
不同,此方法允许您指定验证您的证书所需的所有中间证书。列表中的第一个项目必须是叶证书。- setMissingCertificateIsFatal(cannotRecover)#
- 参数:
cannotRecover – bool
如果
`cannotRecover`
为真,并且正在使用的验证模式是`VerifyPeer`
或`AutoVerifyPeer`
(对于客户端套接字),则缺失的对等方证书将被视为无法恢复的错误,无法忽略。在关闭连接之前将向对等方发送适当的警报消息。- setOcspStaplingEnabled(enable)#
- 参数:
enable - 布尔值
如果
enabled
为 true,客户端QSslSocket
在进行握手时会向其对方发送证书状态请求。在握手过程中,QSslSocket
将验证服务器的响应。此值必须在握手开始之前设置。- setPeerVerifyDepth(depth)#
- 参数:
深度 – int
设置 SSL 握手阶段要检查对方证书链中证书的最大数量为
depth
。设置深度为 0 表示不设置最大深度,表示应检查整个证书链。按照颁发顺序检查证书,从对方的证书开始,然后是其颁发者的证书,依此类推。
- setPeerVerifyMode(mode)#
- 参数:
模式 –
PeerVerifyMode
将验证模式设置为
mode
。此模式决定了QSslSocket
是否应从对方请求证书(即客户端从服务器请求证书或服务器从客户端请求证书),以及是否需要要求此证书有效。默认模式为自动验证对等方,该模式要求
QSslSocket
对于客户端使用验证对等方,对于服务器使用查询对等方。另请参阅
- 参数:
提示 –
QByteArray
设置预共享密钥身份提示为
hint
。这将影响下一次初始化的握手;在一个已加密的套接字上调用此函数不会影响套接字的身份提示。仅用于
SslServerMode
的身份提示!设置连接的私钥
QSslKey
为key
。私钥和本地证书
由客户端和服务器使用,以证明其身份给 SSL 对等方。如果您正在创建 SSL 服务器套接字,则需要键和本地证书。如果您正在创建 SSL 客户端套接字,则需要键和本地证书以使您的客户端能够对 SSL 服务器进行身份验证。
- setProtocol(protocol)#
- 参数:
protocol –
SslProtocol
将此配置的协议设置为
protocol
。在连接已经建立后设置协议不会产生效果。
另请参阅
- setSessionTicket(sessionTicket)#
- 参数:
sessionTicket –
QByteArray
设置用于 SSL 握手的会话票据。必须关闭
SslOptionDisableSessionPersistence
以使其工作,并且sessionTicket
必须采用 ASN.1 格式,如sessionTicket()
返回的那样。启用或禁用 SSL 兼容性
选项
。如果on
为真,则选项
被启用。如果on
为假,则选项
被禁用。另请参阅
- 静态supportedCiphers()#
- 返回类型::
.QSslCipher列表
返回此系统支持的加密密码列表。此列表由系统的 SSL 库设置,可能因系统而异。
另请参阅
- 静态supportedEllipticCurves()#
- 返回类型::
. QSslEllipticCurve 列表
返回此系统支持的椭圆曲线列表。此列表由系统的 SSL 库设置,可能因系统而异。
- swap(other)#
- 参数:
other –
QSslConfiguration
与此 SSL 配置实例交换
other
。此函数非常快且从不失败。- 静态systemCaCertificates()#
- 返回类型::
Qt::QSslCertificate 列表
此函数提供由操作系统提供的 CA 证书数据库。此函数返回的 CA 证书数据库用于初始化默认
QSslConfiguration
上的caCertificates()
返回的数据库。如果指定的SSL兼容性
option
已启用,则返回true
。另请参阅