Skip to content

Add KDF parameter customization and builder module refactor#2

Merged
coreyleavitt merged 4 commits into
masterfrom
feature/argon2-kdf-setters
Nov 29, 2025
Merged

Add KDF parameter customization and builder module refactor#2
coreyleavitt merged 4 commits into
masterfrom
feature/argon2-kdf-setters

Conversation

@coreyleavitt
Copy link
Copy Markdown
Owner

@coreyleavitt coreyleavitt commented Nov 29, 2025

Summary

KDF Parameter Customization

KDBX4 (Argon2):

  • argon2_iterations - get/set time cost
  • argon2_memory - get/set memory cost (KiB)
  • argon2_parallelism - get/set thread count
  • argon2_variant - get/set variant (argon2id or argon2d)

KDBX3 (AES-KDF):

  • transform_rounds - get/set AES transformation rounds

Database Creation Rewrite

Builder Module

Extract database creation logic into kdbx_parsing/builder.py with type-safe API:

  • Argon2Config dataclass with .standard(), .high_security(), .fast() presets
  • AesKdfConfig dataclass with .standard(), .high_security() presets
  • Cipher enum (AES256, CHACHA20, TWOFISH)
  • KdfAlgorithm enum (ARGON2ID, ARGON2D, AES_KDF)

Other Changes

  • Bump minimum Python version to 3.11 (for StrEnum support)
  • Add 18 new tests

Example Usage

from pykeepass import PyKeePass, create_database, Argon2Config, AesKdfConfig, Cipher

# KDBX4 with default settings
kp = create_database('vault.kdbx', password='secret')

# KDBX4 with high security Argon2
kp = create_database('vault.kdbx', password='secret', kdf=Argon2Config.high_security())

# KDBX4 with custom Argon2 parameters
kp = create_database('vault.kdbx', password='secret', 
                     kdf=Argon2Config(iterations=100, memory_kib=262144, parallelism=4))

# KDBX3 database with AES-KDF
kp = create_database('legacy.kdbx', password='secret', version=3)
kp = create_database('legacy.kdbx', password='secret', version=3, 
                     kdf=AesKdfConfig(rounds=100000))

# Modify KDF on existing KDBX4 database
kp = PyKeePass('vault.kdbx', password='secret')
kp.argon2_iterations = 50
kp.argon2_memory = 131072
kp.argon2_variant = 'argon2d'
kp.save()

# Modify KDF on existing KDBX3 database
kp = PyKeePass('legacy.kdbx', password='secret')
kp.transform_rounds = 100000
kp.save()

Test Plan

  • All 142 tests pass
  • CI passes on Python 3.11, 3.12, 3.13

This change adds support for customizing Argon2 key derivation parameters:

- Add argon2_iterations, argon2_memory, argon2_parallelism properties
  with getters and setters to PyKeePass class
- Rewrite create_database() to build KDBX4 structure from scratch
  instead of copying a template file
- Add encryption and kdf parameters to create_database()
- Remove blank_database.kdbx template (no longer needed)

The new create_database() supports:
- Custom encryption algorithm (aes256, chacha20, twofish)
- Custom KDF (argon2id, argon2)
- Custom Argon2 parameters (iterations, memory, parallelism)

KDF parameters can also be modified on existing databases using the
new property setters, which properly invalidate the header cache to
ensure changes are persisted on save.
- Extract _build_kdbx4_structure() to kdbx_parsing/builder.py
- Add KDBX3 database creation support
- Replace string params with type-safe dataclasses:
  - Argon2Config with .standard(), .high_security(), .fast() presets
  - AesKdfConfig with .standard(), .high_security() presets
  - Cipher and KdfAlgorithm StrEnums
- Add 14 new tests for KDBX3 creation and config presets
- Add transform_rounds getter/setter for KDBX3 AES-KDF round modification
- Add argon2_variant getter/setter to switch between argon2id and argon2d
- Add 4 new tests for the new properties
@coreyleavitt coreyleavitt merged commit 2c75068 into master Nov 29, 2025
6 checks passed
coreyleavitt added a commit that referenced this pull request Nov 30, 2025
Add KDF parameter customization and builder module refactor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant