Encryption keys

SpeculaPro encrypts personal data (names, phone numbers, identity numbers and similar) before it reaches the database. Someone who steals a database backup sees scrambled bytes, not your customers’ details. This protection rests on two keys that you hold.

If you lose the keys, the data is gone

Nobody can recover encrypted personal data without the key it was encrypted with. Not you, not your database administrator and not the SpeculaPro team. Store the keys and back them up separately from your database backups before you load a single real record.

The two keys

Setting	What it does	Changes?
SP_SECURITY_MASTER_KEYS	Encrypts and decrypts personal data. Can hold several numbered versions	Yes, you can add new versions (rotation)
SP_SECURITY_BLIND_INDEX_KEY	Produces searchable fingerprints (blind indexes) of values such as phone numbers, so SpeculaPro can find “every customer with this phone number” without storing the number in clear	Never

What is a blind index?

A plain fingerprint (hash) of a phone number is not safe: there are only so many phone numbers, so an attacker can fingerprint all of them and compare. A blind index mixes in your secret key first. Without the key, the fingerprints are useless to an attacker; with it, SpeculaPro can still match equal values.

One key per institution

You configure a single master key, but SpeculaPro derives a separate key for every workspace from it. One institution’s key can never decrypt another’s data, and every encrypted value is bound to the workspace and field it belongs to, so values cannot be copied from one record to another. See Data protection for the details.

More than one region

In a multi-region deployment, each cell has its own keys setting. A workspace can be moved between two cells only if the target holds every master key version of the source and the same blind-index key. Cells that must never exchange workspaces should have separate keys.

How to generate keys

speculapro keys generate

SP_SECURITY_MASTER_KEYS=1:q3J0…base64…=
SP_SECURITY_BLIND_INDEX_KEY=Zk9p…base64…=

Each key is 32 random bytes from the operating system’s secure random generator, encoded in base64. Run the command once per installation. Copy both lines straight into your secret manager; don’t paste them into chat, tickets or email.

When keys are required

SP_ENV	No keys set	Keys set
development	Starts with built-in development keys and logs a warning. These keys are in the source code, so they are public	Uses your keys
anything else	Refuses to start: SP_SECURITY_MASTER_KEYS and SP_SECURITY_BLIND_INDEX_KEY are required outside development	Uses your keys

Never promote a development database

Data written with the development keys is protected by keys anyone can read. Do not copy a development database into production, and do not run a production database with SP_ENV=development.

Key format

SP_SECURITY_MASTER_KEYS=<version>:<base64 key>[,<version>:<base64 key>…]

• version is a whole number from 1 to 255. Each version may appear only once.
• Each key must decode to exactly 32 bytes.
• The first entry is the active key. All new data is encrypted with it. The other entries are only used to read older data.
• Every encrypted value records which key version produced it, so SpeculaPro always knows which key to use.

How to store keys

Good options, from best to acceptable:

1. A secret manager: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, Google Secret Manager, or Kubernetes Secrets with encryption at rest. Inject the keys as environment variables at start-up.
2. A root-only environment file read by systemd (EnvironmentFile=/etc/speculapro/keys.env, mode 0600, owner root).

Avoid: committing keys to git (even a private repository), baking them into container images, or putting them in the same backup as the database.

How to back up keys

• Keep at least two offline copies in different locations, for example two sealed envelopes in separate safes, or two encrypted USB drives held by different officers.
• Record every master key version you have ever used. Data encrypted with an old version needs that version to be read.
• Test recovery: once a year, restore a database backup into an isolated environment using only the backed-up keys.

How to rotate the master key

Rotate on a schedule your policy sets (yearly is common), and immediately if you suspect a key has leaked.

1. Generate a new key: run speculapro keys generate and take the base64 part of the SP_SECURITY_MASTER_KEYS line.

2. Give it the next version number and put it first, keeping the old entries after it:

   # before
   SP_SECURITY_MASTER_KEYS=1:OLDKEY…=
   # after
   SP_SECURITY_MASTER_KEYS=2:NEWKEY…=,1:OLDKEY…=

3. Restart every SpeculaPro process with the new value. Restart them all: until they are, some will still write with the old key, which is harmless but delays the rotation.

4. Back up the new key (see above).

New data is now encrypted with version 2. Existing data stays readable through version 1.

Do not remove an old version

Removing 1:… from the list makes every value encrypted with it unreadable (master key v1 not configured). SpeculaPro does not yet have a command to re-encrypt existing data under the new key, so keep every version in the list for now.

The blind index key never rotates

All the stored fingerprints were made with this key. Changing it would make every existing fingerprint unmatchable: searches by phone number or ID would silently find nothing, and duplicate detection would stop working. Re-indexing tooling does not exist yet, so treat this key as permanent and protect it accordingly.

Error messages

Message	Cause
…required outside development	SP_ENV is not development and a key is missing
master key 0: want <version>:<base64>	An entry is missing the version: part
version must be 1-255	The version is 0, negative or too large
master key vN must be 32 bytes, base64	The key is truncated, has extra characters, or isn’t base64
duplicate master key version N	The same version number appears twice
blind index key must be 32 bytes, base64	The blind index key is missing or malformed. If you set master keys, you must set this too, even in development
master key vN not configured	Stored data was encrypted with a version you removed. Put it back

Related

• Configuration reference: security
• Data protection
• Production checklist