core.kdf

TLS Key Derivation Function implementations for validation.

Provides pure-stdlib (hmac + hashlib) implementations of: - TLS 1.2 PRF (RFC 5246, Section 5) based on P_SHA256 - TLS 1.3 HKDF functions (RFC 8446, Section 7) based on HKDF-Extract/Expand

These are used by the constraint validator algorithm to verify that candidate key bytes found in memory dumps satisfy the expected KDF relationships (e.g. a candidate master secret actually derives from a candidate pre-master secret via the TLS 1.2 PRF).

class TLS12PRF

Bases: object

TLS 1.2 Pseudo-Random Function (RFC 5246).

TLS 1.2 uses a single PRF based on P_SHA256:

PRF(secret, label, seed) = P_SHA256(secret, label + seed)

where P_hash is the iterative HMAC expansion defined in Section 5.

static p_hash(secret, seed, length, hash_algo='sha256')

P_hash expansion (RFC 5246 Section 5).

Iteratively applies HMAC: A(i) = HMAC(secret, A(i-1)), output = HMAC(secret, A(1)+seed) || HMAC(secret, A(2)+seed) || …

Parameters:

• secret (bytes)

• seed (bytes)

• length (int)

• hash_algo (str)

Return type:

bytes

static prf(secret, label, seed, length, hash_algo='sha256')

PRF(secret, label, seed) = P_SHA256(secret, label + seed).

Parameters:

• secret (bytes)

• label (bytes)

• seed (bytes)

• length (int)

• hash_algo (str)

Return type:

bytes

static derive_master_secret(pre_master_secret, client_random, server_random, hash_algo='sha256')

Derive the 48-byte master secret (RFC 5246 Section 8.1).

Parameters:

• pre_master_secret (bytes)

• client_random (bytes)

• server_random (bytes)

• hash_algo (str)

Return type:

bytes

static derive_key_block(master_secret, server_random, client_random, length, hash_algo='sha256')

Derive the key block (RFC 5246 Section 6.3).

Note: seed order is server_random + client_random (reversed from master secret derivation).

Parameters:

• master_secret (bytes)

• server_random (bytes)

• client_random (bytes)

• length (int)

• hash_algo (str)

Return type:

bytes

class TLS13HKDF

Bases: object

TLS 1.3 HKDF functions (RFC 8446, Section 7).

Implements HKDF-Extract and HKDF-Expand (RFC 5869) plus the TLS 1.3 specific HKDF-Expand-Label and Derive-Secret helpers.

static hkdf_extract(salt, ikm, hash_algo='sha256')

HKDF-Extract: PRK = HMAC(salt, IKM) (RFC 5869 Section 2.2).

Parameters:

• salt (bytes)

• ikm (bytes)

• hash_algo (str)

Return type:

bytes

static hkdf_expand(prk, info, length, hash_algo='sha256')

HKDF-Expand: iterative HMAC expansion (RFC 5869 Section 2.3).

Parameters:

• prk (bytes)

• info (bytes)

• length (int)

• hash_algo (str)

Return type:

bytes

static hkdf_expand_label(secret, label, context, length, hash_algo='sha256')

HKDF-Expand-Label: builds HkdfLabel struct (RFC 8446 Section 7.1).

Parameters:

• secret (bytes)

• label (str)

• context (bytes)

• length (int)

• hash_algo (str)

Return type:

bytes

static derive_secret(secret, label, messages_hash, hash_algo='sha256')

Derive-Secret (RFC 8446 Section 7.1).

Parameters:

• secret (bytes)

• label (str)

• messages_hash (bytes)

• hash_algo (str)

Return type:

bytes

Base class and types for KDF (Key Derivation Function) plugins.

KDF plugins are auto-discovered from core/kdf_*.py modules that contain subclasses of BaseKDF. This mirrors the algorithm plugin pattern in algorithms/base.py but lives in core/ because KDF implementations are stdlib-only cryptographic primitives.

class KDFParams

Bases: object

Parameters for a key derivation operation.

hash_algo: str = 'sha256'

key_lengths: tuple = (16, 32)

labels: tuple = ()

context: bytes = b''

extra: Dict[str, Any]

__init__(hash_algo='sha256', key_lengths=(16, 32), labels=(), context=b'', extra=<factory>)

Parameters:

• hash_algo (str)

• key_lengths (tuple)

• labels (tuple)

• context (bytes)

• extra (Dict[str, Any])

Return type:

None

class BaseKDF

Bases: ABC

Abstract base for all KDF plugins.

Subclasses must set name, protocol, and versions as class attributes and implement the four abstract methods.

name: str = ''

protocol: str = ''

versions: Set[str] = {}

abstract derive(secret, params)

Derive output key material from secret using params.

Parameters:

• secret (bytes)

• params (KDFParams)

Return type:

bytes

abstract expand_traffic_secret(secret, key_lengths=None, hash_algo='sha256')

Expand a traffic/session secret into derived keys and IVs.

Parameters:

• secret (CryptoSecret)

• key_lengths (List[int] | None)

• hash_algo (str)

Return type:

List[CryptoSecret]

abstract validate_pair(candidate_a, candidate_b, dump_data, hash_algo='sha256')

Test whether candidate_a and candidate_b are KDF-related.

Returns a confidence score between 0.0 (unrelated) and 1.0 (confirmed relationship).

Parameters:

• candidate_a (bytes)

• candidate_b (bytes)

• dump_data (bytes)

• hash_algo (str)

Return type:

float

supported_secret_types()

Return secret types this KDF can expand.

Override in subclasses; the default returns an empty set (no expansion capability).

Return type:

Set[str]

Auto-discovery registry for KDF (Key Derivation Function) plugins.

Mirrors the algorithm plugin pattern in algorithms/registry.py. Discovers BaseKDF subclasses from all core/kdf_*.py modules via importlib.

class KDFRegistry

Bases: object

Discover and manage KDF plugins from core/kdf_*.py modules.

__init__()

discover()

Walk core/kdf_*.py modules and register BaseKDF subclasses.

Return type:

None

get(name)

Return KDF plugin by name, or None.

Parameters:

name (str)

Return type:

BaseKDF | None

get_for_protocol(protocol, version)

Return the first KDF matching protocol and version.

Parameters:

• protocol (str)

• version (str)

Return type:

BaseKDF | None

list_all()

Return all registered KDF plugins.

Return type:

List[BaseKDF]

get_kdf_registry()

Return the lazily-initialised global KDF registry.

Return type:

KDFRegistry