<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- secureudpclient.qdoc -->
<title>DTLS client | Qt Network 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtnetwork-index.html">Qt Network</a></td><td ><a href="examples-network.html">Network Examples</a></td><td >DTLS client</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtnetwork-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">DTLS client</h1>
<span class="subtitle"></span>
<!-- $$$secureudpclient-brief -->
<p>This example demonstrates how to implement client-side DTLS connections.</p>
<!-- @@@secureudpclient -->
<!-- $$$secureudpclient-description -->
<div class="descr"> <a name="details"></a>
<p class="centerAlign"><img src="images/secureudpclient-example.png" alt="Screenshot of the DTLS client example." /></p><p><b>Note: </b>The DTLS client example is intended to be run alongside the <a href="qtnetwork-secureudpserver-example.html">DTLS server</a> example.</p><p>The example DTLS client can establish several DTLS connections to one or many DTLS servers. A client-side DTLS connection is implemented by the DtlsAssociation class. This class uses <a href="qudpsocket.html">QUdpSocket</a> to read and write datagrams and <a href="qdtls.html">QDtls</a> for encryption:</p>
<pre class="cpp">
<span class="keyword">class</span> DtlsAssociation : <span class="keyword">public</span> <span class="type"><a href="../qtcore/qobject.html">QObject</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
DtlsAssociation(<span class="keyword">const</span> <span class="type"><a href="qhostaddress.html">QHostAddress</a></span> <span class="operator">&</span>address<span class="operator">,</span> <span class="type"><a href="../qtcore/qtglobal.html#quint16-typedef">quint16</a></span> port<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>connectionName);
<span class="operator">~</span>DtlsAssociation();
<span class="type">void</span> startHandshake();
<span class="keyword">signals</span>:
<span class="type">void</span> errorMessage(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message);
<span class="type">void</span> warningMessage(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message);
<span class="type">void</span> infoMessage(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message);
<span class="type">void</span> serverResponse(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>clientInfo<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> <span class="operator">&</span>datagraam<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> <span class="operator">&</span>plainText);
<span class="keyword">private</span> <span class="keyword">slots</span>:
<span class="type">void</span> udpSocketConnected();
<span class="type">void</span> readyRead();
<span class="type">void</span> handshakeTimeout();
<span class="type">void</span> pskRequired(<span class="type"><a href="qsslpresharedkeyauthenticator.html">QSslPreSharedKeyAuthenticator</a></span> <span class="operator">*</span>auth);
<span class="type">void</span> pingTimeout();
<span class="keyword">private</span>:
<span class="type"><a href="../qtcore/qstring.html">QString</a></span> name;
<span class="type"><a href="qudpsocket.html">QUdpSocket</a></span> socket;
<span class="type"><a href="qdtls.html">QDtls</a></span> crypto;
<span class="type"><a href="../qtcore/qtimer.html">QTimer</a></span> pingTimer;
<span class="type">unsigned</span> ping <span class="operator">=</span> <span class="number">0</span>;
Q_DISABLE_COPY(DtlsAssociation)
};
</pre>
<p>The constructor sets the minimal TLS configuration for the new DTLS connection, and sets the address and the port of the server:</p>
<pre class="cpp">
...
<span class="keyword">auto</span> configuration <span class="operator">=</span> <span class="type"><a href="qsslconfiguration.html">QSslConfiguration</a></span><span class="operator">::</span>defaultDtlsConfiguration();
configuration<span class="operator">.</span>setPeerVerifyMode(<span class="type"><a href="qsslsocket.html">QSslSocket</a></span><span class="operator">::</span>VerifyNone);
crypto<span class="operator">.</span>setPeer(address<span class="operator">,</span> port);
crypto<span class="operator">.</span>setDtlsConfiguration(configuration);
...
</pre>
<p>The <a href="qdtls.html#handshakeTimeout">QDtls::handshakeTimeout</a>() signal is connected to the handleTimeout() slot to deal with packet loss and retransmission during the handshake phase:</p>
<pre class="cpp">
...
connect(<span class="operator">&</span>crypto<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qdtls.html">QDtls</a></span><span class="operator">::</span>handshakeTimeout<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>DtlsAssociation<span class="operator">::</span>handshakeTimeout);
...
</pre>
<p>To ensure we receive only the datagrams from the server, we connect our UDP socket to the server:</p>
<pre class="cpp">
...
socket<span class="operator">.</span>connectToHost(address<span class="operator">.</span>toString()<span class="operator">,</span> port);
...
</pre>
<p>The <a href="../qtcore/qiodevice.html#readyRead">QUdpSocket::readyRead</a>() signal is connected to the readyRead() slot:</p>
<pre class="cpp">
...
connect(<span class="operator">&</span>socket<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qudpsocket.html">QUdpSocket</a></span><span class="operator">::</span>readyRead<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>DtlsAssociation<span class="operator">::</span>readyRead);
...
</pre>
<p>When a secure connection to a server is established, a DtlsAssociation object will be sending short ping messages to the server, using a timer:</p>
<pre class="cpp">
pingTimer<span class="operator">.</span>setInterval(<span class="number">5000</span>);
connect(<span class="operator">&</span>pingTimer<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="../qtcore/qtimer.html">QTimer</a></span><span class="operator">::</span>timeout<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>DtlsAssociation<span class="operator">::</span>pingTimeout);
</pre>
<p>startHandshake() starts a handshake with the server:</p>
<pre class="cpp">
<span class="type">void</span> DtlsAssociation<span class="operator">::</span>startHandshake()
{
<span class="keyword">if</span> (socket<span class="operator">.</span>state() <span class="operator">!</span><span class="operator">=</span> <span class="type"><a href="qabstractsocket.html">QAbstractSocket</a></span><span class="operator">::</span>ConnectedState) {
<span class="keyword">emit</span> infoMessage(tr(<span class="string">"%1: connecting UDP socket first ..."</span>)<span class="operator">.</span>arg(name));
connect(<span class="operator">&</span>socket<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qabstractsocket.html">QAbstractSocket</a></span><span class="operator">::</span>connected<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>DtlsAssociation<span class="operator">::</span>udpSocketConnected);
<span class="keyword">return</span>;
}
<span class="keyword">if</span> (<span class="operator">!</span>crypto<span class="operator">.</span>doHandshake(<span class="operator">&</span>socket))
<span class="keyword">emit</span> errorMessage(tr(<span class="string">"%1: failed to start a handshake - %2"</span>)<span class="operator">.</span>arg(name<span class="operator">,</span> crypto<span class="operator">.</span>dtlsErrorString()));
<span class="keyword">else</span>
<span class="keyword">emit</span> infoMessage(tr(<span class="string">"%1: starting a handshake"</span>)<span class="operator">.</span>arg(name));
}
</pre>
<p>The readyRead() slot reads a datagram sent by the server:</p>
<pre class="cpp">
<span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> dgram(socket<span class="operator">.</span>pendingDatagramSize()<span class="operator">,</span> <span class="type"><a href="../qtcore/qt.html">Qt</a></span><span class="operator">::</span>Uninitialized);
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qtglobal.html#qint64-typedef">qint64</a></span> bytesRead <span class="operator">=</span> socket<span class="operator">.</span>readDatagram(dgram<span class="operator">.</span>data()<span class="operator">,</span> dgram<span class="operator">.</span>size());
<span class="keyword">if</span> (bytesRead <span class="operator"><</span><span class="operator">=</span> <span class="number">0</span>) {
<span class="keyword">emit</span> warningMessage(tr(<span class="string">"%1: spurious read notification?"</span>)<span class="operator">.</span>arg(name));
<span class="keyword">return</span>;
}
dgram<span class="operator">.</span>resize(bytesRead);
</pre>
<p>If the handshake was already completed, this datagram is decrypted:</p>
<pre class="cpp">
<span class="keyword">if</span> (crypto<span class="operator">.</span>isConnectionEncrypted()) {
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> plainText <span class="operator">=</span> crypto<span class="operator">.</span>decryptDatagram(<span class="operator">&</span>socket<span class="operator">,</span> dgram);
<span class="keyword">if</span> (plainText<span class="operator">.</span>size()) {
<span class="keyword">emit</span> serverResponse(name<span class="operator">,</span> dgram<span class="operator">,</span> plainText);
<span class="keyword">return</span>;
}
<span class="keyword">if</span> (crypto<span class="operator">.</span>dtlsError() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qdtls.html#QDtlsError-enum">QDtlsError</a></span><span class="operator">::</span>RemoteClosedConnectionError) {
<span class="keyword">emit</span> errorMessage(tr(<span class="string">"%1: shutdown alert received"</span>)<span class="operator">.</span>arg(name));
socket<span class="operator">.</span>close();
pingTimer<span class="operator">.</span>stop();
<span class="keyword">return</span>;
}
<span class="keyword">emit</span> warningMessage(tr(<span class="string">"%1: zero-length datagram received?"</span>)<span class="operator">.</span>arg(name));
} <span class="keyword">else</span> {
</pre>
<p>otherwise, we try to continue the handshake:</p>
<pre class="cpp">
<span class="keyword">if</span> (<span class="operator">!</span>crypto<span class="operator">.</span>doHandshake(<span class="operator">&</span>socket<span class="operator">,</span> dgram)) {
<span class="keyword">emit</span> errorMessage(tr(<span class="string">"%1: handshake error - %2"</span>)<span class="operator">.</span>arg(name<span class="operator">,</span> crypto<span class="operator">.</span>dtlsErrorString()));
<span class="keyword">return</span>;
}
</pre>
<p>When the handshake has completed, we send our first ping message:</p>
<pre class="cpp">
<span class="keyword">if</span> (crypto<span class="operator">.</span>isConnectionEncrypted()) {
<span class="keyword">emit</span> infoMessage(tr(<span class="string">"%1: encrypted connection established!"</span>)<span class="operator">.</span>arg(name));
pingTimer<span class="operator">.</span>start();
pingTimeout();
} <span class="keyword">else</span> {
</pre>
<p>The pskRequired() slot provides the Pre-Shared Key (PSK) needed during the handshake phase:</p>
<pre class="cpp">
<span class="type">void</span> DtlsAssociation<span class="operator">::</span>pskRequired(<span class="type"><a href="qsslpresharedkeyauthenticator.html">QSslPreSharedKeyAuthenticator</a></span> <span class="operator">*</span>auth)
{
Q_ASSERT(auth);
<span class="keyword">emit</span> infoMessage(tr(<span class="string">"%1: providing pre-shared key ..."</span>)<span class="operator">.</span>arg(name));
auth<span class="operator">-</span><span class="operator">></span>setIdentity(name<span class="operator">.</span>toLatin1());
auth<span class="operator">-</span><span class="operator">></span>setPreSharedKey(<span class="type"><a href="../qtcore/qbytearray.html#QByteArrayLiteral">QByteArrayLiteral</a></span>(<span class="string">"\x1a\x2b\x3c\x4d\x5e\x6f"</span>));
}
</pre>
<p><b>Note: </b>For the sake of brevity, the definition of pskRequired() is oversimplified. The documentation for the <a href="qsslpresharedkeyauthenticator.html">QSslPreSharedKeyAuthenticator</a> class explains in detail how this slot can be properly implemented.</p><p>pingTimeout() sends an encrypted message to the server:</p>
<pre class="cpp">
<span class="type">void</span> DtlsAssociation<span class="operator">::</span>pingTimeout()
{
<span class="keyword">static</span> <span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> message <span class="operator">=</span> <span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"I am %1, please, accept our ping %2"</span>);
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qtglobal.html#qint64-typedef">qint64</a></span> written <span class="operator">=</span> crypto<span class="operator">.</span>writeDatagramEncrypted(<span class="operator">&</span>socket<span class="operator">,</span> message<span class="operator">.</span>arg(name)<span class="operator">.</span>arg(ping)<span class="operator">.</span>toLatin1());
<span class="keyword">if</span> (written <span class="operator"><</span><span class="operator">=</span> <span class="number">0</span>) {
<span class="keyword">emit</span> errorMessage(tr(<span class="string">"%1: failed to send a ping - %2"</span>)<span class="operator">.</span>arg(name<span class="operator">,</span> crypto<span class="operator">.</span>dtlsErrorString()));
pingTimer<span class="operator">.</span>stop();
<span class="keyword">return</span>;
}
<span class="operator">+</span><span class="operator">+</span>ping;
}
</pre>
<p>During the handshake phase the client must handle possible timeouts, which can happen due to packet loss. The handshakeTimeout() slot retransmits the handshake messages:</p>
<pre class="cpp">
<span class="type">void</span> DtlsAssociation<span class="operator">::</span>handshakeTimeout()
{
<span class="keyword">emit</span> warningMessage(tr(<span class="string">"%1: handshake timeout, trying to re-transmit"</span>)<span class="operator">.</span>arg(name));
<span class="keyword">if</span> (<span class="operator">!</span>crypto<span class="operator">.</span>handleTimeout(<span class="operator">&</span>socket))
<span class="keyword">emit</span> errorMessage(tr(<span class="string">"%1: failed to re-transmit - %2"</span>)<span class="operator">.</span>arg(name<span class="operator">,</span> crypto<span class="operator">.</span>dtlsErrorString()));
}
</pre>
<p>Before a client connection is destroyed, its DTLS connection must be shut down:</p>
<pre class="cpp">
DtlsAssociation<span class="operator">::</span><span class="operator">~</span>DtlsAssociation()
{
<span class="keyword">if</span> (crypto<span class="operator">.</span>isConnectionEncrypted())
crypto<span class="operator">.</span>shutdown(<span class="operator">&</span>socket);
}
</pre>
<p>Error messages, informational messages, and decrypted responses from servers are displayed by the UI:</p>
<pre class="cpp">
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> colorizer(<span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"<font color=\"%1\">%2</font><br>"</span>));
<span class="type">void</span> MainWindow<span class="operator">::</span>addErrorMessage(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message)
{
ui<span class="operator">-</span><span class="operator">></span>clientMessages<span class="operator">-</span><span class="operator">></span>insertHtml(colorizer<span class="operator">.</span>arg(<span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"Crimson"</span>)<span class="operator">,</span> message));
}
<span class="type">void</span> MainWindow<span class="operator">::</span>addWarningMessage(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message)
{
ui<span class="operator">-</span><span class="operator">></span>clientMessages<span class="operator">-</span><span class="operator">></span>insertHtml(colorizer<span class="operator">.</span>arg(<span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"DarkOrange"</span>)<span class="operator">,</span> message));
}
<span class="type">void</span> MainWindow<span class="operator">::</span>addInfoMessage(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>message)
{
ui<span class="operator">-</span><span class="operator">></span>clientMessages<span class="operator">-</span><span class="operator">></span>insertHtml(colorizer<span class="operator">.</span>arg(<span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"DarkBlue"</span>)<span class="operator">,</span> message));
}
<span class="type">void</span> MainWindow<span class="operator">::</span>addServerResponse(<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>clientInfo<span class="operator">,</span> <span class="keyword">const</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> <span class="operator">&</span>datagram<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qbytearray.html">QByteArray</a></span> <span class="operator">&</span>plainText)
{
<span class="keyword">static</span> <span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> messageColor <span class="operator">=</span> <span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"DarkMagenta"</span>);
<span class="keyword">static</span> <span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> formatter <span class="operator">=</span> <span class="type"><a href="../qtcore/qstring.html#QStringLiteral">QStringLiteral</a></span>(<span class="string">"<br>---------------"</span>
<span class="string">"<br>%1 received a DTLS datagram:<br> %2"</span>
<span class="string">"<br>As plain text:<br> %3"</span>);
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> html <span class="operator">=</span> formatter<span class="operator">.</span>arg(clientInfo<span class="operator">,</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span><span class="operator">::</span>fromUtf8(datagram<span class="operator">.</span>toHex(<span class="char">' '</span>))<span class="operator">,</span>
<span class="type"><a href="../qtcore/qstring.html">QString</a></span><span class="operator">::</span>fromUtf8(plainText));
ui<span class="operator">-</span><span class="operator">></span>serverMessages<span class="operator">-</span><span class="operator">></span>insertHtml(colorizer<span class="operator">.</span>arg(messageColor<span class="operator">,</span> html));
}
</pre>
<p>Files:</p>
<ul>
<li><a href="qtnetwork-secureudpclient-addressdialog-cpp.html">secureudpclient/addressdialog.cpp</a></li>
<li><a href="qtnetwork-secureudpclient-addressdialog-h.html">secureudpclient/addressdialog.h</a></li>
<li><a href="qtnetwork-secureudpclient-addressdialog-ui.html">secureudpclient/addressdialog.ui</a></li>
<li><a href="qtnetwork-secureudpclient-association-cpp.html">secureudpclient/association.cpp</a></li>
<li><a href="qtnetwork-secureudpclient-association-h.html">secureudpclient/association.h</a></li>
<li><a href="qtnetwork-secureudpclient-main-cpp.html">secureudpclient/main.cpp</a></li>
<li><a href="qtnetwork-secureudpclient-mainwindow-cpp.html">secureudpclient/mainwindow.cpp</a></li>
<li><a href="qtnetwork-secureudpclient-mainwindow-h.html">secureudpclient/mainwindow.h</a></li>
<li><a href="qtnetwork-secureudpclient-mainwindow-ui.html">secureudpclient/mainwindow.ui</a></li>
<li><a href="qtnetwork-secureudpclient-secureudpclient-pro.html">secureudpclient/secureudpclient.pro</a></li>
</ul>
</div>
<!-- @@@secureudpclient -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
d5e62c01ae8d1e579463c6a871dd44bf
>
files
>
2244
