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

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

Friends

class QTlsPrivate::TlsCryptographOpenSSL
class ::tst_QSslKeyingMaterial
Q_NETWORK_EXPORT bool comparesEqual (const QSslKeyingMaterial &lhs, const QSslKeyingMaterial &rhs)
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 \preliminary

\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 read with 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().takeKeyingMaterial(keying)->value();
// Both client and server will obtain the same 'derived' bytes
// even though they each performed the derivation independently.
use(derived);
QByteArray
\inmodule QtCore
Definition qbytearray.h:58
QSslKeyingMaterial::QSslKeyingMaterial
Q_NETWORK_EXPORT QSslKeyingMaterial()
Default-constructs an instance of QSslKeyingMaterial.

Definition at line 28 of file qsslkeyingmaterial.h.

Constructor & Destructor Documentation

◆ QSslKeyingMaterial() [1/5]

QSslKeyingMaterial::QSslKeyingMaterial ( )
default

Default-constructs an instance of QSslKeyingMaterial.

A default instance is never valid.

See also
isValid()

◆ QSslKeyingMaterial() [2/5]

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

Definition at line 155 of file qsslkeyingmaterial.cpp.

◆ QSslKeyingMaterial() [3/5]

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

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 161 of file qsslkeyingmaterial.cpp.

◆ QSslKeyingMaterial() [4/5]

QSslKeyingMaterial::QSslKeyingMaterial ( const QSslKeyingMaterial & other)
default

◆ QSslKeyingMaterial() [5/5]

QSslKeyingMaterial::QSslKeyingMaterial ( QSslKeyingMaterial && other)
inlinenoexcept

Definition at line 37 of file qsslkeyingmaterial.h.

◆ ~QSslKeyingMaterial()

QSslKeyingMaterial::~QSslKeyingMaterial ( )
default

Member Function Documentation

◆ clone()

QSslKeyingMaterial QSslKeyingMaterial::clone ( ) const
nodiscard

Returns a copy of this keying material request, without its value().

The returned object carries the exporter label(), context() and requestedSize(), so it can be used to request the same keying material again, but its value() is empty. Use it to initialize a copy, or to reset an entry, without carrying the value along.

See also
value()

Definition at line 228 of file qsslkeyingmaterial.cpp.

◆ context()

QByteArray QSslKeyingMaterial::context ( ) const
inline

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 54 of file qsslkeyingmaterial.h.

◆ isValid()

bool QSslKeyingMaterial::isValid ( ) const
noexcept

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 187 of file qsslkeyingmaterial.cpp.

◆ label()

QByteArray QSslKeyingMaterial::label ( ) const
inline

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 49 of file qsslkeyingmaterial.h.

◆ operator=()

QSslKeyingMaterial & QSslKeyingMaterial::operator= ( const QSslKeyingMaterial & other)
default

◆ 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 64 of file qsslkeyingmaterial.h.

◆ swap()

void QSslKeyingMaterial::swap ( QSslKeyingMaterial & other)
inlinenoexcept

\memberswap{keying material}

Definition at line 71 of file qsslkeyingmaterial.h.

◆ value()

QByteArray QSslKeyingMaterial::value ( ) const
inline

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 \l{QSslKeyingMaterial#Security Considerations}{Security Considerations} for how to keep the returned QByteArray the only copy of it.
See also
label(), context(), requestedSize()

Definition at line 59 of file qsslkeyingmaterial.h.

◆ ::tst_QSslKeyingMaterial

friend class ::tst_QSslKeyingMaterial
friend

Definition at line 100 of file qsslkeyingmaterial.h.

◆ comparesEqual

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

Definition at line 283 of file qsslkeyingmaterial.cpp.

◆ 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 301 of file qsslkeyingmaterial.cpp.

◆ qHash [1/2]

size_t qHash ( const QSslKeyingMaterial & material)
friend

Definition at line 91 of file qsslkeyingmaterial.h.

◆ qHash [2/2]

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

Definition at line 276 of file qsslkeyingmaterial.cpp.

◆ QTlsPrivate::TlsCryptographOpenSSL

friend class QTlsPrivate::TlsCryptographOpenSSL
friend

Definition at line 99 of file qsslkeyingmaterial.h.

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