feat: PKCS#11 challenge-response provider

[coreyleavitt]

Summary

Add generic PKCS#11 support as a challenge-response provider, enabling use of smart cards, HSMs, and other PKCS#11-compatible devices for database protection.

Background

PKCS#11 (Cryptoki) is a standard API for cryptographic tokens. Supporting it would enable a wide range of devices:

• Smart Cards: PIV cards, CAC cards, national ID cards
• HSMs: Nitrokey HSM, YubiHSM, enterprise HSMs
• YubiKey PIV mode: Different from HMAC-SHA1 slot
• Software tokens: SoftHSM (for testing)

Proposed Implementation

from kdbxtool import Pkcs11Provider

# Using a smart card
provider = Pkcs11Provider(
    library_path="/usr/lib/opensc-pkcs11.so",
    slot=0,
    key_id=b"\x01",  # Key identifier
    pin_callback=lambda: getpass("Smart card PIN: "),
)

# Using YubiKey PIV
provider = Pkcs11Provider(
    library_path="/usr/lib/libykcs11.so",
    slot=0,
    key_label="PIV AUTH key",
    pin_callback=lambda: getpass("PIV PIN: "),
)

db = Database.open("vault.kdbx", password="secret", challenge_response_provider=provider)

Technical Considerations

Challenge-Response via Signing

PKCS#11 doesn't have a direct HMAC-with-stored-key operation on all devices. Options:

1. HMAC (C_Sign with CKM_SHA256_HMAC): Ideal but not universally supported
2. RSA/ECDSA Signing: Sign the challenge, use signature as response
3. Key Derivation: Some HSMs support HKDF

Recommendation: Support HMAC where available, fall back to signing.

Output Normalization

• HMAC-SHA256: 32 bytes (matches FIDO2)
• RSA signature: 256-512 bytes (needs hashing to normalize)
• ECDSA signature: 64-72 bytes (needs hashing to normalize)

# Normalize any signature to 32 bytes for KDF
response = hashlib.sha256(raw_signature).digest()

Dependencies

[project.optional-dependencies]
pkcs11 = ["python-pkcs11>=0.7"]

Tasks

• Research python-pkcs11 library API
• Design key discovery/selection workflow
• Implement Pkcs11Provider class
• Support HMAC operation where available
• Support signing fallback with output normalization
• Handle PIN prompting
• Add tests with SoftHSM
• Test with common devices (YubiKey PIV, Nitrokey)
• Documentation for device setup

Supported Devices (Target)

Device	Library	Notes
OpenSC smart cards	opensc-pkcs11.so	PIV, CAC, etc.
YubiKey PIV	libykcs11.so	PIV mode
Nitrokey HSM	opensc-pkcs11.so	Via OpenSC
Nitrokey Pro/Start	opensc-pkcs11.so	OpenPGP card
SoftHSM	libsofthsm2.so	Testing

Related

• feat: challenge-response providers with KEK multi-device support #75 - Challenge-response provider abstraction (prerequisite)