kdbxtool.security.crypto

Cryptographic primitives and utilities for kdbxtool.

This module provides: - Constant-time comparison functions for authentication - Cipher abstractions for KDBX encryption - HMAC utilities for integrity verification

All cryptographic operations use well-audited libraries (PyCryptodome).

Functions

compute_hmac_sha256(key, data)	Compute HMAC-SHA256 of data using the given key.
constant_time_compare(a, b)	Compare two byte sequences in constant time.
secure_random_bytes(n)	Generate cryptographically secure random bytes.
verify_hmac_sha256(key, data, expected_mac)	Verify HMAC-SHA256 in constant time.

Classes

Cipher(*values)	Supported ciphers for KDBX encryption.
CipherContext(cipher, key, iv)	Context for encrypting or decrypting data with a KDBX cipher.

class kdbxtool.security.crypto.Cipher(*values)

Bases: Enum

Supported ciphers for KDBX encryption.

KDBX supports three ciphers: - AES-256-CBC: Traditional cipher, widely supported - ChaCha20: Modern stream cipher, faster in software - Twofish-256-CBC: Legacy cipher, requires oxifish package

Note: KDBX uses plain ChaCha20, not ChaCha20-Poly1305. Authentication is provided by the HMAC block stream.

The UUID values are defined in the KDBX specification.

AES256_CBC = b'1\xc1\xf2\xe6\xbfqCP\xbeX\x05!j\xfcZ\xff'

CHACHA20 = b'\xd6\x03\x8a+\x8boL\xb5\xa5$3\x9a1\xdb\xb5\x9a'

TWOFISH256_CBC = b'\xadh\xf2\x9fWoK\xb9\xa3j\xd4z\xf9e4l'

property key_size: int

Return the key size in bytes for this cipher.

property iv_size: int

Return the IV/nonce size in bytes for this cipher.

property display_name: str

Human-readable cipher name.

classmethod from_uuid(uuid_bytes)

Look up cipher by its KDBX UUID.

Parameters:

uuid_bytes (bytes) – 16-byte cipher identifier from KDBX header

Returns:

The corresponding Cipher enum value

Raises:

ValueError – If the UUID doesn’t match any known cipher

Return type:

Cipher

kdbxtool.security.crypto.constant_time_compare(a, b)

Compare two byte sequences in constant time.

This prevents timing attacks where an attacker could measure response time differences to deduce secret values.

Parameters:

• a (bytes | bytearray) – First byte sequence

• b (bytes | bytearray) – Second byte sequence

Returns:

True if sequences are equal, False otherwise

Return type:

bool

kdbxtool.security.crypto.secure_random_bytes(n)

Generate cryptographically secure random bytes.

Uses os.urandom which is suitable for cryptographic use.

Parameters:

n (int) – Number of random bytes to generate

Returns:

n cryptographically random bytes

Return type:

bytes

kdbxtool.security.crypto.compute_hmac_sha256(key, data)

Compute HMAC-SHA256 of data using the given key.

Parameters:

• key (bytes) – HMAC key

• data (bytes) – Data to authenticate

Returns:

32-byte HMAC-SHA256 digest

Return type:

bytes

kdbxtool.security.crypto.verify_hmac_sha256(key, data, expected_mac)

Verify HMAC-SHA256 in constant time.

Parameters:

• key (bytes) – HMAC key

• data (bytes) – Data that was authenticated

• expected_mac (bytes) – Expected MAC value to verify against

Returns:

True if MAC is valid, False otherwise

Return type:

bool

class kdbxtool.security.crypto.CipherContext(cipher, key, iv)

Bases: object

Context for encrypting or decrypting data with a KDBX cipher.

This class wraps PyCryptodome cipher implementations with a consistent interface for KDBX operations.

Parameters:

• cipher (Cipher)

• key (bytes)

• iv (bytes)

__init__(cipher, key, iv)

Initialize cipher context.

Parameters:

• cipher (Cipher) – Which cipher algorithm to use

• key (bytes) – Encryption key (32 bytes)

• iv (bytes) – Initialization vector/nonce

Raises:

• ValueError – If key or IV size is incorrect

• TwofishNotAvailableError – If Twofish requested but oxifish not installed

Return type:

None

encrypt(plaintext)

Encrypt plaintext data.

For AES-CBC and Twofish-CBC, data must be padded to block size. For ChaCha20, returns stream-encrypted ciphertext (same length as input).

Parameters:

plaintext (bytes) – Data to encrypt

Returns:

Encrypted data (same length as input for ChaCha20)

Return type:

bytes

decrypt(ciphertext)

Decrypt ciphertext data.

For AES-CBC and Twofish-CBC, returns decrypted data (caller must remove padding). For ChaCha20, returns stream-decrypted plaintext.

Parameters:

ciphertext (bytes) – Data to decrypt

Returns:

Decrypted plaintext

Return type:

bytes