09.03 Key Management and Rotation

Requires: Encryption Extra

The master key, the deactivation flow, and the backup-restore semantics described here all live in the Encryption Extra at simplerisk/extras/encryption/.

Why this matters

The master key file is the single most important secret in an encryption-activated SimpleRisk install. Lose it and your encrypted data is permanently inaccessible — there's no recovery, no key escrow, no Anthropic-side intervention. Mishandle it and you face the operational equivalent of "the database is fine but we can't read it." Get key management right and the encryption layer pays back the activation effort; get it wrong and you've added a single point of failure with no recovery path.

This article covers the operational discipline: where the key lives, how to back it up, when to rotate, what happens during deactivation, and how to handle the operational events (disk loss, server migration, key compromise) that affect the key.

Where the master key lives

After activation, the master key is at:

simplerisk/extras/encryption/includes/init.php

Format: a single PHP file with one define() line:

  ');

Filesystem properties:

• Owner: typically the web server user (www-data, apache, nginx, depending on distribution).
• Permissions: should be readable only by the owner — 0640 or 0600.
• Verify: ls -la simplerisk/extras/encryption/includes/init.php.

If the file is world-readable (0644 or worse), tighten the permissions:

chmod 0640 /var/www/simplerisk/extras/encryption/includes/init.php
chown www-data:www-data /var/www/simplerisk/extras/encryption/includes/init.php

The web server's PHP process needs read access; nothing else does.

Backing up the master key

The master key file backup is the single most critical operational task in an encryption-activated install.

Why off-server backup is mandatory

A backup of the key file on the same server doesn't help in:

• Disk failure that takes both the original file and the backup with it.
• Server-level compromise where the attacker has the same access to the backup as the original.
• Server replacement where the backup goes with the decommissioned hardware.

The backup must be:

• Off the SimpleRisk server: another server, a secrets manager, a physical safe.
• Access-controlled: only authorized operators can retrieve it.
• Auditable: access is logged and reviewable.

Where to store the backup

Pick one (or more for defense in depth):

• Secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager). Store the file content as a secret. Programmatic retrieval is easy; access is auditable.
• Corporate password manager (1Password Business, Bitwarden Business, Keeper). Store as a secure note. Manual retrieval; appropriate for small operator teams.
• Sealed envelope in a physical safe. For highly-regulated programs or as a final-fallback. Hard to access casually, which is the point.
• Encrypted backup file on a separate server you control. The backup file itself encrypted with a key managed separately.

For most programs, a secrets manager plus a password manager covers both programmatic retrieval and human recovery.

What to back up

The full content of init.php:

# Read the file
cat /var/www/simplerisk/extras/encryption/includes/init.php

# Or just the key:
grep ENCODED_KEY /var/www/simplerisk/extras/encryption/includes/init.php

Some operators prefer to back up just the key value (the base64 string) rather than the whole file. Either works for recovery; the file is small (a few hundred bytes) so backing up the whole file is the simpler pattern.

Backup procedure

# 1. Copy to an off-server location (HashiCorp Vault example)
vault kv put secret/simplerisk/
  
   /encryption-key \ init_php=@/var/www/simplerisk/extras/encryption/includes/init.php # 2. Verify the backup vault kv get -field=init_php secret/simplerisk/
   
    /encryption-key | diff - /var/www/simplerisk/extras/encryption/includes/init.php # 3. (Optional) Document the location in your operations runbook 
   
  

Recovery procedure

If you lose the original init.php (server failure, accidental deletion, etc.):

# 1. Retrieve from backup
vault kv get -field=init_php secret/simplerisk/
  
   /encryption-key > /tmp/init.php # 2. Restore to the original location sudo cp /tmp/init.php /var/www/simplerisk/extras/encryption/includes/init.php sudo chown www-data:www-data /var/www/simplerisk/extras/encryption/includes/init.php sudo chmod 0640 /var/www/simplerisk/extras/encryption/includes/init.php # 3. Restart the web server / clear PHP opcache sudo systemctl restart php8.3-fpm sudo systemctl restart nginx 
  

Verify by hitting the application: encrypted data should display correctly.

Key rotation

Native key rotation is not supported as a single operation. There's no "rotate to new key while preserving access" path.

The workaround when you genuinely need to rotate (suspected key compromise, regulatory requirement for periodic rotation):

1. Deactivate the Encryption Extra — decrypts all encrypted data in place using the current master key.
2. Verify all data is now plaintext and accessible.
3. Delete the old master key file.
4. Re-activate the Extra — generates a new master key, re-encrypts the data with the new key.
5. Back up the new master key off-server.
6. Update any clones (multi-server deployments) with the new key.

This is expensive: it's two full data migrations (decrypt then re-encrypt), each taking the same time as the original activation. It also leaves the data plaintext in between, which may itself be a regulatory issue. Schedule as a substantial maintenance event.

For programs where periodic key rotation is non-negotiable: weigh the operational cost against the security benefit. NIST SP 800-57 generally recommends rotation but acknowledges that for symmetric data-encryption keys protecting at-rest data, rotation periods can be longer than for transport keys (often years). Most programs running the Encryption Extra rotate only on suspected compromise rather than on a fixed cadence.

When the user changes their password

User password changes have no impact on the encryption key. The master key is per-install, not per-user, and isn't derived from any user credential. A user who changes their password continues to have the same access to encrypted data as before; the encryption key isn't affected.

This is different from password-derived encryption schemes (some applications use the user's password as a key, requiring re-encryption on password change). The Encryption Extra doesn't work that way.

Disabling encryption

When you deactivate the Encryption Extra:

1. The Extra reads each encrypted field, decrypts using the current master key, and writes the plaintext back.
2. The schema reverts to original column types where they were widened to accommodate ciphertext.
3. The Extra-active flag is cleared.
4. The init.php file may persist on disk (depending on the Extra version's deactivation behavior) but is no longer used.

After deactivation:

• All data is plaintext at rest again.
• Backups are plaintext.
• The application no longer needs the master key to function.
• Reactivating later generates a new master key (the old one isn't reused).

Deactivation is a one-way operation in the same sense activation is — time-consuming, requires a maintenance window. Plan accordingly.

What happens if you lose the master key

If the master key is gone (file deleted with no backup, server destroyed with no backup):

• Encrypted fields in the database are permanently inaccessible.
• The application can't decrypt; reads of encrypted fields produce errors.
• Backups taken after activation are useless without the key.
• There is no recovery path.

This is the worst-case scenario for the Encryption Extra. It's why the off-server key backup is non-negotiable.

If you find yourself in this scenario:

1. Restore from a backup taken before activation, if you have one. You'll lose any data created between the backup and activation, but the data you do recover will be plaintext.
2. Accept the data loss and start fresh.

There's no third option.

Compromised key scenarios

If you suspect the master key has been compromised (an attacker had access to the file; the file was leaked; an admin who shouldn't have access read it):

1. Treat as an incident. The encrypted data may have been decrypted offline using the leaked key.
2. Rotate the key via the deactivate-and-reactivate workflow above.
3. Audit access: review who had access to the original key file and the timeline.
4. Consider notification obligations: if the encrypted data included regulated content (PHI, PII), breach notification requirements may apply even if you can't confirm decryption occurred.

The new key protects future data; the old key may have already been used to decrypt past data. Rotation prevents continued exposure but doesn't undo prior compromise.

Multi-server deployments

For SimpleRisk running on multiple app servers:

• Every app server needs the same master key file at simplerisk/extras/encryption/includes/init.php.
• Deploy the file as a secret, not as application code. Configuration management tools (Ansible, Puppet, Chef, Terraform) typically have a "secret file" pattern; use it.
• Rotate the file across all servers atomically if you ever do rotate. Mismatched keys across servers produce inconsistent behavior — some users see plaintext, others see ciphertext, depending on which server handled their request.

For container-based deployments (Docker, Kubernetes), the master key is a secret resource, not a configuration map; mount it as a file inside each container at the expected path.

Common pitfalls

A handful of patterns recur with key management.

• Storing the master key in source control. Don't. The file contains the key; checking it into Git puts the key in everyone's checkout, every backup of every clone, every CI pipeline log.

• Backing up the master key to the same disk as the original. Disk failure takes both. Off-server.

• Confusing the master key with the user's API key. They're different. The master key encrypts data at rest; API keys authenticate API requests. They have different lifecycles and different recovery procedures.

• Treating key rotation as a routine operation. It's expensive — two full migrations per rotation. Most programs don't rotate routinely.

• Forgetting that deactivation decrypts in place. Deactivating the Extra and then taking a backup gives you plaintext backups (the data is plaintext after deactivation). If your reason for activating is "we need encrypted backups," remember that deactivation undoes that.

• Not coordinating key rotation with the multi-server deployment. Rotation that updates one server but not others produces inconsistent application behavior. Rotate all servers in the same window.

• Storing the key backup in the same secrets-manager namespace as other lower-sensitivity secrets. The encryption key is the most sensitive credential; it deserves a separate access-control namespace.

• Not testing the recovery procedure. Practice retrieving the key from backup and restoring to a non-production server before you need to do it for real.

• Treating the Extra as the only data-protection layer. Encryption-at-rest is one defense layer; access control, network segmentation, monitoring, and incident response are independent layers that all need to work.

• Disabling encryption "temporarily" for an upgrade or migration. Don't. The data goes plaintext during the deactivation; if the operation gets interrupted or the rebuild fails, you've now exposed the data unnecessarily. Plan upgrades and migrations to keep encryption active throughout.

Related

• The Encryption Extra Overview
• Enabling Encryption
• Securing the Database
• Securing the Web Server
• Database Backup and Restore

Reference

• Master key location: simplerisk/extras/encryption/includes/init.php — single file with one define('ENCODED_KEY', ' '); line.
• Filesystem permissions: 0640 or 0600, owned by the web server user.
• Algorithm: AES-256-CBC with HMAC-SHA256 authentication. Single 256-bit key from openssl_random_pseudo_bytes(32), base64-encoded.
• Key rotation: Not natively supported. Workaround: deactivate (which decrypts everything), then re-activate (which generates a new key and re-encrypts). Expensive.
• Backup recommendation: Immediately after activation. Off-server location (secrets manager, password manager, physical safe).
• Loss = data unrecoverable: Yes. There is no recovery service.
• User password impact: None. The master key isn't password-derived.
• Multi-server deployment: The master key file must be present on every app server with the same content.
• Implementing files: simplerisk/extras/encryption/index.php (Extra activation/deactivation); simplerisk/extras/encryption/includes/encryption.php (encrypt(), decrypt()); simplerisk/extras/encryption/includes/init.php (the key).
• External dependencies: PHP openssl extension; an off-server location for the key backup; for multi-server, configuration management to deploy the key file.