Metadata-Version: 2.4
Name: kdbxtool
Version: 0.1.1
Summary: A modern, secure Python library for reading and writing KeePass KDBX databases
Project-URL: Homepage, https://github.com/coreyleavitt/kdbxtool
Project-URL: Repository, https://github.com/coreyleavitt/kdbxtool
Author: Corey Leavitt
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: encryption,kdbx,keepass,password,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: defusedxml>=0.7.0
Requires-Dist: pycryptodomex>=3.20.0
Provides-Extra: twofish
Requires-Dist: oxifish>=0.1.1; extra == 'twofish'
Provides-Extra: yubikey
Requires-Dist: yubikey-manager>=5.0.0; extra == 'yubikey'
Description-Content-Type: text/markdown

# kdbxtool

[![CI](https://github.com/coreyleavitt/kdbxtool/actions/workflows/ci.yml/badge.svg)](https://github.com/coreyleavitt/kdbxtool/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/endpoint?url=https://coreyleavitt.github.io/kdbxtool/coverage/coverage-badge.json)](https://coreyleavitt.github.io/kdbxtool/coverage/htmlcov/)
[![mypy](https://img.shields.io/endpoint?url=https://coreyleavitt.github.io/kdbxtool/mypy/mypy-badge.json)](https://coreyleavitt.github.io/kdbxtool/mypy/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A modern, secure Python library for reading and writing KeePass KDBX databases.

## Features

- **Secure by default**: Memory zeroization, constant-time comparisons, hardened XML parsing
- **Type-safe**: Full type hints, Python 3.12+ features, mypy strict compatible
- **Modern API**: Clean, Pythonic interface with context manager support
- **KDBX4 focused**: First-class support for modern KeePass format with Argon2
- **Multiple ciphers**: AES-256-CBC, ChaCha20, and Twofish-256-CBC (optional)

## Installation

```bash
pip install kdbxtool
```

### Optional: Twofish Support

For legacy databases encrypted with Twofish-256-CBC:

```bash
pip install kdbxtool[twofish]
```

This installs [oxifish](https://github.com/coreyleavitt/oxifish), a Rust-based Twofish implementation.

### Optional: YubiKey Support

For hardware-backed authentication with YubiKey HMAC-SHA1 challenge-response:

```bash
pip install kdbxtool[yubikey]
```

This installs [yubikey-manager](https://github.com/Yubico/yubikey-manager) for YubiKey communication.

## Quick Start

```python
from kdbxtool import Database

# Open a database with context manager
with Database.open("vault.kdbx", password="my-password") as db:
    # Find entries
    entries = db.find_entries(title="Gmail")
    if entries:
        print(f"Username: {entries[0].username}")

    # Create new entries
    db.root_group.create_entry(
        title="New Account",
        username="user@example.com",
        password="secure-password",
    )

    db.save()

# Create a new database
db = Database.create(password="my-password", database_name="My Vault")
db.root_group.create_entry(title="First Entry", username="me", password="secret")
db.save("my-vault.kdbx")
```

## YubiKey Support

kdbxtool supports YubiKey HMAC-SHA1 challenge-response authentication, compatible with KeePassXC:

```python
from kdbxtool import Database
from kdbxtool.security import list_yubikeys, is_yubikey_available

# Check YubiKey availability
if is_yubikey_available():
    devices = list_yubikeys()
    for device in devices:
        print(f"Found: {device['name']} (serial: {device.get('serial', 'N/A')})")

# Open a YubiKey-protected database
with Database.open("vault.kdbx", password="my-password", yubikey_slot=2) as db:
    print(f"Entries: {len(db.find_entries())}")
    db.save()

# Create a new database with YubiKey protection
db = Database.create(
    password="my-password",
    yubikey_slot=2,           # Use slot 2 (recommended)
    yubikey_serial=12345678,  # Optional: specific YubiKey serial
)
db.save("protected.kdbx")

# Open with specific YubiKey when multiple are connected
with Database.open(
    "vault.kdbx",
    password="my-password",
    yubikey_slot=2,
    yubikey_serial=12345678,
) as db:
    pass
```

Requirements:
- YubiKey with HMAC-SHA1 configured in slot 1 or 2
- Configure with: `ykman otp chalresp -g 2` (generates random secret for slot 2)

## Security

kdbxtool prioritizes security:

- **SecureBytes**: Sensitive data is stored in zeroizable buffers
- **Constant-time comparisons**: All authentication uses `hmac.compare_digest`
- **Hardened XML**: Uses defusedxml to prevent XXE attacks
- **Modern KDF**: Enforces minimum Argon2 parameters

## License

Apache-2.0
