PySide6.QtNetwork.QSslConfiguration

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)

另请参阅

SslProtocol QSslCertificate QSslCipher QSslKey QSslSocket QNetworkAccessManager sslConfiguration() setSslConfiguration()

class NextProtocolNegotiationStatus

描述下一个协议协商（NPN）或应用层协议协商（ALPN）的状态。

常量

描述

QSslConfiguration.NextProtocolNegotiationNone

尚未协商任何应用程序协议。

QSslConfiguration.NextProtocolNegotiationNegotiated

已协商下一个协议（参见 nextNegotiatedProtocol() ）。

QSslConfiguration.NextProtocolNegotiationUnsupported

客户端和服务器无法就下一个应用协议达成一致。
PySide6.QtNetwork.QSslConfiguration.ALPNProtocolHTTP2
PySide6.QtNetwork.QSslConfiguration.NextProtocolHttp1_1
__init__()

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

一旦调用了任何setter方法，isNull()将返回false。

__init__(other)
Parameters:

其他 – QSslConfiguration

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

addCaCertificate(certificate)
Parameters:

证书 – QSslCertificate

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

注意

默认配置使用系统的CA证书数据库。如果该数据库不可用（在iOS上通常如此），则默认数据库为空。

另请参阅

caCertificates() setCaCertificates() addCaCertificates()

addCaCertificates(certificates)
Parameters:

certificates – QSslCertificate 的列表

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

注意

默认配置使用系统的CA证书数据库。如果该数据库不可用（在iOS上通常如此），则默认数据库为空。

另请参阅

caCertificates() setCaCertificates() addCaCertificate()

addCaCertificates(path[, format=QSsl.Pem[, syntax=QSslCertificate.PatternSyntax.FixedString]])
Parameters:
Return type:

布尔

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

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

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

allowedNextProtocols()
Return type:

.list of QByteArray

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

backendConfiguration()
Return type:

字典的键类型为 .QByteArray，值类型为 QVariant。

返回后端特定的配置。

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

caCertificates()
Return type:

QSslCertificate的列表

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

ciphers()
Return type:

QSslCipher的列表

返回此连接的当前加密密码套件。此列表在握手阶段用于选择会话密码。返回的密码列表按优先级降序排列。（即，列表中的第一个密码是最优先的密码）。会话密码将是列表中第一个也被对等方支持的密码。

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

static defaultConfiguration()
Return type:

QSslConfiguration

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

默认的SSL配置包括：

  • 没有本地证书和私钥

  • 协议 SecureProtocols

  • 系统的默认CA证书列表

  • 密码列表等于SSL库支持的128位或以上的SSL密码列表

另请参阅

supportedCiphers() setDefaultConfiguration()

static defaultDtlsConfiguration()
Return type:

QSslConfiguration

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

默认的DTLS配置包括：

  • 没有本地证书和私钥

  • 协议 DtlsV1_2OrLater

  • 系统的默认CA证书列表

  • 密码列表等于SSL库支持的TLS 1.2密码列表，这些密码使用128或更多秘密位。

另请参阅

setDefaultDtlsConfiguration()

diffieHellmanParameters()
Return type:

QSslDiffieHellmanParameters

检索当前的Diffie-Hellman参数集。

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

注意

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

另请参阅

setDiffieHellmanParameters()

dtlsCookieVerificationEnabled()
Return type:

布尔

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

ellipticCurves()
Return type:

.list of QSslEllipticCurve

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

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

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

另请参阅

setEllipticCurves

ephemeralServerKey()
Return type:

QSslKey

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

临时密钥仅在客户端模式下运行时可用，即 SslClientMode。在服务器模式下运行或使用没有前向保密性的加密算法时，将返回空密钥。临时服务器密钥将在发出 encrypted() 信号之前设置。

handshakeMustInterruptOnError()
Return type:

布尔

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

注意

此函数对于除OpenSSL之外的所有后端始终返回false。

另请参阅

setHandshakeMustInterruptOnError() handshakeInterruptedOnError() continueInterruptedHandshake()

isNull()
Return type:

布尔

如果这是一个空的 QSslConfiguration 对象，则返回 true。

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

localCertificate()
Return type:

QSslCertificate

返回在SSL握手过程中要呈现给对等方的证书。

另请参阅

setLocalCertificate()

localCertificateChain()
Return type:

QSslCertificate的列表

返回在SSL握手过程中要呈现给对等方的证书链。

missingCertificateIsFatal()
Return type:

布尔

如果无法忽略代码为NoPeerCertificate的错误，则返回true。

注意

对于所有TLS后端，除了OpenSSL，始终返回false。

另请参阅

ignoreSslErrors() setMissingCertificateIsFatal()

nextNegotiatedProtocol()
Return type:

QByteArray

如果启用了Next Protocol Negotiation (NPN) 或 Application-Layer Protocol Negotiation (ALPN) TLS扩展，此函数返回与服务器协商的协议。为了使NPN/ALPN扩展启用，在连接到服务器之前需要显式调用setAllowedNextProtocols()。

如果无法协商协议或未启用扩展，此函数返回一个为空的QByteArray。

nextProtocolNegotiationStatus()
Return type:

NextProtocolNegotiationStatus

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

ocspStaplingEnabled()
Return type:

布尔

如果通过 setOCSPStaplingEnabled() 启用了 OCSP 装订，则返回 true，否则返回 false（这是默认值）。

__ne__(other)
Parameters:

其他 – QSslConfiguration

Return type:

布尔

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

另请参阅

operator==()

__eq__(other)
Parameters:

其他 – QSslConfiguration

Return type:

布尔

如果此 QSslConfiguration 对象等于 other，则返回 true。

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

另请参阅

operator!=()

peerCertificate()
Return type:

QSslCertificate

返回对等方的数字证书（即您所连接主机的直接证书），如果对等方未分配证书，则返回空证书。

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

因为对等证书是在握手阶段设置的，所以从连接到sslErrors()信号、sslErrors()信号或encrypted()信号的插槽访问对等证书是安全的。

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

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

peerCertificateChain()
Return type:

QSslCertificate的列表

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

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

因为对等证书是在握手阶段设置的，所以从连接到sslErrors()信号、sslErrors()信号或encrypted()信号的插槽访问对等证书是安全的。

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

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

peerVerifyDepth()
Return type:

整数

返回在SSL握手阶段要检查的对等方证书链中的最大证书数量，如果未设置最大深度，则返回0（默认值），表示应检查整个证书链。

证书按照颁发顺序进行检查，从对等方自己的证书开始，然后是颁发者的证书，依此类推。

peerVerifyMode()
Return type:

PeerVerifyMode

返回验证模式。此模式决定QSslSocket是否应向对等方请求证书（即客户端向服务器请求证书，或服务器向客户端请求证书），以及是否应要求该证书有效。

默认模式是AutoVerifyPeer，它告诉QSslSocket对客户端使用VerifyPeer，对服务器使用QueryPeer。

另请参阅

setPeerVerifyMode()

preSharedKeyIdentityHint()
Return type:

QByteArray

返回身份提示。

privateKey()
Return type:

QSslKey

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

protocol()
Return type:

SslProtocol

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

另请参阅

setProtocol()

sessionCipher()
Return type:

QSslCipher

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

SSL 基础设施还提供了用于设置加密套件有序列表的函数，握手阶段最终将从该列表中选择会话加密套件。此有序列表必须在握手阶段开始之前设置好。

sessionProtocol()
Return type:

SslProtocol

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

另请参阅

protocol() setProtocol()

sessionTicket()
Return type:

QByteArray

如果SslOptionDisableSessionPersistence被关闭，此函数返回用于SSL握手的会话票据，格式为ASN.1，适合例如持久化到磁盘。如果没有使用会话票据或SslOptionDisableSessionPersistence未被关闭，此函数返回一个空的QByteArray。

注意

将会话票证持久化到磁盘或类似存储时，请注意不要将会话暴露给潜在的攻击者，因为了解会话信息可能会导致使用会话参数加密的数据被窃听。

另请参阅

setSessionTicket() SslOptionDisableSessionPersistence setSslOption() newSessionTicketReceived()

sessionTicketLifeTimeHint()
Return type:

整数

如果SslOptionDisableSessionPersistence被关闭，此函数返回服务器发送的会话票证生命周期提示（可能为0）。如果服务器没有发送会话票证（例如，在恢复会话时或服务器不支持时）或SslOptionDisableSessionPersistence未被关闭，此函数返回-1。

setAllowedNextProtocols(protocols)
Parameters:

protocols – QByteArray 的列表

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

setBackendConfiguration([backendConfiguration=QMap<QByteArray, QVariant>()])
Parameters:

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

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

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

setBackendConfigurationOption(name, value)
Parameters:

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

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

注意

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

另请参阅

backendConfiguration() setBackendConfiguration()

setCaCertificates(certificates)
Parameters:

certificates – QSslCertificate 的列表

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

注意

默认配置使用系统的CA证书数据库。如果该数据库不可用（在iOS上通常如此），则默认数据库为空。

另请参阅

caCertificates() addCaCertificates() addCaCertificate()

setCiphers(ciphers)
Parameters:

ciphers – QSslCipher 的列表

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

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

setCiphers(ciphers)
Parameters:

加密算法 – 字符串

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

注意

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

另请参阅

ciphers()

static setDefaultConfiguration(configuration)
Parameters:

配置 – QSslConfiguration

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

static setDefaultDtlsConfiguration(configuration)
Parameters:

配置 – QSslConfiguration

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

setDiffieHellmanParameters(dhparams)
Parameters:

dhparams – QSslDiffieHellmanParameters

设置一组自定义的Diffie-Hellman参数，当此套接字作为服务器时使用dhparams。

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

自6.7版本起，如果TLS后端支持，您可以提供一个空的Diffie-Hellman参数以使用自动选择（参见openssl的SSL_CTX_set_dh_auto）。

注意

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

另请参阅

diffieHellmanParameters()

setDtlsCookieVerificationEnabled(enable)
Parameters:

enable – 布尔值

当enable为true时，此函数启用DTLS cookie验证。

setEllipticCurves(curves)
Parameters:

曲线 – .QSslEllipticCurve 的列表

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

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

另请参阅

ellipticCurves

setHandshakeMustInterruptOnError(interrupt)
Parameters:

interrupt – 布尔值

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

注意

当启用中断握手时，原本由peerVerifyError()报告的错误将改为仅由handshakeInterruptedOnError()报告。

注意

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

另请参阅

handshakeMustInterruptOnError() handshakeInterruptedOnError() continueInterruptedHandshake()

setLocalCertificate(certificate)
Parameters:

证书 – QSslCertificate

设置要在SSL握手期间向对等方呈现的证书为certificate。

一旦连接建立，设置证书将无效。

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

另请参阅

localCertificate()

setLocalCertificateChain(localChain)
Parameters:

localChain – QSslCertificate 的列表

设置要在SSL握手期间呈现给对等方的证书链为localChain。

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

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

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

setMissingCertificateIsFatal(cannotRecover)
Parameters:

cannotRecover – bool

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

注意

仅在Qt配置并使用OpenSSL后端构建时可用。

另请参阅

ignoreSslErrors() PeerVerifyMode missingCertificateIsFatal()

setOcspStaplingEnabled(enable)
Parameters:

enable – 布尔值

如果 enabled 为 true，客户端 QSslSocket 在启动握手时将向其对等方发送证书状态请求。在握手期间，QSslSocket 将验证服务器的响应。此值必须在握手开始之前设置。

另请参阅

ocspStaplingEnabled()

setPeerVerifyDepth(depth)
Parameters:

深度 – int

设置SSL握手阶段要检查的对等方证书链中的最大证书数量为depth。设置深度为0意味着没有设置最大深度，表示应检查整个证书链。

证书按照颁发顺序进行检查，从对等方自己的证书开始，然后是颁发者的证书，依此类推。

setPeerVerifyMode(mode)
Parameters:

mode – PeerVerifyMode

设置验证模式为mode。此模式决定QSslSocket是否应向对等方请求证书（即客户端向服务器请求证书，或服务器向客户端请求证书），以及是否应要求此证书有效。

默认模式是AutoVerifyPeer，它告诉QSslSocket对客户端使用VerifyPeer，对服务器使用QueryPeer。

另请参阅

peerVerifyMode()

setPreSharedKeyIdentityHint(hint)
Parameters:

提示 – QByteArray

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

身份提示仅在SslServerMode中使用！

setPrivateKey(key)
Parameters:

key – QSslKey

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

如果您正在创建一个SSL服务器套接字，密钥和本地证书都是必需的。如果您正在创建一个SSL客户端套接字，当您的客户端必须向SSL服务器标识自己时，密钥和本地证书也是必需的。

setProtocol(protocol)
Parameters:

协议 – SslProtocol

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

一旦连接已经建立，设置协议将不会产生任何效果。

另请参阅

protocol()

setSessionTicket(sessionTicket)
Parameters:

sessionTicket – QByteArray

设置用于SSL握手的会话票据。SslOptionDisableSessionPersistence必须关闭才能使其生效，并且sessionTicket必须是以ASN.1格式返回的，如sessionTicket()所返回的。

setSslOption(option, on)
Parameters:

启用或禁用SSL兼容性option。如果on为true，则启用option。如果on为false，则禁用option。

另请参阅

testSslOption()

static supportedCiphers()
Return type:

QSslCipher的列表

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

另请参阅

ciphers() setCiphers()

static supportedEllipticCurves()
Return type:

.list of QSslEllipticCurve

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

swap(other)
Parameters:

其他 – QSslConfiguration

将此SSL配置实例与other交换。此函数非常快速且永远不会失败。

static systemCaCertificates()
Return type:

QSslCertificate的列表

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

testSslOption(option)
Parameters:

选项 – SslOption

Return type:

布尔

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

另请参阅

setSslOption()