PySide6.QtNetwork.QSslKeyingMaterial¶

class QSslKeyingMaterial¶

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

Added in version 6.12.

Synopsis¶

Methods¶

def __init__()
def clone()
def context()
def isValid()
def label()
def __ne__()
def __eq__()
def requestedSize()
def swap()
def value()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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 read with value() .

QSslKeyingMaterial objects are typically configured via 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);

Security Considerations¶

Exported keying material is a secret. QByteArray is a copy-on-write container, so every QSslKeyingMaterial object holding a value shares one buffer, and the secret remains in memory for as long as any of those objects lives. An application that needs to guarantee it holds the only remaining reference must release the Qt-internal ones explicitly.

After a successful handshake the value lives in exactly one place inside Qt: the QSslKeyingMaterial entry in the socket’s internal QSslConfiguration . Each QSslConfiguration returned by sslConfiguration() is an independent copy of that configuration, sharing the value’s buffer with it.

Both takeKeyingMaterial() overloads hand the values over instead of sharing them: what they return holds the only reference to the value, and the entries they leave behind in the configuration they were called on are valueless clones . Copy the value out of the returned object with value() and let the object itself go out of scope, then write the configuration back to the socket: that overwrites the socket’s entry with the valueless one, dropping the last reference Qt holds.

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);

The following copies are outside the socket’s control and must be dealt with separately:

Any other QSslConfiguration copy the application still holds, including one stored in a QNetworkRequest or installed with setDefaultConfiguration() . Taking the value from one copy does not affect the others.

A configuration that was never written back to the socket. Taking the values out of a QSslConfiguration only strips that copy of the configuration; the socket keeps its own until it is given the valueless entries.

Any QSslKeyingMaterial copy the application made itself. Use clone() when a copy of a request is needed without its value.

The socket also drops the values when it starts a new handshake, because its entries are reset to valueless clones then, and when it is destroyed. Neither replaces the explicit step above for a socket that stays alive.

__init__()¶

Default-constructs an instance of QSslKeyingMaterial .

A default instance is never valid.

See also

isValid()

__init__(other)

Parameters:: other – QSslKeyingMaterial

__init__(label, size)

Parameters:

label – QByteArray
size – int

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.