QDtls 类

成员函数文档

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

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

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

[虚拟 noexcept] QDtls::~QDtls()

销毁QDtls对象。

bool QDtls::abortHandshake(QUdpSocket *socket)

中止当前的握手。如果socket上正在进行一个，则返回true；否则，设置合适的错误并返回false。

另请参阅：doHandshake()和resumeHandshake。

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

返回当前的哈希算法和密钥，为默认值或通过setCookieGeneratorParameters()()提前设置的。

默认的哈希算法是QCryptographicHash::Sha256，如果Qt配置支持它，否则是QCryptographicHash::Sha1。默认密钥从后端特定的密码学强伪随机数生成器获得。

另请参阅 setCookieGeneratorParameters()，QDtlsClientVerifier和cookieGeneratorParameters()。

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。

[信号] 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()。

[信号] 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

返回此连接使用的加密加密器，如果不是加密连接，则返回空加密器。在握手阶段选择会话加密器。加密用于加密和解密数据。

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 = {})

设置对等方的地址、端口和主机名，如果成功则返回true。address不得为空、组播或多播。verificationName是进行证书验证所使用的主机名。

另请参阅：peerAddress，peerPort和peerVerificationName。

bool QDtls::setPeerVerificationName(const QString &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()。