QDtls Class

成员函数文档

[explicit] QDtls::QDtls(QSslSocket::SslMode mode, QObject *parent = nullptr)

创建一个 QDtls 对象，将parent 传递给QObject 构造函数。mode 对于服务器端 DTLS 连接为QSslSocket::SslServerMode ，对于客户端则为QSslSocket::SslClientMode 。

另请参阅 sslMode() 和QSslSocket::SslMode 。

[virtual noexcept] QDtls::~QDtls()

销毁QDtls 对象。

bool QDtls::abortHandshake(QUdpSocket *socket)

中止正在进行的握手。如果socket 上正在进行握手，则返回true；否则，设置相应的错误并返回false。

另请参阅 doHandshake() 和resumeHandshake()。

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

返回当前的哈希算法和密钥，可能是默认值，也可能是之前通过调用setCookieGeneratorParameters() 设置的。

如果 Qt 在配置时支持该算法，则默认哈希算法为QCryptographicHash::Sha256 ；否则为QCryptographicHash::Sha1 。默认密钥来自后端特有的、具有密码学强度的伪随机数生成器。

另请参阅 QDtlsClientVerifier 和setCookieGeneratorParameters()。

QByteArray QDtls::decryptDatagram(QUdpSocket *socket, const QByteArray &dgram)

对dgram 进行解密，并将内容作为明文返回。必须先完成握手过程，才能对数据报进行解密。根据TLS消息的类型，连接可能会向socket 写入数据，该指针必须是有效的。

bool QDtls::doHandshake(QUdpSocket *socket, const QByteArray &dgram = {})

启动或继续 DTLS 握手。socket 必须是一个有效的指针。在启动服务器端 DTLS 握手时，dgram 必须包含从QUdpSocket 读取的初始 ClientHello 消息。如果未发现错误，该函数返回true 。可使用handshakeState() 检测握手状态。若返回false ，则表示发生了一些错误，请使用dtlsError() 获取更详细的信息。

if (!dtls.doHandshake(&socket, dgram)) {
    if (dtls.dtlsError() == QDtlsError::PeerVerificationError)
        dtls.abortAfterError(&socket);
}

另请参阅 handshakeState()、dtlsError()、ignoreVerificationErrors()、resumeHandshake() 以及abortHandshake()。

QSslConfiguration QDtls::dtlsConfiguration() const

返回默认的 DTLS 配置，或通过先前对setDtlsConfiguration() 的调用所设置的配置。

另请参阅 setDtlsConfiguration() 和QSslConfiguration::defaultDtlsConfiguration()。

QDtlsError QDtls::dtlsError() const

返回连接遇到的最后一个错误，或QDtlsError::NoError 。

另请参阅 dtlsErrorString() 和QDtlsError 。

QString QDtls::dtlsErrorString() const

返回连接遇到的最后一个错误的文本描述，或返回空字符串。

另请参阅 dtlsError()。

bool QDtls::handleTimeout(QUdpSocket *socket)

如果在握手过程中发生超时，则会发出handshakeTimeout() 信号。应用程序必须调用 handleTimeout() 来重传握手消息；如果发生超时，handleTimeout() 返回true ，否则返回 false。socket 必须是一个有效的指针。

另请参阅 handshakeTimeout()。

QDtls::HandshakeState QDtls::handshakeState() const

返回此QDtls 的当前握手状态。

另请参阅 doHandshake() 和QDtls::HandshakeState 。

[signal] void QDtls::handshakeTimeout()

数据包丢失可能会导致握手阶段出现超时。在这种情况下，QDtls 会发出一个handshakeTimeout()信号。调用handleTimeout()来重传握手消息：

DtlsClient::DtlsClient()
{
    // Some initialization code here ...
    connect(&clientDtls, &QDtls::handshakeTimeout, this, &DtlsClient::handleTimeout);
}

void DtlsClient::handleTimeout()
{
    clientDtls.handleTimeout(&clientSocket);
}

另请参阅 handleTimeout()。

void QDtls::ignoreVerificationErrors(const QList<QSslError> &errorsToIgnore)

此方法指示QDtls 仅忽略errorsToIgnore 中列出的错误。

例如，如果您想连接到使用自签名证书的服务器，请参考以下代码片段：

QList<QSslCertificate> cert = QSslCertificate::fromPath("server-certificate.pem"_L1);
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QDtls dtls;
dtls.ignoreVerificationErrors(expectedSslErrors);
dtls.doHandshake(udpSocket);

您还可以在doHandshake() 遇到QDtlsError::PeerVerificationError 错误后调用此函数，然后通过调用resumeHandshake() 继续握手过程。

后续对该函数的调用将覆盖之前调用中传递的错误列表。您可以通过向该函数传递一个空列表来清除需要忽略的错误列表。

另请参阅 doHandshake()、resumeHandshake() 和QSslError 。

bool QDtls::isConnectionEncrypted() const

如果 DTLS 握手成功完成，则返回true 。

另请参阅 doHandshake() 和handshakeState()。

quint16 QDtls::mtuHint() const

返回先前由setMtuHint() 设置的值。默认值为 0。

另请参阅 setMtuHint()。

QHostAddress QDtls::peerAddress() const

返回由setPeer()或QHostAddress::Null 设置的对等方地址。

另请参阅 setPeer()。

quint16 QDtls::peerPort() const

返回对等方的端口号（由setPeer()设置）或0。

另请参阅 setPeer()。

QList<QSslError> QDtls::peerVerificationErrors() const

返回在确定对等方身份时发现的错误。

如果希望在出现错误的情况下仍继续建立连接，必须调用ignoreVerificationErrors()。

QString QDtls::peerVerificationName() const

返回由setPeer() 或setPeerVerificationName() 设置的主机名。默认值为空字符串。

另请参阅 setPeerVerificationName() 和setPeer()。

[signal] void QDtls::pskRequired(QSslPreSharedKeyAuthenticator *authenticator)

QDtls 在协商 PSK 密码套件时会发出此信号，因此随后需要进行 PSK 身份验证。

使用PSK时，客户端必须向服务器发送有效的身份信息和有效的预共享密钥，以便TLS握手继续进行。应用程序可以通过连接到该信号的插槽提供此信息，根据需要填充传入的authenticator 对象。

另请参阅 QSslPreSharedKeyAuthenticator 。

bool QDtls::resumeHandshake(QUdpSocket *socket)

如果在握手过程中忽略了对等方验证错误，resumeHandshake() 会恢复并完成握手，并返回true 。socket 必须是一个有效的指针。如果无法恢复握手，则返回false 。

另请参阅 doHandshake()、abortHandshake()、peerVerificationErrors() 和ignoreVerificationErrors()。

QSslCipher QDtls::sessionCipher() const

返回此连接所使用的加密算法cipher ，如果连接未加密，则返回空加密算法。会话的加密算法在握手阶段选定。该加密算法用于对数据进行加密和解密。

QSslConfiguration 提供了一组函数，用于设置加密套件的有序列表，握手阶段将最终从该列表中选择会话加密套件。该有序列表必须在握手阶段开始之前就已准备就绪。

另请参见 QSslConfiguration 、setDtlsConfiguration() 和dtlsConfiguration()。

QSsl::SslProtocol QDtls::sessionProtocol() const

返回此连接所使用的 DTLS 协议版本；如果连接尚未加密，则返回 UnknownProtocol。连接所使用的协议是在握手阶段选定的。

setDtlsConfiguration() 可在握手开始前设置首选版本。

另请参阅 setDtlsConfiguration()、QSslConfiguration 、QSslConfiguration::defaultDtlsConfiguration() 以及QSslConfiguration::setProtocol()。

bool QDtls::setCookieGeneratorParameters(const QDtls::GeneratorParameters &params)

设置来自params 的加密哈希算法和密钥。此函数仅适用于服务器端的QDtls 连接。成功时返回true 。

另请参阅 cookieGeneratorParameters()、doHandshake()、QDtlsClientVerifier 以及QDtlsClientVerifier::cookieGeneratorParameters()。

bool QDtls::setDtlsConfiguration(const QSslConfiguration &configuration)

根据configuration 设置连接的TLS配置，成功时返回true 。

另请参阅 dtlsConfiguration() 和doHandshake()。

void QDtls::setMtuHint(quint16 mtuHint)

mtuHint 是最大传输单元（MTU），由应用程序自动检测或推测得出。应用程序无需设置此值。

另请参阅 mtuHint() 和QAbstractSocket::PathMtuSocketOption 。

bool QDtls::setPeer(const QHostAddress &address, quint16 port, const QString &verificationName = {})

设置对等方的地址、port 以及主机名，若操作成功则返回true 。address 不能为空、多播地址或广播地址。verificationName 是用于证书验证的主机名。

另请参阅 peerAddress()、peerPort() 和peerVerificationName()。

bool QDtls::setPeerVerificationName(const QString &name)

设置用于证书验证的主机名name ，若操作成功则返回true 。

另请参阅 peerVerificationName() 和setPeer()。

bool QDtls::shutdown(QUdpSocket *socket)

发送一条加密的关机警报消息，并关闭 DTLS 连接。握手状态变为“QDtls::HandshakeNotStarted ”。socket 必须是一个有效的指针。该函数成功时返回true 。

另请参阅 doHandshake()。

QSslSocket::SslMode QDtls::sslMode() const

对于服务器端连接，返回QSslSocket::SslServerMode ；对于客户端连接，返回QSslSocket::SslClientMode 。

另请参阅 QDtls() 和QSslSocket::SslMode 。

qint64 QDtls::writeDatagramEncrypted(QUdpSocket *socket, const QByteArray &dgram)

对dgram 进行加密，并将加密后的数据写入socket 。返回写入的字节数；若发生错误，则返回 -1。在写入加密数据之前，必须完成握手过程。socket 必须是一个有效的指针。

另请参阅 doHandshake()、handshakeState()、isConnectionEncrypted() 和dtlsError()。