Master Key Backup
How to securely back up your MASTER_KEY — losing it means permanent, unrecoverable loss of all encrypted wills.
Master Key Backup
If you lose your MASTER_KEY, all encrypted wills are permanently unrecoverable. There is no reset, no recovery, no backdoor. This is by design.
Why This Matters
BAP encrypts every will's Data Encryption Key (DEK) using the MASTER_KEY. Without it:
- No will can be decrypted
- No Survivor can access documents
- The Will Transfer Protocol cannot complete
- Data is permanently lost
Backup Procedure
Step 1: Generate and Record
When you first set up BAP, you generated the key:
openssl rand -hex 32This produced a 64-character hex string. You must store this in at least two physically separate locations.
Step 2: Choose Backup Locations
Use at least two of these methods:
| Method | Security | Accessibility | Cost |
|---|---|---|---|
| Password manager (Bitwarden, 1Password) | High | Easy | Free-$36/yr |
| Encrypted USB drive (LUKS/VeraCrypt) | High | Medium | $10-20 |
| Paper copy in fireproof safe | Medium | Low | $50-200 |
| Bank safe deposit box | High | Low | $30-100/yr |
| Trusted family member (sealed envelope) | Medium | Low | Free |
Step 3: Verify the Backup
After storing the key:
- Do not rely on memory. Write it down or copy it digitally.
- Test recovery: On a separate machine, set the
MASTER_KEYenvironment variable to your backed-up value and verify the API starts and can decrypt a test will. - Document the backup location — if you are hit by a bus, someone needs to know where the key is stored.
If you use BAP to protect your own digital estate, the irony of losing the MASTER_KEY would be painful. Your Survivors cannot access wills if the server operator (you) loses this key.
Step 4: Rotation (Optional)
If you suspect the key has been compromised:
- Generate a new key:
openssl rand -hex 32 - Before changing the key, decrypt and re-encrypt all existing wills (this requires a migration script — see the API documentation)
- Update the environment variable in your deployment
- Update all backup locations
Key rotation is not currently automated. A future release will include a bap rotate-master-key CLI command.
Environment Variable Backup
Beyond MASTER_KEY, back up these critical values too:
| Variable | Impact if Lost |
|---|---|
MASTER_KEY | All wills unrecoverable |
JWT_SECRET | All sessions invalidated (users must re-login) |
WILL_SIGNING_PRIVATE_KEY | Cannot verify will integrity (if signing enabled) |
POSTGRES_PASSWORD | Cannot connect to database |
Self-Hosted Operators
If you run BAP self-hosted, you are the sole custodian of the MASTER_KEY. Consider:
- Adding the key to your own BAP will (yes, recursive — but it works if a Survivor can access it)
- Sharing the backup location with a trusted person
- Documenting the recovery procedure alongside your server access credentials
SaaS Operators
If you operate BAP as a SaaS, the MASTER_KEY protects all tenants' data. Use enterprise-grade secret management:
- AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault
- Enable key versioning and audit logging
- Restrict access to the minimum number of people
- Test disaster recovery quarterly