Before you start
KeySigner macOS test build with local key file commands and KeePassXC 2.8.0
- Use a disposable KeePassXC database with a password, an empty KeySigner key file store in a separate test setup, and private local folders for the XML key file and encrypted backup.
- Check the KeePassXC version
Data and access
Create a test key file
Open your test KeySigner vault on the Mac. In Terminal, list the key files. Replace REVISION with the revision in that response to create a key file labeled for your test database.
keysigner authenticator keyfile-list --json keysigner authenticator keyfile-create 'Recovery test' 'test.kdbx' REVISION --jsonCheck. The create response contains the key file ID and a new revision. Use both for the next command.
Add the file to the test database
Replace KEY_FILE_ID and REVISION with the values from the create response to save the XML file to a new path in a private local folder. In KeePassXC, keep the database password and add this file under Database Settings, Security. Lock the database and check that the password and file together open it. Clear the key file selection and check that the password alone is rejected.
keysigner authenticator keyfile-deliver KEY_FILE_ID REVISION ./test.keyx reusable-copyCheck. Open the same test entry with the password and the new file. After locking, check that KeePassXC rejects the password alone.
Back up the KeySigner key files
Run the backup command from a private local folder and enter a separate backup passphrase at the hidden prompt. Keep the encrypted backup and its passphrase available for the rehearsal. Keep the test database and original key file until you confirm recovery.
keysigner authenticator keyfile-backup ./key-file-backup.ageCheck. Find the encrypted backup at the path you gave the command before continuing to the separate vault.
Restore in a separate test vault
Open an empty KeySigner key file store in a separate test setup. Copy the encrypted backup there and preview it using the backup passphrase. Match the key file label. Replace REVIEW_HASH and REVISION with the review hash and destination revision from the preview before applying it.
keysigner authenticator keyfile-backup-review ./key-file-backup.age --json keysigner authenticator keyfile-backup-restore ./key-file-backup.age REVIEW_HASH REVISION --jsonCheck. The preview shows the expected label. After applying it, use the restore response for the ID and revision in the next step.
Open the database with the recovered file
Replace KEY_FILE_ID and REVISION with the values from the restore response to deliver the restored file to a new private path. Open the test database in KeePassXC with its password and the restored file.
keysigner authenticator keyfile-deliver KEY_FILE_ID REVISION ./restored.keyx reusable-copyCheck. Confirm the database opens to the same test entry. An unrelated file should fail even with the correct database password.
Check your result
Check that the recovered file and the database password open the same test entry. Each delivered file is a reusable copy of the same factor and works while KeySigner is locked. KeySigner cannot revoke a copy. If you lose control of one, replace the key file in KeePassXC and check that the old file no longer opens the updated database.
What we tested
Tested on . KeePassXC 2.8.0 opened a local test database with the generated key file and then with the file restored from backup. It rejected a missing or wrong key file and an incorrect database password. A delivered copy also opened the database while KeySigner was locked.
If you get stuck
KeySigner refuses the backup review
Confirm the destination key file store is empty and the backup is a KeySigner key file backup. Preview again in the intended destination if you switched test setups or the revision changed.