kdbxtool.security.kdf¶

Key Derivation Functions for KDBX databases.

This module provides secure KDF implementations for: - Argon2d: Default KDF for KDBX4 (KeePassXC compatible, better GPU resistance) - Argon2id: Alternative Argon2 variant with timing attack resistance - AES-KDF: Legacy KDF for KDBX3 read support (not for new databases)

Security considerations: - Argon2 enforces minimum parameters to prevent weak configurations - All derived keys are returned as SecureBytes for automatic zeroization

Functions

`derive_composite_key`([password, ...])	Create composite key from password, keyfile, and/or YubiKey response.
`derive_key_aes_kdf`(password, config)	Derive a 32-byte key using legacy AES-KDF.
`derive_key_argon2`(password, config, *[, ...])	Derive a 32-byte key using Argon2.

Classes

`AesKdfConfig`(rounds, salt)	Configuration for AES-KDF key derivation.
`Argon2Config`(memory_kib, iterations, ...[, ...])	Configuration for Argon2 key derivation.
`KdfType`(*values)	Supported Key Derivation Functions in KDBX.

class kdbxtool.security.kdf.KdfType(*values)[source]¶

Bases: Enum

Supported Key Derivation Functions in KDBX.

The UUID values are defined in the KDBX specification.

ARGON2D = b'\xefcm\xdf\x8c)DK\x91\xf7\xa9\xa4\x03\xe3\n\x0c'¶

ARGON2ID = b'\x9e)\x8b\x19V\xdbGs\xb2=\xfc>\xc6\xf0\xa1\xe6'¶

AES_KDF = b'\xc9\xd9\xf3\x9ab\x8aD`\xbft\r\x08\xc1\x8aO\xea'¶

property display_name: str¶: Human-readable KDF name.

classmethod from_uuid(uuid_bytes)[source]¶

Look up KDF by its KDBX UUID.

Parameters:: uuid_bytes (bytes) – 16-byte KDF identifier from KDBX header
Returns:: The corresponding KdfType enum value
Raises:: ValueError – If the UUID doesn’t match any known KDF
Return type:: KdfType

class kdbxtool.security.kdf.Argon2Config(memory_kib, iterations, parallelism, salt, variant=KdfType.ARGON2D)[source]¶

Bases: object

Configuration for Argon2 key derivation.

Parameters:

memory_kib (int)
iterations (int)
parallelism (int)
salt (bytes)
variant (KdfType)

memory_kib¶

Memory usage in KiB

Type:: int

iterations¶

Number of iterations (time cost)

Type:: int

parallelism¶

Degree of parallelism

Type:: int

salt¶

Random salt (must be at least 16 bytes)

Type:: bytes

variant¶

Argon2 variant (Argon2d or Argon2id)

Type:: kdbxtool.security.kdf.KdfType

memory_kib: int¶

iterations: int¶

parallelism: int¶

salt: bytes¶

variant: KdfType¶

validate_security()[source]¶

Check that parameters meet minimum security requirements.

Raises:: ValueError – If parameters are below security minimums
Return type:: None

classmethod default(salt=None, variant=KdfType.ARGON2D)[source]¶

Create configuration with secure defaults.

Alias for standard(). Provides balanced security and performance.

Parameters:

salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
variant (KdfType) – Argon2 variant (ARGON2D or ARGON2ID). Default is ARGON2D which provides better GPU resistance for local password databases.

Returns:

Argon2Config with recommended security parameters

Return type:

Argon2Config

classmethod standard(salt=None, variant=KdfType.ARGON2D)[source]¶

Create configuration with balanced security/performance.

Suitable for most use cases. Provides good security with reasonable unlock times on modern hardware.

Parameters: 64 MiB memory, 3 iterations, 4 parallelism

Parameters:

salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
variant (KdfType) – Argon2 variant (ARGON2D or ARGON2ID). Default is ARGON2D which provides better GPU resistance for local password databases. Use ARGON2ID if timing attack resistance is needed.

Returns:

Argon2Config with standard security parameters

Return type:

Argon2Config

classmethod high_security(salt=None, variant=KdfType.ARGON2D)[source]¶

Create configuration for high-security applications.

Use for sensitive data where longer unlock times are acceptable. Provides stronger protection against brute-force attacks.

Parameters: 256 MiB memory, 10 iterations, 4 parallelism

Parameters:

salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
variant (KdfType) – Argon2 variant (ARGON2D or ARGON2ID). Default is ARGON2D which provides better GPU resistance for local password databases.

Returns:

Argon2Config with high security parameters

Return type:

Argon2Config

classmethod fast(salt=None, variant=KdfType.ARGON2D)[source]¶

Create configuration for fast operations (testing only).

WARNING: This provides minimal security and should only be used for testing or development. Not suitable for production databases.

Parameters: 16 MiB memory, 3 iterations, 2 parallelism

Parameters:

salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
variant (KdfType) – Argon2 variant (ARGON2D or ARGON2ID). Default is ARGON2D.

Returns:

Argon2Config with minimal parameters

Return type:

Argon2Config

__init__(memory_kib, iterations, parallelism, salt, variant=KdfType.ARGON2D)¶

Parameters:

memory_kib (int)
iterations (int)
parallelism (int)
salt (bytes)
variant (KdfType)

Return type:

None

class kdbxtool.security.kdf.AesKdfConfig(rounds, salt)[source]¶

Bases: object

Configuration for AES-KDF key derivation.

AES-KDF is supported in both KDBX3 and KDBX4. While Argon2 is generally recommended for new databases, AES-KDF may be preferred for compatibility with older KeePass clients or on systems where Argon2 is slow.

Parameters:

rounds (int)
salt (bytes)

rounds¶

Number of AES encryption rounds (higher = slower but more secure)

Type:: int

salt¶

32-byte salt

Type:: bytes

rounds: int¶

salt: bytes¶

classmethod standard(salt=None)[source]¶

Create configuration with balanced security/performance.

Uses 600,000 rounds which provides reasonable security while keeping unlock times acceptable on most hardware.

Parameters:: salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
Returns:: AesKdfConfig with standard parameters
Return type:: AesKdfConfig

classmethod high_security(salt=None)[source]¶

Create configuration for high-security applications.

Uses 6,000,000 rounds for stronger protection at the cost of longer unlock times.

Parameters:: salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
Returns:: AesKdfConfig with high security parameters
Return type:: AesKdfConfig

classmethod fast(salt=None)[source]¶

Create configuration for fast operations (testing only).

WARNING: Uses only 60,000 rounds which provides minimal security. Only use for testing or development.

Parameters:: salt (bytes | None) – Optional salt (32 random bytes generated if not provided)
Returns:: AesKdfConfig with minimal parameters
Return type:: AesKdfConfig

__init__(rounds, salt)¶

Parameters:

rounds (int)
salt (bytes)

Return type:

None

kdbxtool.security.kdf.derive_key_argon2(password, config, *, enforce_minimums=True)[source]¶

Derive a 32-byte key using Argon2.

Parameters:

password (bytes) – Password bytes (usually composite key hash)
config (Argon2Config) – Argon2 configuration parameters
enforce_minimums (bool) – If True, reject weak parameters

Returns:

32-byte derived key wrapped in SecureBytes

Raises:

ValueError – If parameters are invalid or below minimums

Return type:

SecureBytes

kdbxtool.security.kdf.derive_key_aes_kdf(password, config)[source]¶

Derive a 32-byte key using legacy AES-KDF.

This performs repeated AES-ECB encryption of the password using the salt as key. Only use for KDBX3 compatibility.

Parameters:

password (bytes) – 32-byte password hash
config (AesKdfConfig) – AES-KDF configuration

Returns:

32-byte derived key wrapped in SecureBytes

Raises:

ValueError – If password is not 32 bytes

Return type:

SecureBytes

kdbxtool.security.kdf.derive_composite_key(password=None, keyfile_data=None, yubikey_response=None)[source]¶

Create composite key from password, keyfile, and/or YubiKey response.

The composite key is SHA-256(password_hash || keyfile_key || challenge_result).

KeePassXC-compatible YubiKey handling: - The YubiKey response (20 bytes HMAC-SHA1) is SHA-256 hashed - This hash is appended to the other key components before final SHA-256 - The challenge used to obtain the response should be the KDF salt

The keyfile_key is processed according to KeePass keyfile format rules.

Parameters:

password (str | None) – Optional password string
keyfile_data (bytes | None) – Optional keyfile contents
yubikey_response (bytes | None) – Optional 20-byte YubiKey HMAC-SHA1 response

Returns:

32-byte composite key wrapped in SecureBytes

Raises:

MissingCredentialsError – If no credentials are provided
ValueError – If yubikey_response is provided but wrong size

Return type:

SecureBytes