QDtlsClientVerifier Class

The QDtlsClientVerifier class implements server-side DTLS cookie generation and verification. Datagram security protocols are highly susceptible to a variety of Denial-of-Service attacks. According to RFC 6347, section 4.2.1, these are two of the more common types of attack:

• An attacker transmits a series of handshake initiation requests, causing a server to allocate excessive resources and potentially perform expensive cryptographic operations.

• An attacker transmits a series of handshake initiation requests with a forged source of the victim, making the server act as an amplifier. Normally, the server would reply to the victim machine with a Certificate message, which can be quite large, thus flooding the victim machine with datagrams.

As a countermeasure to these attacks, RFC 6347, section 4.2.1 proposes a stateless cookie technique that a server may deploy:

• In response to the initial ClientHello message, the server sends a HelloVerifyRequest, which contains a cookie. This cookie is a cryptographic hash and is generated using the client's address, port number, and the server's secret (which is a cryptographically strong pseudo-random sequence of bytes).

• A reachable DTLS client is expected to reply with a new ClientHello message containing this cookie.

• When the server receives the ClientHello message with a cookie, it generates a new cookie as described above. This new cookie is compared to the one found in the ClientHello message.

• In the cookies are equal, the client is considered to be real, and the server can continue with a TLS handshake procedure.

QDtlsClientVerifier is designed to work in pair with QUdpSocket, as shown in the following code-excerpt:

class DtlsServer : public QObject
{
public:
    bool listen(const QHostAddress &address, quint16 port);
    // ...

private:
    void readyRead();
    // ...

    QUdpSocket serverSocket;
    QDtlsClientVerifier verifier;
    // ...
};

bool DtlsServer::listen(const QHostAddress &serverAddress, quint16 serverPort)
{
    if (serverSocket.bind(serverAddress, serverPort))
        connect(&serverSocket, &QUdpSocket::readyRead, this, &DtlsServer::readyRead);
    return serverSocket.state() == QAbstractSocket::BoundState;
}

void DtlsServer::readyRead()
{
    QByteArray dgram(serverSocket.pendingDatagramSize(), Qt::Uninitialized);
    QHostAddress address;
    quint16 port = {};
    serverSocket.readDatagram(dgram.data(), dgram.size(), &address, &port);
    if (verifiedClients.contains({address, port}) {
        // This client was verified previously, we either continue the
        // handshake or decrypt the incoming message.
    } else if (verifier.verifyClient(&serverSocket, dgram, address, port)) {
        // Apparently we have a real DTLS client who wants to send us
        // encrypted datagrams. Remember this client as verified
        // and proceed with a handshake.
    } else {
        // No matching cookie was found in the incoming datagram,
        // verifyClient() has sent a ClientVerify message.
        // We'll hear from the client again soon, if they're real.
    }
}

QDtlsClientVerifier does not impose any restrictions on how the application uses QUdpSocket. For example, it is possible to have a server with a single QUdpSocket in state QAbstractSocket::BoundState, handling multiple DTLS clients simultaneously:

• Testing if new clients are real DTLS-capable clients.

• Completing TLS handshakes with the verified clients (see QDtls).

• Decrypting datagrams coming from the connected clients (see QDtls).

• Sending encrypted datagrams to the connected clients (see QDtls).

This implies that QDtlsClientVerifier does not read directly from a socket, instead it expects the application to read an incoming datagram, extract the sender's address, and port, and then pass this data to verifyClient(). To send a HelloVerifyRequest message, verifyClient() can write to the QUdpSocket.

By default QDtlsClientVerifier obtains its secret from a cryptographically strong pseudorandom number generator.

void DtlsServer::updateServerSecret()
{
    const QByteArray newSecret(generateCryptoStrongSecret());
    if (newSecret.size()) {
        usedCookies.append(newSecret);
        verifier.setCookieGeneratorParameters({QCryptographicHash::Sha1, newSecret});
    }
}

The DTLS server example illustrates how to use QDtlsClientVerifier in a server application.

See Also▲

[explicit] QDtlsClientVerifier::QDtlsClientVerifier(QObject *parent = nullptr)▲

[virtual] QDtlsClientVerifier::~QDtlsClientVerifier()▲

QDtlsClientVerifier::GeneratorParameters QDtlsClientVerifier::cookieGeneratorParameters() const▲

QDtlsError QDtlsClientVerifier::dtlsError() const▲

QString QDtlsClientVerifier::dtlsErrorString() const▲

bool QDtlsClientVerifier::setCookieGeneratorParameters(const QDtlsClientVerifier::GeneratorParameters &params)▲

QByteArray QDtlsClientVerifier::verifiedHello() const▲

bool QDtlsClientVerifier::verifyClient(QUdpSocket *socket, const QByteArray &dgram, const QHostAddress &address, quint16 port)▲

if (!verifier.verifyClient(&socket, message, address, port)) {
    switch (verifyClient.dtlsError()) {
    case QDtlsError::NoError:
        // Not verified yet, but no errors found and we have to wait for the next
        // message from this client.
        return;
    case QDtlsError::TlsInitializationError:
        // This error is fatal, nothing we can do about it.
        // Probably, quit the server after reporting the error.
        return;
    case QDtlsError::UnderlyingSocketError:
        // There is some problem in QUdpSocket, handle it (see QUdpSocket::error())
        return;
    case QDtlsError::InvalidInputParameters:
    default:
        Q_UNREACHABLE();
    }
}