QDtls Class

成员函数文档

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

mode 创建 QDtls 对象，parent 传递给QObject 构造函数。对于服务器端 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 XML 被配置为支持哈希算法，则默认哈希算法为QCryptographicHash::Sha256 ，否则为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 。

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