QDtls Class

Detailed Description

The QDtls class can be used to establish a secure connection with a network peer using User Datagram Protocol (UDP). DTLS connection over essentially connectionless UDP means that two peers first have to successfully complete a TLS handshake by calling doHandshake(). After the handshake has completed, encrypted datagrams can be sent to the peer using writeDatagramEncrypted(). Encrypted datagrams coming from the peer can be decrypted by decryptDatagram().

QDtls is designed to work with QUdpSocket. Since QUdpSocket can receive datagrams coming from different peers, an application must implement demultiplexing, forwarding datagrams coming from different peers to their corresponding instances of QDtls. An association between a network peer and its QDtls object can be established using the peer's address and port number. Before starting a handshake, the application must set the peer's address and port number using setPeer().

QDtls does not read datagrams from QUdpSocket, this is expected to be done by the application, for example, in a slot attached to the QUdpSocket::readyRead() signal. Then, these datagrams must be processed by QDtls.

Normally, several datagrams are to be received and sent by both peers during the handshake phase. Upon reading datagrams, server and client must pass these datagrams to doHandshake() until some error is found or handshakeState() returns HandshakeComplete:

 // 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.
     }
 }

For a server, the first call to doHandshake() requires a non-empty datagram containing a ClientHello message. If the server also deploys QDtlsClientVerifier, the first ClientHello message is expected to be the one verified by QDtlsClientVerifier.

In case the peer's identity cannot be validated during the handshake, the application must inspect errors returned by peerVerificationErrors() and then either ignore errors by calling ignoreVerificationErrors() or abort the handshake by calling abortHandshake(). If errors were ignored, the handshake can be resumed by calling resumeHandshake().

After the handshake has been completed, datagrams can be sent to and received from the network peer securely:

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

A DTLS connection may be closed using shutdown().

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

If the server does not use QDtlsClientVerifier, it must configure its QDtls objects to disable the cookie verification procedure:

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

A server that uses cookie verification with non-default generator parameters must set the same parameters for its QDtls object before starting the handshake.

The DTLS server and DTLS client examples illustrate how to use QDtls in applications.