Back to Doc.qt.io
Contact Us Blog Download Qt
On this page

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

Note: All functions in this class are reentrant.

Public Functions

QSslKeyingMaterial(const QByteArray &label, int size, const QByteArray &context)
QByteArray context() const
bool isValid() const
QByteArray label() const
qsizetype size() const
QByteArray value() const
QDebug operator<<(QDebug debug, 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

[explicit noexcept implicit] QSslKeyingMaterial::QSslKeyingMaterial(const QByteArray &label, int 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.

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, an empty QByteArray is returned.

See also label() and value().

[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.

See also label() and value().

[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::size() 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] 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 size().

Related Non-Members

QDebug operator<<(QDebug debug, 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.