QSslKeyingMaterial Class
Describes exported keying material derived from a TLS session. More...
| Header: | #include <QSslKeyingMaterial> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Network)target_link_libraries(mytarget PRIVATE Qt6::Network) |
| qmake: | QT += network |
| Since: | Qt 6.12 |
- List of all members, including inherited members
- QSslKeyingMaterial is part of Network Programming API.
Note: All functions in this class are reentrant.
QSslKeyingMaterial Comparisons
| Category | Comparable Types |
|---|---|
| equality | QSslKeyingMaterial |
Public Functions
| QSslKeyingMaterial() | |
| QSslKeyingMaterial(const QByteArray &label, qsizetype size) | |
| QSslKeyingMaterial(const QByteArray &label, qsizetype size, const QByteArray &context) | |
| QByteArray | context() const |
| bool | isValid() const |
| QByteArray | label() const |
| qsizetype | requestedSize() const |
| void | swap(QSslKeyingMaterial &other) |
| QByteArray | value() const |
Related Non-Members
| size_t | qHash(const QSslKeyingMaterial &key) |
| size_t | qHash(const QSslKeyingMaterial &key, size_t seed) |
| QDebug | operator<<(QDebug debug, const QSslKeyingMaterial &keying) |
Detailed Description
QSslKeyingMaterial represents a request for keying material derived from an established TLS connection using the TLS exporter mechanism.
The exporter mechanism is defined in RFC 5705 for TLS 1.2 and earlier and in RFC 8446 for TLS 1.3. It allows applications to derive cryptographically separate keying material from the TLS session without exposing the session's traffic keys.
Each QSslKeyingMaterial object specifies:
- an exporter label identifying the purpose of the derived keying material
- an optional context value binding the keying material to application-specific data
- the desired size of the exported keying material
The actual keying material is derived by the TLS backend after a successful handshake and can be retrieved via value().
QSslKeyingMaterial objects are typically configured via QSslConfiguration::setKeyingMaterial() before initiating a TLS connection.
Example: Deterministic export on client and server
// 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().keyingMaterial(keying)->value();
// Both client and server will obtain the same 'derived' bytes
// even though they each performed the derivation independently.
qDebug() << "Derived keying material:" << derived;Member Function Documentation
[constexpr noexcept default] QSslKeyingMaterial::QSslKeyingMaterial()
Default-constructs an instance of QSslKeyingMaterial.
A default instance is never valid.
See also isValid().
[explicit] QSslKeyingMaterial::QSslKeyingMaterial(const QByteArray &label, qsizetype size)
[explicit] QSslKeyingMaterial::QSslKeyingMaterial(const QByteArray &label, qsizetype size, const QByteArray &context)
Constructs a QSslKeyingMaterial object with the given exporter label, output size, and optional context.
The label identifies the purpose of the exported keying material and must be non-empty. The size specifies the number of bytes to be derived from the TLS exporter.
The optional context is application-defined data that is mixed into the key derivation process to provide domain separation.
The keying material itself is not generated until a TLS handshake has completed successfully.
Note: Under TLS 1.2 (RFC 5705), a null context and an empty (non-null) context produce different keying material: the context length field is omitted entirely when no context is present, yielding a different PRF input. Under TLS 1.3 (RFC 8446), an absent context and an empty context are defined to be equivalent and produce the same keying material. Use QByteArray::isNull() to distinguish them.
See also isValid(), label(), context(), and value().
[noexcept] QByteArray QSslKeyingMaterial::context() const
Returns the optional context value used for deriving the keying material.
The context value binds the exported keying material to application-specific data and helps prevent accidental reuse of identical keys across different purposes.
If no context was specified, a null/empty QByteArray is returned (see QSslKeyingMaterial::QSslKeyingMaterial()).
[noexcept] bool QSslKeyingMaterial::isValid() const
Returns true if this QSslKeyingMaterial object describes a valid exporter request.
A QSslKeyingMaterial object is considered valid if it has a non-empty exporter label and a positive output size.
[noexcept] QByteArray QSslKeyingMaterial::label() const
Returns the exporter label used for deriving the keying material.
The label identifies the purpose of the exported keying material and is included verbatim in the TLS exporter derivation.
See also context() and value().
[noexcept] qsizetype QSslKeyingMaterial::requestedSize() const
The desired size of the keying material.
The desired size is the number of bytes the handshake protocol is asked to generate for the purpose described by the label() and context() of the requested keying material.
See also value().
[noexcept] void QSslKeyingMaterial::swap(QSslKeyingMaterial &other)
Swaps this keying material with other. This operation is very fast and never fails.
[noexcept] QByteArray QSslKeyingMaterial::value() const
Returns the exported keying material.
The returned QByteArray contains the keying material derived from the TLS session using the configured exporter label and context.
If the TLS handshake has not completed successfully or if the TLS backend does not support key exporters, this function returns an empty value.
Note: The contents of the returned keying material are security-sensitive and must be handled with care.
See also label(), context(), and requestedSize().
Related Non-Members
[noexcept] size_t qHash(const QSslKeyingMaterial &key)
[noexcept] size_t qHash(const QSslKeyingMaterial &key, size_t seed)
Returns the hash value for key, using seed to seed the calculation.
QDebug operator<<(QDebug debug, const QSslKeyingMaterial &keying)
Writes a textual representation of the keying material keying to the debug object debug.
See also Debugging Techniques.
© 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.
