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 |
- Lista de todos los miembros, incluidos los heredados
- QDtls forma parte de la API de programación de redes.
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 ¶ms) |
| 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) |
Elementos no miembros relacionados
| 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.
| Constante | Valor | Descripción |
|---|---|---|
QDtls::HandshakeNotStarted | 0 | Aún no se ha realizado ninguna acción. |
QDtls::HandshakeInProgress | 1 | Se ha iniciado el protocolo de enlace y, hasta el momento, no se han detectado errores. |
QDtls::PeerVerificationFailed | 2 | No se ha podido establecer la identidad del interlocutor. |
QDtls::HandshakeComplete | 3 | El 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 ¶ms)
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.
| Constante | Valor | Descripción |
|---|---|---|
QDtls::QDtlsError::NoError | 0 | No se ha producido ningún error; la última operación se ha realizado correctamente. |
QDtls::QDtlsError::InvalidInputParameters | 1 | Los parámetros de entrada proporcionados por el llamante no eran válidos. |
QDtls::QDtlsError::InvalidOperation | 2 | Se ha intentado realizar una operación en un estado que no lo permitía. |
QDtls::QDtlsError::UnderlyingSocketError | 3 | QUdpSocket::writeDatagram() ha fallado; las funciones QUdpSocket::error() y QUdpSocket::errorString() pueden proporcionar información más específica. |
QDtls::QDtlsError::RemoteClosedConnectionError | 4 | Se ha recibido un mensaje de alerta de cierre de TLS. |
QDtls::QDtlsError::PeerVerificationError | 5 | No se ha podido verificar la identidad del par durante el protocolo de enlace TLS. |
QDtls::QDtlsError::TlsInitializationError | 6 | Se produjo un error al inicializar un backend TLS subyacente. |
QDtls::QDtlsError::TlsFatalError | 7 | Se 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::TlsNonFatalError | 8 | Se 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.