QDtls Class

See also QUdpSocket, QDtlsClientVerifier, HandshakeState, QDtlsError, QSslConfiguration

Describes the current state of DTLS handshake.

This enum describes the current state of DTLS handshake for a QDtls connection.

This enum was introduced or modified in Qt 5.12.

See Also▲

Creates a QDtls object, parent is passed to the QObject constructor. mode is QSslSocket::SslServerMode for a server-side DTLS connection or QSslSocket::SslClientMode for a client.

See Also▲

Destroys the QDtls object.

Aborts the ongoing handshake. Returns true if one was on-going on socket; otherwise, sets a suitable error and returns false.

See Also▲

Returns the current hash algorithm and secret, either default ones or previously set by a call to setCookieGeneratorParameters().

The default hash algorithm is QCryptographicHash::Sha256 if Qt was configured to support it, QCryptographicHash::Sha1 otherwise. The default secret is obtained from the backend-specific cryptographically strong pseudorandom number generator.

See Also▲

Decrypts dgram and returns its contents as plain text. The handshake must be completed before datagrams can be decrypted. Depending on the type of the TLS message the connection may write into socket, which must be a valid pointer.

Starts or continues a DTLS handshake. socket must be a valid pointer. When starting a server-side DTLS handshake, dgram must contain the initial ClientHello message read from QUdpSocket. This function returns true if no error was found. Handshake state can be tested using handshakeState(). false return means some error occurred, use dtlsError() for more detailed information.

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

See Also▲

Returns either the default DTLS configuration or the configuration set by an earlier call to setDtlsConfiguration().

See Also▲

Returns the last error encountered by the connection or QDtlsError::NoError.

See Also▲

Returns a textual description for the last error encountered by the connection or empty string.

See Also▲

If a timeout occurs during the handshake, the handshakeTimeout() signal is emitted. The application must call handleTimeout() to retransmit handshake messages; handleTimeout() returns true if a timeout has occurred, false otherwise. socket must be a valid pointer.

See Also▲

Returns the current handshake state for this QDtls.

See Also▲

Packet loss can result in timeouts during the handshake phase. In this case QDtls emits a handshakeTimeout() signal. Call handleTimeout() to retransmit the handshake messages:

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

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

See Also▲

This method tells QDtls to ignore only the errors given in errorsToIgnore.

If, for instance, you want to connect to a server that uses a self-signed certificate, consider the following snippet:

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);

You can also call this function after doHandshake() encountered the QDtlsError::PeerVerificationError error, and then resume the handshake by calling resumeHandshake().

Later calls to this function will replace the list of errors that were passed in previous calls. You can clear the list of errors you want to ignore by calling this function with an empty list.

See Also▲

Returns true if DTLS handshake completed successfully.

See Also▲

Returns the value previously set by setMtuHint(). The default value is 0.

See Also▲

Returns the peer's address, set by setPeer(), or QHostAddress::Null.

See Also▲

Returns the peer's port number, set by setPeer(), or 0.

See Also▲

Returns errors found while establishing the identity of the peer.

If you want to continue connecting despite the errors that have occurred, you must call ignoreVerificationErrors().

Returns the host name set by setPeer() or setPeerVerificationName(). The default value is an empty string.

See Also▲

QDtls emits this signal when it negotiates a PSK ciphersuite, and therefore a PSK authentication is then required.

When using PSK, the client must send to the server a valid identity and a valid pre shared key, in order for the TLS handshake to continue. Applications can provide this information in a slot connected to this signal, by filling in the passed authenticator object according to their needs.

See Also▲

If peer verification errors were ignored during the handshake, resumeHandshake() resumes and completes the handshake and returns true. socket must be a valid pointer. Returns false if the handshake could not be resumed.

See Also▲

Returns the cryptographic cipher used by this connection, or a null cipher if the connection isn't encrypted. The cipher for the session is selected during the handshake phase. The cipher is used to encrypt and decrypt data.

QSslConfiguration provides functions for setting the ordered list of ciphers from which the handshake phase will eventually select the session cipher. This ordered list must be in place before the handshake phase begins.

See Also▲

Returns the DTLS protocol version used by this connection, or UnknownProtocol if the connection isn't encrypted yet. The protocol for the connection is selected during the handshake phase.

setDtlsConfiguration() can set the preferred version before the handshake starts.

See Also▲

Sets the cryptographic hash algorithm and the secret from params. This function is only needed for a server-side QDtls connection. Returns true if successful.

See Also▲

Sets the connection's TLS configuration from configuration and returns true if successful.

See Also▲

mtuHint is the maximum transmission unit (MTU), either discovered or guessed by the application. The application is not required to set this value.

See Also▲

Sets the peer's address, port, and host name and returns true if successful. address must not be null, multicast, or broadcast. verificationName is the host name used for the certificate validation.

See Also▲

Sets the host name that will be used for the certificate validation and returns true if successful.

See Also▲

Sends an encrypted shutdown alert message and closes the DTLS connection. Handshake state changes to QDtls::HandshakeNotStarted. socket must be a valid pointer. This function returns true on success.

See Also▲

Returns QSslSocket::SslServerMode for a server-side connection and QSslSocket::SslClientMode for a client.

See Also▲

Encrypts dgram and writes the encrypted data into socket. Returns the number of bytes written, or -1 in case of error. The handshake must be completed before writing encrypted data. socket must be a valid pointer.

See Also▲

Describes errors that can be found by QDtls and QDtlsClientVerifier.

This enum describes general and TLS-specific errors that can be encountered by objects of the classes QDtlsClientVerifier and QDtls.

This enum was introduced or modified in Qt 5.12.