Warning
This section contains snippets that were automatically translated from C++ to Python and may contain errors.
DTLS server#
This examples demonstrates how to implement a simple DTLS server.
Note
The DTLS server example is intended to be run alongside the DTLS client example.
The server is implemented by the DtlsServer class. It uses QUdpSocket , QDtlsClientVerifier , and QDtls to test each client’s reachability, complete a handshake, and read and write encrypted messages.
class DtlsServer(QObject): Q_OBJECT # public DtlsServer() ~DtlsServer() listen = bool(QHostAddress address, quint16 port) isListening = bool() def close(): # signals def errorMessage(message): def warningMessage(message): def infoMessage(message): def datagramReceived(peerInfo, cipherText,): plainText) = QByteArray() # private slots def readyRead(): def pskRequired(auth): # private def handleNewConnection(peerAddress, peerPort,): clientHello) = QByteArray() def doHandshake(newConnection, clientHello): def decryptDatagram(connection, clientMessage): def shutdown(): listening = False serverSocket = QUdpSocket() serverConfiguration = QSslConfiguration() cookieSender = QDtlsClientVerifier() std.vector<std.unique_ptr<QDtls>> knownClients Q_DISABLE_COPY(DtlsServer)
The constructor connects the QUdpSocket::readyRead() signal to its readyRead() slot and sets the minimal needed TLS configuration:
def __init__(self): serverSocket.readyRead.connect(self.readyRead) serverConfiguration = QSslConfiguration.defaultDtlsConfiguration() serverConfiguration.setPreSharedKeyIdentityHint("Qt DTLS example server") serverConfiguration.setPeerVerifyMode(QSslSocket.VerifyNone)
Note
The server is not using a certificate and is relying on Pre-Shared Key (PSK) handshake.
listen() binds QUdpSocket :
def listen(self, QHostAddress address, quint16 port): if address != serverSocket.localAddress() or port != serverSocket.localPort(): shutdown() listening = serverSocket.bind(address, port) if not listening: errorMessage.emit(serverSocket.errorString()) else: listening = True return listening
The readyRead() slot processes incoming datagrams:
... bytesToRead = serverSocket.pendingDatagramSize() if bytesToRead <= 0: warningMessage.emit(tr("A spurious read notification")) return dgram = QByteArray(bytesToRead, Qt.Uninitialized) peerAddress = QHostAddress() peerPort = 0 bytesRead = serverSocket.readDatagram(dgram.data(), dgram.size(), peerAddress, peerPort) if bytesRead <= 0: warningMessage.emit(tr("Failed to read a datagram: ") + serverSocket.errorString()) return dgram.resize(bytesRead) ...
After extracting an address and a port number, the server first tests if it’s a datagram from an already known peer:
... if peerAddress.isNull() or not peerPort: warningMessage.emit(tr("Failed to extract peer info (address, port)")) return client = std::find_if(knownClients.begin(), knownClients.end(), [](std.unique_ptr<QDtls> connection){ return connection.peerAddress() == peerAddress and connection.peerPort() == peerPort }) ...
If it is a new, unknown address and port, the datagram is processed as a potential ClientHello message, sent by a DTLS client:
... if client == knownClients.end(): return handleNewConnection(peerAddress, peerPort, dgram) ...
If it’s a known DTLS client, the server either decrypts the datagram:
... if (client).isConnectionEncrypted(): decryptDatagram(client.get(), dgram) if (client).dtlsError() == QDtlsError.RemoteClosedConnectionError: knownClients.erase(client) return ...
or continues a handshake with this peer:
... doHandshake(client.get(), dgram) ...
handleNewConnection() verifies it’s a reachable DTLS client, or sends a HelloVerifyRequest:
def handleNewConnection(self, peerAddress,): quint16 peerPort, QByteArray clientHello) if not listening: return peerInfo = peer_info(peerAddress, peerPort) if cookieSender.verifyClient(serverSocket, clientHello, peerAddress, peerPort): infoMessage.emit(peerInfo + tr(": verified, starting a handshake")) ...
If the new client was verified to be a reachable DTLS client, the server creates and configures a new QDtls object, and starts a server-side handshake:
... std.unique_ptr<QDtls> newConnection{QDtls(){QSslSocket.SslServerMode}} newConnection.setDtlsConfiguration(serverConfiguration) newConnection.setPeer(peerAddress, peerPort) newConnection.connect(newConnection.get(), QDtls.pskRequired, self.pskRequired) knownClients.push_back(std.move(newConnection)) doHandshake(knownClients.back().get(), clientHello) ...
doHandshake() progresses through the handshake phase:
def doHandshake(self, newConnection, clientHello): result = newConnection.doHandshake(serverSocket, clientHello) if not result: errorMessage.emit(newConnection.dtlsErrorString()) return peerInfo = peer_info(newConnection.peerAddress(), newConnection.peerPort()) switch (newConnection.handshakeState()) { elif graphicsApi == QDtls.HandshakeInProgress: infoMessage.emit(peerInfo + tr(": handshake is in progress ...")) break elif graphicsApi == QDtls.HandshakeComplete: infoMessage.emit(tr("Connection with %1 encrypted. %2") .arg(peerInfo, connection_info(newConnection))) break else: Q_UNREACHABLE()
During the handshake phase, the pskRequired() signal is emitted and the pskRequired() slot provides the preshared key:
def pskRequired(self, auth): Q_ASSERT(auth) infoMessage.emit(tr("PSK callback, received a client's identity: '%1'") .arg(QString.fromLatin1(auth.identity()))) auth.setPreSharedKey(QByteArrayLiteral("\x1a\x2b\x3c\x4d\x5e\x6f"))
Note
For the sake of brevity, the definition of pskRequired() is oversimplified. The documentation for the QSslPreSharedKeyAuthenticator class explains in detail how this slot can be properly implemented.
After the handshake is completed for the network peer, an encrypted DTLS connection is considered to be established and the server decrypts subsequent datagrams, sent by the peer, by calling decryptDatagram(). The server also sends an encrypted response to the peer:
def decryptDatagram(self, connection, clientMessage): Q_ASSERT(connection.isConnectionEncrypted()) peerInfo = peer_info(connection.peerAddress(), connection.peerPort()) dgram = connection.decryptDatagram(serverSocket, clientMessage) if dgram.size(): datagramReceived.emit(peerInfo, clientMessage, dgram) connection.writeDatagramEncrypted(serverSocket, tr("to %1: ACK").arg(peerInfo).toLatin1()) elif connection.dtlsError() == QDtlsError.NoError: warningMessage.emit(peerInfo + ": " + tr("0 byte dgram, could be a re-connect attempt?")) else: errorMessage.emit(peerInfo + ": " + connection.dtlsErrorString())
The server closes its DTLS connections by calling shutdown() :
def shutdown(self): for connection in std::exchange(knownClients, {}): connection.shutdown(serverSocket) serverSocket.close()
During its operation, the server reports errors, informational messages, and decrypted datagrams, by emitting signals errorMessage(), warningMessage(), infoMessage(), and datagramReceived(). These messages are logged by the server’s UI:
colorizer = QString(QStringLiteral("<font color=\"%1\">%2")) def addErrorMessage(self, message): ui.serverInfo.insertHtml(colorizer.arg("Crimson", message)) def addWarningMessage(self, message): ui.serverInfo.insertHtml(colorizer.arg("DarkOrange", message)) def addInfoMessage(self, message): ui.serverInfo.insertHtml(colorizer.arg("DarkBlue", message)) def addClientMessage(self, peerInfo, datagram,): QByteArray plainText) messageColor = "DarkMagenta" formatter = QStringLiteral("<br>---------------"() "<br>A message from %1" "<br>DTLS datagram:<br> %2" "<br>As plain text:<br> %3") html = formatter.arg(peerInfo, QString.fromUtf8(datagram.toHex(' ')), QString.fromUtf8(plainText)) ui.messages.insertHtml(colorizer.arg(messageColor, html))