Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QSslKeyingMaterial Class Reference

Describes exported keying material derived from a TLS session. More...

#include <qsslkeyingmaterial.h>

Collaboration diagram for QSslKeyingMaterial:

Public Member Functions

 QSslKeyingMaterial ()=default
 Default-constructs an instance of QSslKeyingMaterial.
 QSslKeyingMaterial (const QByteArray &label, qsizetype size)
 QSslKeyingMaterial (const QByteArray &label, qsizetype size, const QByteArray &context)
 Constructs a QSslKeyingMaterial object with the given exporter label, output size, and optional context.
bool isValid () const noexcept
 Returns true if this QSslKeyingMaterial object describes a valid exporter request.
QByteArray label () const noexcept
 Returns the exporter label used for deriving the keying material.
QByteArray context () const noexcept
 Returns the optional context value used for deriving the keying material.
QByteArray value () const noexcept
 Returns the exported keying material.
qsizetype requestedSize () const noexcept
 The desired size of the keying material.
void swap (QSslKeyingMaterial &other) noexcept
 \memberswap{keying material}

Friends

class QTlsPrivate::TlsCryptographOpenSSL
bool comparesEqual (const QSslKeyingMaterial &lhs, const QSslKeyingMaterial &rhs) noexcept
size_t qHash (const QSslKeyingMaterial &material) noexcept
Q_NETWORK_EXPORT size_t qHash (const QSslKeyingMaterial &material, size_t seed)
Q_NETWORK_EXPORT QDebug operator<< (QDebug debug, const QSslKeyingMaterial &keying)
 Writes a textual representation of the keying material keying to the debug object debug.

Detailed Description

Describes exported keying material derived from a TLS session.

Since
6.12

\reentrant

\inmodule QtNetwork \compares equality

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: \list

  • 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 \endlist

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;
QByteArray
\inmodule QtCore
Definition qbytearray.h:58
QSslKeyingMaterial::QSslKeyingMaterial
QSslKeyingMaterial()=default
Default-constructs an instance of QSslKeyingMaterial.
qDebug
#define qDebug
Definition qlogging.h:169

Definition at line 25 of file qsslkeyingmaterial.h.

Constructor & Destructor Documentation

◆ QSslKeyingMaterial() [1/3]

QSslKeyingMaterial::QSslKeyingMaterial ( )
default

Default-constructs an instance of QSslKeyingMaterial.

A default instance is never valid.

See also
isValid()

◆ QSslKeyingMaterial() [2/3]

QSslKeyingMaterial::QSslKeyingMaterial ( const QByteArray & label,
qsizetype size )
inlineexplicit

Definition at line 29 of file qsslkeyingmaterial.h.

References QSslKeyingMaterial().

Referenced by QSslKeyingMaterial().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ QSslKeyingMaterial() [3/3]

QSslKeyingMaterial::QSslKeyingMaterial ( const QByteArray & label,
qsizetype size,
const QByteArray & context )
inlineexplicit

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 \l{QByteArray::isNull()} to distinguish them.
See also
isValid(), label(), context(), value()

Definition at line 34 of file qsslkeyingmaterial.h.

References QSslKeyingMaterial().

Referenced by QSslKeyingMaterial().

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ context()

QByteArray QSslKeyingMaterial::context ( ) const
inlinenoexcept

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 \l{QSslKeyingMaterial::QSslKeyingMaterial()}).

See also
label(), value()

Definition at line 53 of file qsslkeyingmaterial.h.

◆ isValid()

bool QSslKeyingMaterial::isValid ( ) const
inlinenoexcept

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(), value()

Definition at line 43 of file qsslkeyingmaterial.h.

◆ label()

QByteArray QSslKeyingMaterial::label ( ) const
inlinenoexcept

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(), value()

Definition at line 48 of file qsslkeyingmaterial.h.

◆ requestedSize()

qsizetype QSslKeyingMaterial::requestedSize ( ) const
inlinenoexcept

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 \l label() and \l context() of the requested keying material.

See also
value()

Definition at line 63 of file qsslkeyingmaterial.h.

◆ swap()

void QSslKeyingMaterial::swap ( QSslKeyingMaterial & other)
inlinenoexcept

\memberswap{keying material}

Definition at line 68 of file qsslkeyingmaterial.h.

◆ value()

QByteArray QSslKeyingMaterial::value ( ) const
inlinenoexcept

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(), requestedSize()

Definition at line 58 of file qsslkeyingmaterial.h.

◆ comparesEqual

bool comparesEqual ( const QSslKeyingMaterial & lhs,
const QSslKeyingMaterial & rhs )
friend

Definition at line 82 of file qsslkeyingmaterial.h.

◆ operator<<

QDebug operator<< ( QDebug debug,
const QSslKeyingMaterial & keying )
friend

Writes a textual representation of the keying material keying to the debug object debug.

See also
{Debugging Techniques}

Definition at line 194 of file qsslkeyingmaterial.cpp.

◆ qHash [1/2]

size_t qHash ( const QSslKeyingMaterial & material)
friend

Definition at line 92 of file qsslkeyingmaterial.h.

◆ qHash [2/2]

Q_NETWORK_EXPORT size_t qHash ( const QSslKeyingMaterial & material,
size_t seed )
friend

Definition at line 179 of file qsslkeyingmaterial.cpp.

◆ QTlsPrivate::TlsCryptographOpenSSL

friend class QTlsPrivate::TlsCryptographOpenSSL
friend

Definition at line 100 of file qsslkeyingmaterial.h.

The documentation for this class was generated from the following files: