En esta página

QDtls Class

Esta clase proporciona cifrado para sockets UDP. Más información...

Encabezado: #include <QDtls>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Heredado de: QObject

Tipos públicos

GeneratorParameters
enum HandshakeState { HandshakeNotStarted, HandshakeInProgress, PeerVerificationFailed, HandshakeComplete }

Funciones públicas

QDtls(QSslSocket::SslMode mode, QObject *parent = nullptr)
virtual ~QDtls()
bool abortHandshake(QUdpSocket *socket)
QDtls::GeneratorParameters cookieGeneratorParameters() const
QByteArray decryptDatagram(QUdpSocket *socket, const QByteArray &dgram)
bool doHandshake(QUdpSocket *socket, const QByteArray &dgram = {})
QSslConfiguration dtlsConfiguration() const
QDtlsError dtlsError() const
QString dtlsErrorString() const
bool handleTimeout(QUdpSocket *socket)
QDtls::HandshakeState handshakeState() const
void ignoreVerificationErrors(const QList<QSslError> &errorsToIgnore)
bool isConnectionEncrypted() const
quint16 mtuHint() const
QHostAddress peerAddress() const
quint16 peerPort() const
QList<QSslError> peerVerificationErrors() const
QString peerVerificationName() const
bool resumeHandshake(QUdpSocket *socket)
QSslCipher sessionCipher() const
QSsl::SslProtocol sessionProtocol() const
bool setCookieGeneratorParameters(const QDtls::GeneratorParameters &params)
bool setDtlsConfiguration(const QSslConfiguration &configuration)
void setMtuHint(quint16 mtuHint)
bool setPeer(const QHostAddress &address, quint16 port, const QString &verificationName = {})
bool setPeerVerificationName(const QString &name)
bool shutdown(QUdpSocket *socket)
QSslSocket::SslMode sslMode() const
qint64 writeDatagramEncrypted(QUdpSocket *socket, const QByteArray &dgram)

Señales

void handshakeTimeout()
void pskRequired(QSslPreSharedKeyAuthenticator *authenticator)
enum class QDtlsError { NoError, InvalidInputParameters, InvalidOperation, UnderlyingSocketError, RemoteClosedConnectionError, …, TlsNonFatalError }

Descripción detallada

La clase QDtls se puede utilizar para establecer una conexión segura con un par de red mediante el Protocolo de datagramas de usuario (UDP). Una conexión DTLS sobre UDP, que es esencialmente un protocolo sin conexión, implica que ambos pares deben completar primero con éxito un protocolo de enlace TLS llamando a doHandshake(). Una vez completado el protocolo de enlace, se pueden enviar datagramas cifrados al nodo utilizando writeDatagramEncrypted(). Los datagramas cifrados procedentes del nodo se pueden descifrar mediante decryptDatagram().

QDtls está diseñado para funcionar con QUdpSocket. Dado que QUdpSocket puede recibir datagramas procedentes de diferentes pares, una aplicación debe implementar la demultiplexación, reenviando los datagramas procedentes de diferentes pares a sus correspondientes instancias de QDtls. Se puede establecer una asociación entre un par de red y su objeto QDtls utilizando la dirección y el número de puerto del par. Antes de iniciar un handshake, la aplicación debe configurar la dirección y el número de puerto del par mediante setPeer().

QDtls no lee los datagramas de ` QUdpSocket`; se espera que sea la aplicación la que lo haga, por ejemplo, en una ranura asociada a la señal ` QUdpSocket::readyRead()`. A continuación, QDtls debe procesar dichos datagramas.

Nota: QDtls no asume la propiedad del objeto QUdpSocket.

Normalmente, ambos pares deben recibir y enviar varios datagramas durante la fase de establecimiento de conexión. Al leer los datagramas, el servidor y el cliente deben pasarlos a ` doHandshake()` hasta que se detecte algún error o ` handshakeState()` devuelva ` 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.
    }
}

En el caso de un servidor, la primera llamada a doHandshake() requiere un datagrama no vacío que contenga un mensaje ClientHello. Si el servidor también implementa QDtlsClientVerifier, se espera que el primer mensaje ClientHello sea el verificado por QDtlsClientVerifier.

En caso de que no se pueda validar la identidad del par durante el protocolo de establecimiento de conexión, la aplicación debe examinar los errores devueltos por ` peerVerificationErrors()` y, a continuación, bien ignorar los errores llamando a ` ignoreVerificationErrors()`, bien abortar el protocolo de establecimiento de conexión llamando a ` abortHandshake()`. Si se han ignorado los errores, el protocolo de establecimiento de conexión puede reanudarse llamando a ` resumeHandshake()`.

Una vez completado el establecimiento de la conexión, se pueden enviar y recibir datagramas de forma segura con el par de red:

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

Una conexión DTLS puede cerrarse utilizando shutdown().

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

Advertencia: Se recomienda llamar a ` shutdown()` antes de destruir el objeto `QDtls` del cliente si se tiene previsto reutilizar el mismo número de puerto para conectarse al servidor más adelante. De lo contrario, el servidor podría descartar los mensajes `ClientHello` entrantes; véase la RFC 6347, sección 4.2.8, para obtener más detalles y consejos de implementación.

Si el servidor no utiliza ` QDtlsClientVerifier`, debe configurar sus objetos `QDtls` para desactivar el procedimiento de verificación de cookies:

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

Un servidor que utilice la verificación de cookies con parámetros de generador distintos de los predeterminados debe establecer los mismos parámetros para su objeto QDtls antes de iniciar el protocolo de enlace.

Nota: El protocolo DTLS deja en manos de la aplicación la determinación de la unidad máxima de transmisión de ruta (PMTU). La aplicación puede proporcionar a QDtls el valor de MTU mediante setMtuHint(). Esta indicación solo afecta a la fase de establecimiento de la conexión, ya que solo los mensajes de establecimiento de la conexión pueden ser fragmentados y reensamblados por el DTLS. Todos los demás mensajes enviados por la aplicación deben caber en un único datagrama.

Nota: Las cabecerasespecíficas de DTLS añaden cierta sobrecarga a los datos de la aplicación, lo que reduce aún más el tamaño posible del mensaje.

Advertencia: Un servidor configurado para responder con HelloVerifyRequest descartará todos los mensajes ClientHello fragmentados, sin iniciar nunca un protocolo de enlace.

Los ejemplos del servidor DTLS y del cliente DTLS ilustran cómo utilizar QDtls en aplicaciones.

Véase también QUdpSocket, QDtlsClientVerifier, HandshakeState, QDtlsError y QSslConfiguration.

Documentación sobre los tipos de miembros

[alias] QDtls::GeneratorParameters

enum QDtls::HandshakeState

Describe el estado actual del protocolo de establecimiento de conexión DTLS.

Esta enumeración describe el estado actual del protocolo de establecimiento de conexión DTLS para una conexión QDtls.

ConstanteValorDescripción
QDtls::HandshakeNotStarted0Aún no se ha realizado ninguna acción.
QDtls::HandshakeInProgress1Se ha iniciado el protocolo de enlace y, hasta el momento, no se han detectado errores.
QDtls::PeerVerificationFailed2No se ha podido establecer la identidad del interlocutor.
QDtls::HandshakeComplete3El protocolo de enlace se ha completado con éxito y se ha establecido una conexión cifrada.

Véase también QDtls::doHandshake() y QDtls::handshakeState().

Documentación de funciones miembro

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

Crea un objeto QDtls; se pasa « parent » al constructor « QObject ». « mode » es « QSslSocket::SslServerMode » para una conexión DTLS del lado del servidor o « QSslSocket::SslClientMode » para un cliente.

Véase también sslMode() y QSslSocket::SslMode.

[virtual noexcept] QDtls::~QDtls()

Elimina el objeto « QDtls ».

bool QDtls::abortHandshake(QUdpSocket *socket)

Cancela el proceso de establecimiento de conexión en curso. Devuelve «true» si había uno en curso en socket; en caso contrario, establece un error adecuado y devuelve «false».

Véase también doHandshake() y resumeHandshake().

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

Devuelve el algoritmo hash y el secreto actuales, ya sean los predeterminados o los establecidos previamente mediante una llamada a ` setCookieGeneratorParameters()`.

El algoritmo de hash predeterminado es QCryptographicHash::Sha256 si Qt se ha configurado para admitirlo; en caso contrario, es QCryptographicHash::Sha1. La clave predeterminada se obtiene del generador de números pseudoaleatorios criptográficamente seguro específico del backend.

Véanse también QDtlsClientVerifier y setCookieGeneratorParameters().

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

Descifra un ` dgram ` y devuelve su contenido como texto sin cifrar. El protocolo de establecimiento de conexión debe completarse antes de que se puedan descifrar los datagramas. Dependiendo del tipo de mensaje TLS, la conexión puede escribir en ` socket`, que debe ser un puntero válido.

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

Inicia o continúa un protocolo de enlace DTLS. ` socket ` debe ser un puntero válido. Al iniciar un protocolo de enlace DTLS del lado del servidor, ` dgram ` debe contener el mensaje `ClientHello` inicial leído desde ` QUdpSocket`. Esta función devuelve ` true ` si no se ha detectado ningún error. El estado del protocolo de enlace se puede comprobar mediante ` handshakeState()`. Si se devuelve ` false `, significa que se ha producido algún error; utilice ` dtlsError()` para obtener información más detallada.

Nota: Si no se puede establecer la identidad del par, el error se establece en QDtlsError::PeerVerificationError. Si desea ignorar los errores de verificación y continuar con la conexión, debe llamar a ignoreVerificationErrors() y, a continuación, a resumeHandshake(). Si los errores no se pueden ignorar, debe llamar a abortHandshake().

if (!dtls.doHandshake(&socket, dgram)) {
    if (dtls.dtlsError() == QDtlsError::PeerVerificationError)
        dtls.abortAfterError(&socket);
}

Véase también handshakeState(), dtlsError(), ignoreVerificationErrors(), resumeHandshake() y abortHandshake().

QSslConfiguration QDtls::dtlsConfiguration() const

Devuelve la configuración predeterminada de DTLS o la configuración establecida mediante una llamada anterior a ` setDtlsConfiguration()`.

Véanse también setDtlsConfiguration() y QSslConfiguration::defaultDtlsConfiguration().

QDtlsError QDtls::dtlsError() const

Devuelve el último error detectado por la conexión o por QDtlsError::NoError.

Véase también dtlsErrorString() y QDtlsError.

QString QDtls::dtlsErrorString() const

Devuelve una descripción textual del último error detectado por la conexión o una cadena vacía.

Véase también ` dtlsError()`.

bool QDtls::handleTimeout(QUdpSocket *socket)

Si se produce un tiempo de espera durante el protocolo de establecimiento de conexión, se emite la señal « handshakeTimeout()». La aplicación debe llamar a «handleTimeout()» para volver a transmitir los mensajes del protocolo de establecimiento de conexión; «handleTimeout()» devuelve « true » si se ha producido un tiempo de espera y «false» en caso contrario. « socket » debe ser un puntero válido.

Véase también handshakeTimeout().

QDtls::HandshakeState QDtls::handshakeState() const

Devuelve el estado actual del protocolo de enlace para este QDtls.

Véase también doHandshake() y QDtls::HandshakeState.

[signal] void QDtls::handshakeTimeout()

La pérdida de paquetes puede provocar tiempos de espera durante la fase de establecimiento de conexión. En este caso, QDtls emite una señal handshakeTimeout(). Llama a handleTimeout() para retransmitir los mensajes de establecimiento de conexión:

DtlsClient::DtlsClient()
{
    // Some initialization code here ...
    connect(&clientDtls, &QDtls::handshakeTimeout, this, &DtlsClient::handleTimeout);
}

void DtlsClient::handleTimeout()
{
    clientDtls.handleTimeout(&clientSocket);
}

Véase también handleTimeout().

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

Este método indica a QDtls que ignore únicamente los errores indicados en errorsToIgnore.

Si, por ejemplo, quieres conectarte a un servidor que utiliza un certificado autofirmado, ten en cuenta el siguiente fragmento de código:

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

También puedes llamar a esta función después de que doHandshake() haya detectado el error QDtlsError::PeerVerificationError y, a continuación, reanudar el protocolo de enlace llamando a resumeHandshake().

Las llamadas posteriores a esta función sustituirán la lista de errores que se hayan pasado en llamadas anteriores. Puedes borrar la lista de errores que quieras ignorar llamando a esta función con una lista vacía.

Véase también doHandshake(), resumeHandshake() y QSslError.

bool QDtls::isConnectionEncrypted() const

Devuelve « true » si el protocolo de establecimiento de conexión DTLS se ha completado correctamente.

Véase también doHandshake() y handshakeState().

quint16 QDtls::mtuHint() const

Devuelve el valor establecido previamente mediante la función setMtuHint(). El valor por defecto es 0.

Véase también setMtuHint().

QHostAddress QDtls::peerAddress() const

Devuelve la dirección del par, establecida mediante setPeer(), o QHostAddress::Null.

Véase también setPeer().

quint16 QDtls::peerPort() const

Devuelve el número de puerto del par, establecido mediante la función ` setPeer()` o el valor 0.

Véase también setPeer().

QList<QSslError> QDtls::peerVerificationErrors() const

Devuelve los errores detectados al establecer la identidad del interlocutor.

Si deseas continuar con la conexión a pesar de los errores que se han producido, debes llamar a la función ` ignoreVerificationErrors()`.

QString QDtls::peerVerificationName() const

Devuelve el nombre de host establecido mediante setPeer() o setPeerVerificationName(). El valor por defecto es una cadena vacía.

Véase también setPeerVerificationName() y setPeer().

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

QDtls emite esta señal cuando negocia un conjunto de cifrado PSK, por lo que a continuación se requiere una autenticación PSK.

Al utilizar PSK, el cliente debe enviar al servidor una identidad válida y una clave precompartida válida para que el protocolo de enlace TLS pueda continuar. Las aplicaciones pueden proporcionar esta información en un slot conectado a esta señal, rellenando el objeto ` authenticator ` pasado según sus necesidades.

Nota: Ignorar esta señal o no proporcionar las credenciales necesarias provocará que el protocolo de enlace falle y, por lo tanto, que se interrumpa la conexión.

Nota: El objeto ` authenticator ` es propiedad de ` QDtls ` y la aplicación no debe eliminarlo.

Véase también QSslPreSharedKeyAuthenticator.

bool QDtls::resumeHandshake(QUdpSocket *socket)

Si se ignoraron errores de verificación entre pares durante el protocolo de enlace, la función `resumeHandshake()` reanuda y completa dicho protocolo y devuelve ` true`. ` socket ` debe ser un puntero válido. Devuelve ` false ` si no se ha podido reanudar el protocolo de enlace.

Véanse también doHandshake(), abortHandshake(), peerVerificationErrors() y ignoreVerificationErrors().

QSslCipher QDtls::sessionCipher() const

Devuelve el algoritmo criptográfico cipher utilizado por esta conexión, o un algoritmo nulo si la conexión no está cifrada. El algoritmo de la sesión se selecciona durante la fase de establecimiento de la conexión. El algoritmo se utiliza para cifrar y descifrar datos.

QSslConfiguration Proporciona funciones para establecer la lista ordenada de cifrados entre los que la fase de establecimiento de la conexión seleccionará finalmente el cifrado de la sesión. Esta lista ordenada debe estar definida antes de que comience la fase de establecimiento de la conexión.

Véanse también QSslConfiguration, setDtlsConfiguration() y dtlsConfiguration().

QSsl::SslProtocol QDtls::sessionProtocol() const

Devuelve la versión del protocolo DTLS utilizada por esta conexión, o «UnknownProtocol» si la conexión aún no está cifrada. El protocolo de la conexión se selecciona durante la fase de establecimiento de la conexión.

setDtlsConfiguration() permite establecer la versión preferida antes de que comience el protocolo de enlace.

Véase también setDtlsConfiguration(), QSslConfiguration, QSslConfiguration::defaultDtlsConfiguration() y QSslConfiguration::setProtocol().

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

Establece el algoritmo de hash criptográfico y el secreto a partir de params. Esta función solo es necesaria para una conexión QDtls del lado del servidor. Devuelve true si se realiza correctamente.

Nota: Esta función debe llamarse antes de que comience el protocolo de enlace.

Véase también cookieGeneratorParameters(), doHandshake(), QDtlsClientVerifier y QDtlsClientVerifier::cookieGeneratorParameters().

bool QDtls::setDtlsConfiguration(const QSslConfiguration &configuration)

Establece la configuración TLS de la conexión a partir de configuration y devuelve true si la operación se realiza correctamente.

Nota: Esta función debe llamarse antes de que comience el protocolo de enlace.

Véase también dtlsConfiguration() y doHandshake().

void QDtls::setMtuHint(quint16 mtuHint)

mtuHint es la unidad máxima de transmisión (MTU), ya sea detectada o estimada por la aplicación. La aplicación no está obligada a establecer este valor.

Véase también mtuHint() y QAbstractSocket::PathMtuSocketOption.

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

Establece la dirección del interlocutor, port, y el nombre de host, y devuelve true si la operación se realiza con éxito. address no debe ser nulo, ni multicast ni broadcast. verificationName es el nombre de host utilizado para la validación del certificado.

Véase también peerAddress(), peerPort() y peerVerificationName().

bool QDtls::setPeerVerificationName(const QString &name)

Establece el host name que se utilizará para la validación del certificado y devuelve true si se realiza correctamente.

Nota: Esta función debe llamarse antes de que comience el protocolo de enlace.

Véase también peerVerificationName() y setPeer().

bool QDtls::shutdown(QUdpSocket *socket)

Envía un mensaje de alerta de cierre cifrado y cierra la conexión DTLS. El estado del protocolo de establecimiento de conexión cambia a « QDtls::HandshakeNotStarted ». « socket » debe ser un puntero válido. Esta función devuelve « true » si se ejecuta correctamente.

Véase también doHandshake().

QSslSocket::SslMode QDtls::sslMode() const

Devuelve « QSslSocket::SslServerMode » para una conexión del lado del servidor y « QSslSocket::SslClientMode » para una del lado del cliente.

Véase también QDtls() y QSslSocket::SslMode.

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

Cifra dgram y escribe los datos cifrados en socket. Devuelve el número de bytes escritos, o -1 en caso de error. El protocolo de establecimiento de conexión debe haberse completado antes de escribir los datos cifrados. socket debe ser un puntero válido.

Véase también doHandshake(), handshakeState(), isConnectionEncrypted() y dtlsError().

Elementos no miembros relacionados

enum class QDtlsError

Describe los errores que pueden detectarse mediante QDtls y QDtlsClientVerifier.

Esta enumeración describe los errores generales y específicos de TLS que pueden producirse en los objetos de las clases QDtlsClientVerifier y QDtls.

ConstanteValorDescripción
QDtls::QDtlsError::NoError0No se ha producido ningún error; la última operación se ha realizado correctamente.
QDtls::QDtlsError::InvalidInputParameters1Los parámetros de entrada proporcionados por el llamante no eran válidos.
QDtls::QDtlsError::InvalidOperation2Se ha intentado realizar una operación en un estado que no lo permitía.
QDtls::QDtlsError::UnderlyingSocketError3QUdpSocket::writeDatagram() ha fallado; las funciones QUdpSocket::error() y QUdpSocket::errorString() pueden proporcionar información más específica.
QDtls::QDtlsError::RemoteClosedConnectionError4Se ha recibido un mensaje de alerta de cierre de TLS.
QDtls::QDtlsError::PeerVerificationError5No se ha podido verificar la identidad del par durante el protocolo de enlace TLS.
QDtls::QDtlsError::TlsInitializationError6Se produjo un error al inicializar un backend TLS subyacente.
QDtls::QDtlsError::TlsFatalError7Se ha producido un error grave durante el protocolo de enlace TLS, distinto de un error de verificación del par o de un error de inicialización de TLS.
QDtls::QDtlsError::TlsNonFatalError8Se ha producido un fallo al cifrar o descifrar un datagrama; no es un error grave, lo que significa que QDtls puede seguir funcionando tras este error.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. 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.