Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

09.02 Enabling Encryption

Activate the Encryption Extra to begin encrypting sensitive fields at rest. Activation generates the master key (init.php), creates a one-time unencrypted backup, and migrates existing plaintext data to ciphertext in place. Plan as a maintenance event; back up the master key file immediately after activation; delete the unencrypted backup file after verification.

Requires: Encryption Extra

Activation generates the per-install master key, encrypts existing data, and modifies the schema. The Extra is at simplerisk/extras/encryption/. See The Encryption Extra Overview for what the Extra does and why before reading the activation procedure.

Why this matters

Activation is when encryption-at-rest actually starts protecting data. Before activation, every sensitive field is plaintext in the database; after activation, the same fields are AES-256-CBC ciphertext. The activation operation is irreversible without recovery effort, time-consuming on large installs, and produces an unencrypted backup file you have to clean up. Getting the operation right matters; getting it wrong leaves the install in a half-encrypted state that's painful to recover from.

This article covers the activation procedure end-to-end. Read The Encryption Extra Overview first if you haven't decided whether to activate.

Before you start

Have these in hand:

  • Admin access to Configure → Extras → Encryption Extra.
  • A confirmed maintenance window. Activation takes minutes for typical installs, longer for large databases (10,000+ risks plus assets, frameworks, etc.). Plan accordingly; users will see degraded or unavailable application during the migration.
  • A current full database backup, taken immediately before activation. The Extra creates its own activation-time backup, but having a separate fresh backup is belt-and-suspenders. See Database Backup and Restore.
  • Verified PHP OpenSSL extension. The Extra requires openssl (legacy mcrypt is deprecated). Check via php -m | grep openssl.
  • Disk space for the unencrypted backup file (the activation creates a SQL dump in /tmp/). Confirm /tmp/ has enough free space — at minimum your full database size.
  • A secure off-server location for backing up the master key file (e.g., a sealed envelope in a safe; a HashiCorp Vault entry; an encrypted entry in a corporate password manager). Plan this before activation; back up the file immediately after.
  • For multi-server deployments: a deployment plan to copy the master key file to every app server.

Step-by-step

1. Decide on activation timing

Coordinate with users:

  • Pre-announce: notify users that the application will be unavailable during the maintenance window.
  • Pick a low-traffic time: typically off-hours or weekend; the migration should not run while users are actively submitting risks (uncommitted writes during migration can produce inconsistent encryption state).
  • Have a rollback plan: if activation fails partway, the path is to restore from the pre-activation backup. Test the restore procedure in non-production before committing in production.

2. Create a fresh backup before activation

Don't rely on the Extra's activation-time backup as your only safety net:

  1. Take a fresh full database backup using your standard procedure (mysqldump, MySQL Enterprise Backup, etc.).
  2. Verify the backup is restorable in a non-production environment.
  3. Store the backup in your standard backup location.

3. Verify prerequisites

# Confirm OpenSSL is available
php -m | grep -i openssl

# Confirm /tmp has enough space (at least your DB size)
df -h /tmp

# Confirm the SimpleRisk PHP process can write to /tmp
ls -ld /tmp

If any of these fail, fix before proceeding.

4. Activate the Extra

Sidebar: Configure → Extras → Encryption Extra → Activate (the Extra may also be labeled Encrypted Database Extra). The activation:

  1. Verifies OpenSSL is available; aborts with an error if not.
  2. Creates an unencrypted database backup at /tmp/simplerisk-unencrypted_backup-YYYY-MM-DD--HH-MM-SS.sql.
  3. Generates the 256-bit master key with openssl_random_pseudo_bytes(32).
  4. Base64-encodes the key and writes it to simplerisk/extras/encryption/includes/init.php as define('ENCODED_KEY', ' '); .
  5. Iterates the encryptable fields (~30 fields across the schema) and encrypts each row's value in place.
  6. Creates the encrypted_fields tracking table to record which fields are encrypted.
  7. Runs schema migrations to add sort-order helper columns (order_by_subject, order_by_name) for fields where sorting is needed without decrypting every row at query time.
  8. Sets the Extra-active flag.

The activation runs with max_execution_time = 0 (no PHP timeout) because it can take meaningful time on large installs.

Wait for the activation to complete. The page typically shows a progress indicator or status message; don't leave the page.

5. Immediately back up the master key file

This is the most important post-activation step. The master key at simplerisk/extras/encryption/includes/init.php is the only copy. Lose it and your encrypted data is unrecoverable.

# Copy to a secure off-server location
scp /var/www/simplerisk/extras/encryption/includes/init.php \
    secure-vault@vault.internal:/secure/simplerisk/
  
   /init.php # Or upload to your secrets manager vault kv put secret/simplerisk/
   
    /encryption-key \ init_php=@/var/www/simplerisk/extras/encryption/includes/init.php

Patterns:

  • HashiCorp Vault, AWS Secrets Manager, Azure Key Vault — store the file content as a secret.
  • Corporate password manager (1Password, Bitwarden, etc.) — store the file content as a secure note.
  • Sealed envelope in a physical safe — for highly-regulated programs.

The backup must be:

  • Off the SimpleRisk server: a backup on the same disk as the original is no protection against disk failure.
  • Access-controlled: restrict to operators authorized to recover the install.
  • Auditable: log who accessed the backup and when, so you can detect unauthorized access.

6. Delete the activation-time unencrypted backup

The /tmp/simplerisk-unencrypted_backup-YYYY-MM-DD--HH-MM-SS.sql file is plaintext — every encrypted field is in the clear. Once you've verified the activation succeeded:

  1. Verify the install works (next step).
  2. Delete the backup file: rm /tmp/simplerisk-unencrypted_backup-*.sql.
  3. Confirm deletion: ls /tmp/simplerisk-unencrypted_backup-*.sql should report no matches.

The Extra's UI may also expose a "Delete Unencrypted Backup" button after activation; either path works.

7. Verify the install works

Test that everything's still operational:

  1. Log in as a non-admin test user.
  2. Browse the risk register; confirm the risks display with decrypted content (subjects, descriptions all readable).
  3. Open a risk; confirm the details (description, mitigation, etc.) are readable.
  4. Submit a new risk; confirm it saves and re-opens correctly (round-trip encryption test).
  5. Open the audit trail for a risk; confirm log messages are readable.
  6. Run a report (e.g., the Dynamic Risk Report); confirm risk subjects appear.

If any data appears as encrypted ciphertext (a long base64 blob instead of readable text), the encryption layer isn't decrypting correctly. Possible causes: master key file is wrong / missing on the server handling the request; a record's encryption was corrupted during migration. Investigate.

8. Multi-server deployment: distribute the key

If your SimpleRisk runs on multiple app servers behind a load balancer:

  1. Copy simplerisk/extras/encryption/includes/init.php from the activation server to every other app server.
  2. Verify each server's file matches (e.g., compare hashes).
  3. Test by hitting each server directly (bypass the load balancer) and confirming encrypted data displays.

The key file is configuration, not application code. Don't bake it into the deployment image; deploy as a runtime secret like any other credential.

9. Update operational documentation

After activation, document:

  • Where the master key backup is stored and how to retrieve it.
  • The deactivation procedure (in case you ever need to undo).
  • The recovery procedure for "we lost a server and need to restore from backup."
  • The key-file deployment procedure for new servers added to the cluster.

This documentation prevents the inevitable "what's our process if this server dies?" question from becoming an emergency.

10. Plan for ongoing operations

Encryption is on; sensitive data at rest is protected. Subsequent operational considerations:

  • Backups: standard backup procedures continue to work; backups now contain encrypted data, which is fine for storage but means restoring requires the matching master key.
  • Upgrades: SimpleRisk upgrades preserve the encryption (the master key file isn't touched). Verify after each upgrade by checking that data still displays correctly.
  • New encrypted fields: future SimpleRisk versions may add new fields to the encryption set. The Extra's activation function is re-run on each upgrade (idempotently) to encrypt newly-encryptable fields.
  • Key rotation: not natively supported as a single operation; see Key Management and Rotation.

Common pitfalls

A handful of patterns recur with activation.

  • Activating without a backup of the master key. The single most common failure mode. Back up immediately after activation.

  • Activating without a fresh database backup. Activation modifies every encryptable field; a botched activation that doesn't roll back leaves the install in a state that needs manual recovery. The fresh backup is the recovery path.

  • Activating on production without testing in non-production first. The procedure is mechanical but not trivial; testing in non-production catches OpenSSL configuration issues, disk-space issues, and timing assumptions before they affect users.

  • Leaving the unencrypted backup in /tmp/ indefinitely. It's plaintext and sensitive. Delete after verification.

  • Not coordinating with the multi-server deployment process. Forgotten app servers without the key file produce inconsistent behavior — some users see decrypted data, others see ciphertext. Confirm every server has the key.

  • Storing the master key file in source control. Don't. Manage as a secret.

  • Activating during business hours. Migration time can be substantial; the application is effectively down during it. Schedule a maintenance window.

  • Not verifying OpenSSL before activating. Activation aborts if OpenSSL isn't available, but discovering that mid-window costs time. Check first.

  • Skipping the post-activation verification step. A successful-looking activation might still have produced corrupted data. Verify with real reads before considering the operation done.

  • Treating the Extra's activation as the only thing protecting the data. Encryption-at-rest is one layer; web-server hardening, OS security, network segmentation, monitoring all matter too. See the rest of this chapter and Securing the Database.

Related

Reference

  • Permission required: check_admin for the Extras page and the activation flow.
  • API endpoint(s): None specific to activation; activation is a UI-driven operation.
  • Implementing files: simplerisk/extras/encryption/index.php (enable_encryption_extra(), the activation logic); simplerisk/extras/encryption/includes/encryption.php (encrypt(), decrypt() runtime functions); simplerisk/extras/encryption/includes/init.php (the master key, generated at activation).
  • Database tables: encrypted_fields (tracks which fields are encrypted). The Extra modifies the schema of existing tables to widen text columns (encrypted ciphertext is longer than plaintext).
  • config_settings keys: encryption (Extra activation flag).
  • Activation backup: /tmp/simplerisk-unencrypted_backup-YYYY-MM-DD--HH-MM-SS.sql — created automatically; delete after verification.
  • External dependencies: PHP openssl extension; /tmp/ writable with sufficient free space; for multi-server deployments, the ability to deploy the init.php file to all app servers.