QDtls Class

 // A client initiates a handshake:
 QUdpSocket clientSocket;
 QDtls clientDtls;
 clientDtls.setPeer(address, port, peerName);
 clientDtls.doHandshake(&clientSocket);

 // A server accepting an incoming connection; address, port, clientHello are
 // read by QUdpSocket::readDatagram():
 QByteArray clientHello(serverSocket.pendingDatagramSize(), Qt::Uninitialized);
 QHostAddress address;
 quin16 port = {};
 serverSocket.readDatagram(clientHello.data(), clientHello.size(), &address, &port);

 QDtls serverDtls;
 serverDtls.setPeer(address, port);
 serverDtls.doHandshake(&serverSocket, clientHello);

 // Handshake completion, both for server and client:
 void DtlsConnection::continueHandshake(const QByteArray &datagram)
 {
     if (dtls.doHandshake(&udpSocket, datagram)) {
         // Check handshake status:
         if (dtls.handshakeStatus() == QDlts::HandshakeComplete) {
             // Secure DTLS connection is now established.
         }
     } else {
         // Error handling.
     }
 }

 // Sending an encrypted datagram:
 dtlsConnection.writeDatagramEncrypted(&clientSocket, "Hello DTLS server!");

 // Decryption:
 QByteArray encryptedMessage(dgramSize);
 socket.readDatagram(encryptedMessage.data(), dgramSize);
 const QByteArray plainText = dtlsConnection.decryptDatagram(&socket, encryptedMessage);

 DtlsClient::~DtlsClient()
 {
     clientDtls.shutdown(&clientSocket);
 }

 auto config = QSslConfiguration::defaultDtlsConfiguration();
 config.setDtlsCookieVerificationEnabled(false);
 // Some other customization ...
 dtlsConnection.setDtlsConfiguration(config);

Member Function Documentation

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

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 sslMode() and QSslSocket::SslMode.

[virtual noexcept] QDtls::~QDtls()

Destroys the QDtls object.

bool QDtls::abortHandshake(QUdpSocket *socket)

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

See also doHandshake() and resumeHandshake().

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

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 setCookieGeneratorParameters(), QDtlsClientVerifier, and cookieGeneratorParameters().

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

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.

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

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 handshakeState(), dtlsError(), ignoreVerificationErrors(), resumeHandshake(), and abortHandshake().

QSslConfiguration QDtls::dtlsConfiguration() const

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

See also setDtlsConfiguration() and QSslConfiguration::defaultDtlsConfiguration().

QDtlsError QDtls::dtlsError() const

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

See also dtlsErrorString() and QDtlsError.

QString QDtls::dtlsErrorString() const

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

See also dtlsError().

bool QDtls::handleTimeout(QUdpSocket *socket)

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 handshakeTimeout().

QDtls::HandshakeState QDtls::handshakeState() const

Returns the current handshake state for this QDtls.

See also doHandshake() and QDtls::HandshakeState.

[signal] void QDtls::handshakeTimeout()

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 handleTimeout().

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

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 doHandshake(), resumeHandshake(), and QSslError.

bool QDtls::isConnectionEncrypted() const

Returns true if DTLS handshake completed successfully.

See also doHandshake() and handshakeState().

quint16 QDtls::mtuHint() const

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

See also setMtuHint().

QHostAddress QDtls::peerAddress() const

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

See also setPeer().

quint16 QDtls::peerPort() const

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

See also setPeer().

QList<QSslError> QDtls::peerVerificationErrors() const

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().

QString QDtls::peerVerificationName() const

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

See also setPeerVerificationName() and setPeer().

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

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 QSslPreSharedKeyAuthenticator.

bool QDtls::resumeHandshake(QUdpSocket *socket)

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 doHandshake(), abortHandshake(), peerVerificationErrors(), and ignoreVerificationErrors().

QSslCipher QDtls::sessionCipher() const

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 QSslConfiguration, setDtlsConfiguration(), and dtlsConfiguration().

QSsl::SslProtocol QDtls::sessionProtocol() const

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 setDtlsConfiguration(), QSslConfiguration, QSslConfiguration::defaultDtlsConfiguration(), and QSslConfiguration::setProtocol().

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

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 cookieGeneratorParameters(), doHandshake(), QDtlsClientVerifier, and QDtlsClientVerifier::cookieGeneratorParameters().

bool QDtls::setDtlsConfiguration(const QSslConfiguration &configuration)

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

See also dtlsConfiguration() and doHandshake().

void QDtls::setMtuHint(quint16 mtuHint)

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 mtuHint() and QAbstractSocket::PathMtuSocketOption.

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

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 peerAddress(), peerPort(), and peerVerificationName().

bool QDtls::setPeerVerificationName(const QString &name)

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

See also peerVerificationName() and setPeer().

bool QDtls::shutdown(QUdpSocket *socket)

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 doHandshake().

QSslSocket::SslMode QDtls::sslMode() const

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

See also QDtls() and QSslSocket::SslMode.

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

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 doHandshake(), handshakeState(), isConnectionEncrypted(), and dtlsError().