KeyPlus vaults, migration, and backups

KeyPlus 0.3 stores authentication metadata and encrypted entries together in a single file named keyplus.vault. The current working directory no longer selects the active 0.3 vault.

Default data locations

The data directory also contains keyplus.lock and a backups directory. KeyPlus currently supports one default vault and does not expose general multi-vault selection.

Automatic write protection

Before replacing an existing vault during a mutation, KeyPlus preserves the previous structurally valid encrypted envelope as backups/last-good.vault. It writes the replacement to a same-directory temporary file, flushes it, validates its envelope, and uses an atomic file replacement. On POSIX systems, the data and backup directories are set to mode 0700 and vault-related files to 0600.

An advisory lock serializes writes. A content revision check also refuses a write based on stale data from another KeyPlus process. These mechanisms reduce common data-loss risks; they do not replace independent backups or make every filesystem failure recoverable.

Manual encrypted backups

The CLI backup command and GUI Backup button copy the current encrypted vault to backups/keyplus-<UTC timestamp>.vault. A numeric suffix avoids a filename collision within the same second. Creating a backup requires an unlocked session.

CLI command backups lists the encrypted .vault files in the KeyPlus backup directory, newest filesystem modification time first, along with each file’s size and directory. The inventory is informational; restore still requires an explicit path and password.

Backups remain encrypted with the master password in use when each backup was created. Changing the active vault’s password does not rewrite older backups. Store backup copies separately from the computer when your recovery needs require protection against disk loss.

Change the master password

Use CLI command passwd or the GUI dashboard’s Change Password action. KeyPlus requires an unlocked session, verifies the current password against the vault on disk, generates a new salt, derives a new key, and atomically re-encrypts the complete document. A failed current-password check does not write the vault or invalidate the existing session.

The pre-change encrypted vault becomes last-good.vault and still requires the old password. Other existing backups likewise keep their original passwords. Changing the active password does not provide recovery for forgotten backup passwords.

Restore a backup

The CLI uses restore <path>; the GUI offers Restore Encrypted Backup on the login screen. Supply the password belonging to that backup. KeyPlus parses the envelope and requires successful authenticated decryption before installing it. If installation succeeds, the restored document becomes the unlocked session and the previous active vault is retained as last-good.vault.

A restore replaces the complete active vault. It does not merge entries. Confirm that you selected the intended file before accepting the replacement. Wrong passwords, invalid envelopes, unsupported versions, and write failures abort restoration without replacing the active vault or its unlocked document.

Migrate from 0.2

Migration requires both legacy files from the same known directory:

• auth.db: a 16-byte salt followed by a 32-byte PBKDF2 verifier;
• vault.json: the Fernet-encrypted legacy entry list.

The 0.3 migration reader verifies the old password with the legacy PBKDF2 scheme, decrypts the legacy list using its historical SHA-256/Fernet scheme, converts every valid entry, and creates a new 0.3 envelope. It validates the installed result and leaves both source files unchanged. A wrong password, invalid record, incompatible payload, or failed installation aborts migration.

KeyPlus checks only explicitly selected directories and the CLI’s current directory. This avoids scanning unrelated private files but means users must locate working-directory-based 0.2 vaults themselves.