kdbxtool.parsing.kdbx4

KDBX4 payload encryption and decryption.

This module handles the cryptographic operations for KDBX4 files: - Master key derivation from credentials - Header integrity verification (HMAC-SHA256) - Payload decryption and encryption - Block-based HMAC verification (HmacBlockStream) - Inner header parsing

KDBX4 structure: 1. Outer header (plaintext) 2. SHA-256 hash of header 3. HMAC-SHA256 of header 4. Encrypted payload (HmacBlockStream format)

• Inner header

• XML database content

Functions

read_kdbx4(data[, password, keyfile_data, ...])	Convenience function to read a KDBX4 file.
write_kdbx4(header, inner_header, xml_data)	Convenience function to write a KDBX4 file.

Classes

DecryptedPayload(header, inner_header, xml_data)	Result of decrypting a KDBX4 file.
InnerHeader(random_stream_id, ...)	KDBX4 inner header data.
Kdbx4Reader(data)	Reader for KDBX4 database files.
Kdbx4Writer()	Writer for KDBX4 database files.

class kdbxtool.parsing.kdbx4.InnerHeader(random_stream_id, random_stream_key, binaries)

Bases: object

KDBX4 inner header data.

The inner header appears after decryption, before the XML payload. It contains the protected stream cipher settings and binary attachments.

Parameters:

• random_stream_id (int)

• random_stream_key (bytes)

• binaries (dict[int, tuple[bool, bytes]])

random_stream_id: int

random_stream_key: bytes

binaries: dict[int, tuple[bool, bytes]]

__init__(random_stream_id, random_stream_key, binaries)

Parameters:

• random_stream_id (int)

• random_stream_key (bytes)

• binaries (dict[int, tuple[bool, bytes]])

Return type:

None

class kdbxtool.parsing.kdbx4.DecryptedPayload(header, inner_header, xml_data, transformed_key=None)

Bases: object

Result of decrypting a KDBX4 file.

Contains all data needed to work with the database.

Parameters:

• header (KdbxHeader)

• inner_header (InnerHeader)

• xml_data (bytes)

• transformed_key (bytes | None)

header: KdbxHeader

inner_header: InnerHeader

xml_data: bytes

transformed_key: bytes | None

__init__(header, inner_header, xml_data, transformed_key=None)

Parameters:

• header (KdbxHeader)

• inner_header (InnerHeader)

• xml_data (bytes)

• transformed_key (bytes | None)

Return type:

None

class kdbxtool.parsing.kdbx4.Kdbx4Reader(data)

Bases: object

Reader for KDBX4 database files.

Parameters:

data (bytes)

__init__(data)

Initialize reader with file data.

Parameters:

data (bytes) – Complete KDBX4 file contents

Return type:

None

decrypt(password=None, keyfile_data=None, transformed_key=None, yubikey_response=None)

Decrypt the KDBX4 file.

Parameters:

• password (str | None) – Optional password

• keyfile_data (bytes | None) – Optional keyfile contents

• transformed_key (bytes | None) – Optional precomputed transformed key (skips KDF)

• yubikey_response (bytes | None) – Optional 20-byte YubiKey HMAC-SHA1 response

Returns:

DecryptedPayload with header, inner header, XML, and transformed_key

Raises:

ValueError – If decryption fails (wrong credentials, corrupted file)

Return type:

DecryptedPayload

class kdbxtool.parsing.kdbx4.Kdbx4Writer

Bases: object

Writer for KDBX4 database files.

BLOCK_SIZE = 1048576

encrypt(header, inner_header, xml_data, password=None, keyfile_data=None, transformed_key=None, yubikey_response=None)

Encrypt database to KDBX4 format.

Parameters:

• header (KdbxHeader) – Outer header configuration

• inner_header (InnerHeader) – Inner header with stream cipher and binaries

• xml_data (bytes) – XML database content

• password (str | None) – Optional password

• keyfile_data (bytes | None) – Optional keyfile contents

• transformed_key (bytes | None) – Optional precomputed transformed key (skips KDF)

• yubikey_response (bytes | None) – Optional 20-byte YubiKey HMAC-SHA1 response

Returns:

Complete KDBX4 file as bytes

Return type:

bytes

kdbxtool.parsing.kdbx4.read_kdbx4(data, password=None, keyfile_data=None, transformed_key=None, yubikey_response=None)

Convenience function to read a KDBX4 file.

Parameters:

• data (bytes) – Complete file contents

• password (str | None) – Optional password

• keyfile_data (bytes | None) – Optional keyfile contents

• transformed_key (bytes | None) – Optional precomputed transformed key (skips KDF)

• yubikey_response (bytes | None) – Optional 20-byte YubiKey HMAC-SHA1 response

Returns:

DecryptedPayload with header, inner header, XML, and transformed_key

Return type:

DecryptedPayload

kdbxtool.parsing.kdbx4.write_kdbx4(header, inner_header, xml_data, password=None, keyfile_data=None, transformed_key=None, yubikey_response=None)

Convenience function to write a KDBX4 file.

Parameters:

• header (KdbxHeader) – Outer header configuration

• inner_header (InnerHeader) – Inner header with stream cipher and binaries

• xml_data (bytes) – XML database content

• password (str | None) – Optional password

• keyfile_data (bytes | None) – Optional keyfile contents

• transformed_key (bytes | None) – Optional precomputed transformed key (skips KDF)

• yubikey_response (bytes | None) – Optional 20-byte YubiKey HMAC-SHA1 response

Returns:

Complete KDBX4 file as bytes

Return type:

bytes