KeePassRecoveryTool is a specialized command-line utility designed for users who have lost or damaged their YubiKey Hardware Key (Challenge-Response) but still possess the original 20-byte Seed. It allows for the recovery of KeePass databases (.kdbx) by simulating the hardware response and subsequently removing the hardware key requirement.

Many KeePass users employ YubiKey's Challenge-Response (C-R) mode as a robust second factor. However, if the YubiKey is lost or malfunctions without a physical backup, the database becomes inaccessible even with the correct master password.

KeePassRecoveryTool enables you to:

1. Simulate the YubiKey's HMAC-SHA1 response using your original 20-byte Seed.
2. Decrypt KDBX 3.x or 4.x databases.
3. Re-save the database with Master Password protection only, effectively removing the dependency on the hardware key.

• Multi-Version Support: Fully compatible with both KDBX 3.x (Legacy) and KDBX 4.x (Modern).
• Hardware Decoupling: Once processed, the output database can be opened with just the master password on any KeePass client.
• HMAC-SHA1 Simulation: Accurately reproduces the YubiKey Slot 2 HMAC-SHA1 Challenge-Response logic.
• Portable Implementation: Built with pure Java/Kotlin, ensuring cross-platform compatibility without native hardware drivers.

• Java JDK 17 or higher.
• Gradle (Optional, project includes Gradle Wrapper).

Build the executable Shadow Jar using Gradle:

./gradlew shadowJar

After the build, the executable will be found at build/libs/KeePassRecoveryTool-1.0-SNAPSHOT-all.jar.

To run the tool, provide the input file, output path, master password, and the 20-byte hex-encoded Seed.

java -jar KeePassRecoveryTool-all.jar <input.kdbx> <output.kdbx> -p <password> -s <hex_seed>

• <input.kdbx>: Path to the original hardware-protected KeePass database.
• <output.kdbx>: Path where the recovered (hardware-key-removed) database will be saved.
• -p, --pass: Your KeePass master password.
• -s, --seed: Critical. The 20-byte Seed as a Hex string (40 characters).

java -jar KeePassRecoveryTool-all.jar my_vault.kdbx recovered.kdbx -p "MySecretPassword123" -s "0123456789abcdef0123456789abcdef01234567"

1. Challenge Extraction: The tool parses the KDBX header. For KDBX 4, it extracts the S salt from KDF Parameters; for KDBX 3, it uses the Transform Seed.
2. Response Calculation: It computes the expected 20-byte response using the HMAC-SHA1 algorithm with your provided Seed and the extracted Challenge.
3. Database Decryption: It attempts to unlock the KDBX file using the combination of the password and the simulated response.
4. Re-encryption: It saves the decrypted content back to a new file, stripping the hardware key requirement and using only the master password for encryption.

This project is made possible by the following open-source libraries:

• Kotpass: An excellent Kotlin-based parser and editor for KeePass databases.
• Bouncy Castle: For robust cryptographic implementations in Java.
• Picocli: A powerful framework for creating command-line applications.
• Okio: For efficient I/O and byte manipulation.
• SLF4J: Simple Logging Facade for Java.

Distributed under the MIT License.