QSslKeyingMaterial Class
Describe el material de clave exportado derivado de una sesión TLS. Más información...
| Encabezado: | #include <QSslKeyingMaterial> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Network) target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake: | QT += network |
| Desde: | Qt 6.12 |
| Estado: | Versión preliminar |
Esta clase se encuentra en fase de vista previa tecnológica y está sujeta a cambios.
- Lista de todos los miembros, incluidos los heredados
- QSslKeyingMaterial forma parte de la API de programación de red.
Nota: Todas las funciones de esta clase son reentrantes.
Comparaciones de QSslKeyingMaterial
| Categoría | Tipos comparables |
|---|---|
| igualdad | QSslKeyingMaterial |
Funciones públicas
| QSslKeyingMaterial() | |
| QSslKeyingMaterial(const QByteArray &label, qsizetype size) | |
| QSslKeyingMaterial(const QByteArray &label, qsizetype size, const QByteArray &context) | |
| QSslKeyingMaterial | clone() const |
| QByteArray | context() const |
| bool | isValid() const |
| QByteArray | label() const |
| qsizetype | requestedSize() const |
| void | swap(QSslKeyingMaterial &other) |
| QByteArray | value() const |
Elementos no miembros relacionados
| size_t | qHash(const QSslKeyingMaterial &key) |
| size_t | qHash(const QSslKeyingMaterial &key, size_t seed) |
| QDebug | operator<<(QDebug debug, const QSslKeyingMaterial &keying) |
Descripción detallada
QSslKeyingMaterial representa una solicitud de material de clave derivado de una conexión TLS establecida mediante el mecanismo de exportador de TLS.
El mecanismo de exportación se define en el RFC 5705 para TLS 1.2 y versiones anteriores, y en el RFC 8446 para TLS 1.3. Permite a las aplicaciones derivar material de clave criptográficamente independiente de la sesión TLS sin exponer las claves de tráfico de la sesión.
Cada objeto QSslKeyingMaterial especifica:
- una etiqueta de exportador que identifica la finalidad del material de cifrado derivado
- un valor de contexto opcional que vincula el material de cifrado a datos específicos de la aplicación
- el tamaño deseado del material de cifrado exportado
El material de clave real lo deriva el backend de TLS tras un handshake correcto y puede leerse con ` value()`.
Los objetos `QSslKeyingMaterial` se configuran normalmente mediante ` QSslConfiguration::setKeyingMaterial()` antes de iniciar una conexión TLS.
Ejemplo: Exportación determinista en el cliente y el servidor
// Both client and server configure the same label and optional context
QSslKeyingMaterial keying("session-label", 32, "app-specific-context");
// After the TLS handshake completes get data from QSslConfiguration.
QByteArray derived = sslConfiguration().takeKeyingMaterial(keying)->value();
// Both client and server will obtain the same 'derived' bytes
// even though they each performed the derivation independently.
use(derived);Consideraciones de seguridad
El material de clave exportado es un secreto. ` QByteArray ` es un contenedor de tipo «copia al escribir», por lo que todos los objetos `QSslKeyingMaterial` que contienen un valor comparten un mismo búfer, y el secreto permanece en memoria mientras exista cualquiera de esos objetos. Una aplicación que necesite garantizar que es la única que conserva una referencia debe liberar explícitamente las referencias internas de Qt.
Tras un handshake correcto, el valor reside en un único lugar dentro de Qt: la entrada QSslKeyingMaterial en el QSslConfiguration interno del socket. Cada QSslConfiguration devuelto por QSslSocket::sslConfiguration() es una copia independiente de esa configuración, que comparte el búfer del valor con ella.
Ambas sobrecargas de QSslConfiguration::takeKeyingMaterial() transfieren los valores en lugar de compartirlos: lo que devuelven contiene la única referencia al valor, y las entradas que dejan atrás en la configuración en la que se invocaron son clones sin valor. Copia el valor del objeto devuelto con ` value()` y deja que el propio objeto salga del ámbito, y luego vuelve a escribir la configuración en el socket: esto sobrescribe la entrada del socket con la que carece de valor, eliminando la última referencia que mantiene Qt.
QSslConfiguration config = socket->sslConfiguration();
// Copy the value out of the temporary that owns it, and let it die:
QByteArray secret = config.takeKeyingMaterial(request)->value();
// Overwrite the socket's copy with the entry left behind, which has no value:
socket->setSslConfiguration(config);Las siguientes copias quedan fuera del control del socket y deben tratarse por separado:
- Cualquier otra copia de QSslConfiguration que la aplicación siga conservando, incluida la almacenada en un QNetworkRequest o instalada con QSslConfiguration::setDefaultConfiguration(). Eliminar el valor de una copia no afecta a las demás.
- Una configuración que nunca se ha vuelto a escribir en el socket. Extraer los valores de un QSslConfiguration solo elimina esa copia de la configuración; el socket conserva la suya propia hasta que se le proporcionen las entradas sin valor.
- Cualquier copia de QSslKeyingMaterial que la propia aplicación haya creado. Utiliza clone() cuando se necesite una copia de una solicitud sin su valor.
El socket también descarta los valores cuando inicia un nuevo handshake, ya que en ese momento sus entradas se restablecen a clones sin valor, y cuando se destruye. Ninguna de estas situaciones sustituye al paso explícito anterior para un socket que permanece activo.
Documentación de las funciones miembro
QSslKeyingMaterial::QSslKeyingMaterial()
Crea por defecto una instancia de QSslKeyingMaterial.
Una instancia predeterminada nunca es válida.
Véase también isValid().
[explicit] QSslKeyingMaterial::QSslKeyingMaterial(const QByteArray &label, qsizetype size)
[explicit] QSslKeyingMaterial::QSslKeyingMaterial(const QByteArray &label, qsizetype size, const QByteArray &context)
Crea un objeto ` QSslKeyingMaterial ` con el exportador ` label`, la salida ` size` y el ` context` opcional.
El label identifica la finalidad del material de clave exportado y no debe estar vacío. El size especifica el número de bytes que se derivarán del exportador TLS.
El parámetro opcional « context » es un dato definido por la aplicación que se incorpora al proceso de derivación de claves para proporcionar separación de dominios.
El material de clave en sí no se genera hasta que se haya completado con éxito un protocolo de enlace TLS.
Nota: En TLS 1.2 (RFC 5705), un contexto nulo y un contexto vacío (no nulo) producen un material de clave diferente: el campo de longitud del contexto se omite por completo cuando no hay contexto, lo que da lugar a una entrada PRF diferente. En TLS 1.3 (RFC 8446), se define que un contexto ausente y un contexto vacío son equivalentes y producen el mismo material de clave. Utiliza ` QByteArray::isNull()` para distinguirlos.
Véanse también isValid(), label(), context() y value().
QSslKeyingMaterial QSslKeyingMaterial::clone() const
Devuelve una copia de esta solicitud de material de clave, sin su value().
El objeto devuelto contiene el « label » () del exportador, « context » () y « requestedSize » (), por lo que puede utilizarse para volver a solicitar el mismo material de clave, pero su « value » () está vacío. Úsalo para inicializar una copia o para restablecer una entrada sin conservar el valor.
Véase también value().
QByteArray QSslKeyingMaterial::context() const
Devuelve el valor de contexto opcional que se utiliza para derivar el material de clave.
El valor de contexto vincula el material de cifrado exportado a datos específicos de la aplicación y ayuda a evitar la reutilización accidental de claves idénticas para fines distintos.
Si no se ha especificado ningún contexto, se devuelve un ` QByteArray ` nulo o vacío (véase QSslKeyingMaterial::QSslKeyingMaterial()).
Véanse también label() y value().
[noexcept] bool QSslKeyingMaterial::isValid() const
Devuelve «true» si este objeto ` QSslKeyingMaterial ` describe una solicitud de exportador válida.
Un objeto ` QSslKeyingMaterial ` se considera válido si tiene una etiqueta de exportador no vacía y un tamaño de salida positivo.
Véase también label() y value().
QByteArray QSslKeyingMaterial::label() const
Devuelve la etiqueta del exportador utilizada para derivar el material de clave.
La etiqueta identifica la finalidad del material de clave exportado y se incluye tal cual en la derivación del exportador TLS.
Véase también context() y value().
[noexcept] qsizetype QSslKeyingMaterial::requestedSize() const
El tamaño deseado del material de cifrado.
El tamaño deseado es el número de bytes que se solicita que genere el protocolo de establecimiento de conexión con el fin descrito por los parámetros « label » () y « context » () del material de cifrado solicitado.
Véase también value().
[noexcept] void QSslKeyingMaterial::swap(QSslKeyingMaterial &other)
Cambia este material de clave por other. Esta operación es muy rápida y nunca falla.
QByteArray QSslKeyingMaterial::value() const
Devuelve el material de cifrado exportado.
El objeto ` QByteArray ` devuelto contiene el material de clave derivado de la sesión TLS utilizando la etiqueta y el contexto del exportador configurados.
Si el protocolo de enlace TLS no se ha completado correctamente o si el backend TLS no admite exportadores de claves, esta función devuelve un valor vacío.
Nota: El contenido del material de clave devuelto es sensible desde el punto de vista de la seguridad y debe manejarse con cuidado. Consulte Security Considerations para saber cómo garantizar que el QByteArray devuelto sea la única copia del mismo.
Véase también label(), context() y requestedSize().
Elementos no miembros relacionados
[noexcept] size_t qHash(const QSslKeyingMaterial &key)
[noexcept] size_t qHash(const QSslKeyingMaterial &key, size_t seed)
Devuelve el valor hash de key, utilizando seed como semilla para el cálculo.
QDebug operator<<(QDebug debug, const QSslKeyingMaterial &keying)
Escribe una representación textual del material de clave keying en el objeto de depuración debug.
Véase también «Técnicas de depuración».
© 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.