Black Candle Wiki / Identity backup & key rotation
Identity backup & key rotation
Black Candle Wiki / Identity backup
There is no password reset in Courier. Your seed is your identity — back it up, or lose it forever.
Create an encrypted backup
Backup
courier backup create --output backup.json --device-name my-laptop
You’ll be prompted for a passphrase (minimum 8 characters, no-echo prompt, confirmation required). The backup seals your identity seed and live encryption keys with scrypt + NaCl secretbox. Store backup.json somewhere the passphrase isn’t — a USB stick, a password manager, printed in a safe.
Restore on a new machine
Restore
courier backup restore backup.json
Enter the passphrase and the backup becomes this machine’s identity — same address, same keys. Your contacts keep reaching you at the same address; nothing changes on their end.
Sync a second device
Multi-device sync
courier backup export-sync --output sync.json # on device A
courier backup import-sync sync.json # on device B
Sync envelopes use the same encrypted format as backups but merge the live key material into the second device’s identity instead of replacing it. Move sync.json between machines however you like — without the passphrase it’s opaque.
Rotate your encryption keys
Rotation
courier rotate
Rotation generates a fresh X25519 encryption key and announces it to the relay — your address doesn’t change (the address is your Ed25519 identity key, which stays put). Old keys are retained briefly so in-flight messages still decrypt, then dropped. Rotate periodically, or immediately if you suspect a key leaked.
Rules of thumb
- Back up before you need it — right after
courier init. - Keep the passphrase and the backup file in different places.
- Test a restore on a scratch machine once, so you trust the process.
- Rotate keys after any incident, and on a schedule if you’re cautious.
Next steps
Security model — what the backup actually protects.
Troubleshooting — “I lost my seed” and other bad days.