Encryption protects the sensitive secrets OptimiDoc stores — connector and mailbox passwords, OAuth tokens, certificates, and scan-destination connection details — by encrypting them at rest with AES-256. The Encryption page is where administrators check encryption status, manage and rotate the encryption keys, safeguard a recovery key for disaster recovery, and optionally encrypt the print and scan files held on disk.
How OptimiDoc Encryption Works
OptimiDoc uses a two-tier key hierarchy so that keys can be rotated and recovered without re-encrypting everything by hand.
-
Master Encryption Key (MEK). A single AES-256 key for the server, protected by Windows DPAPI scoped to the local machine. Because DPAPI is machine-bound, the stored MEK can only be unwrapped on the same server that created it — which is exactly why the recovery key described below matters when hardware changes.
-
Data Encryption Keys (DEK). One or more versioned AES-256 keys, each wrapped (encrypted) by the MEK and stored in the database. The active DEK encrypts new values; older versions are kept so existing values remain readable. New DEKs use AES-256-GCM, an authenticated cipher that also detects tampering.
What is encrypted
Encryption is applied automatically by the database layer whenever a record is saved — administrators never encrypt values by hand:
-
Credential values — passwords, OAuth tokens, and certificates stored for print connectors, mailboxes, and authentication.
-
Destination connection strings — the secrets inside scan-destination configuration.
Encryption is field-level: within a connection string, only the sensitive fields (passwords, tokens, keys) are encrypted, while non-secret settings such as host names and folder paths remain readable for support and diagnostics. Encrypted values are tagged with an ENC: marker and a key version; any value without the marker is treated as plaintext, so the system stays backward-compatible with data written before encryption was enabled.
Automatic upgrade to AES-GCM
Earlier builds used AES-CBC. On upgrade, OptimiDoc automatically adds a new AES-GCM key and makes it active, while retaining the older CBC keys read-only so existing values can still be decrypted. New writes are always AES-GCM. Running Re-encrypt All Data (below) migrates the remaining legacy values across to the new key.
Accessing the Encryption Page
-
Log in to the OptimiDoc web interface as an administrator.
-
Navigate to Diagnostics > Encryption in the left sidebar.
Encryption Status
The Encryption Status card summarises the current state of the encryption system:
|
Field |
Description |
|---|---|
|
Initialized |
Whether the encryption service has started and loaded its keys. Most actions are disabled until this is Yes. |
|
Recovery Record |
Whether a recovery record exists in the database. This is created the first time you download the recovery key. |
|
Active Key Version |
The version number of the DEK currently used for new encryption. |
|
Total Key Versions |
How many DEK versions exist (active plus retained older versions). |
File Encryption
By default OptimiDoc encrypts stored secrets (above) but not the document files themselves. The File Encryption card adds encryption for the print jobs and scanned documents held on disk.
-
Toggle Encrypt files at rest on to encrypt newly created files.
-
Existing files remain readable — the setting is not retroactive.
Enable this where spooled documents may contain sensitive content and the storage volume is not otherwise encrypted.
Key Management
The Key Management card holds three actions.
1. Rotate Data Encryption Key
Creates a new DEK version and makes it the active key. Data already written with previous versions stays readable, because the older keys are retained. Rotate keys periodically in line with your security policy, or after any suspected exposure. To move existing data onto the new key, follow rotation with Re-encrypt All Data.
2. Download Recovery Key
Downloads a recovery key file (.odrk) that lets you restore the MEK on a new or rebuilt server, where DPAPI can no longer unwrap the original MEK. The recovery key is derived from your licence and the server's hardware identifier, and the file is integrity-protected so a corrupted or tampered file is rejected on import.
-
The first download also creates the recovery record in the database (the MEK, re-wrapped so the recovery key can unlock it).
-
An activated licence is required to generate the file.
-
You can download the file again at any time.
Store the .odrk file securely and offline. Without it — and without the original server — encrypted data cannot be recovered.
3. Export Encryption Keys
Exports all encryption key records from the database as a JSON file. This is a convenience backup of the (wrapped) key material to keep alongside your database backups before major maintenance. Store it as securely as the recovery key.
Re-encrypt All Data
The Data Encryption card provides Re-encrypt All Data. It re-saves every encryptable destination connection string and credential so that each value is re-written with the active key. Use it to:
-
encrypt values that predate encryption being enabled, and
-
migrate values off older (including legacy AES-CBC) key versions after a rotation.
The operation is safe to re-run and reports how many destinations and credentials were processed and how many were skipped (records that are not of an encryptable type). Run it once after first enabling encryption, and again after each key rotation.
Disaster Recovery
Because the MEK is bound to the machine via DPAPI, moving OptimiDoc to new hardware or restoring onto a fresh server leaves the copied MEK unusable — the server cannot decrypt secrets and admin log-in will fail. This is what the recovery key is for.
-
Browse to the public recovery page at
/recover-encryption(reachable without logging in). -
Upload your .odrk recovery key file.
-
OptimiDoc verifies the file, uses it to unlock the MEK from the database recovery record, re-protects the MEK under the new machine's DPAPI, and reloads the data keys.
-
Log in normally — encrypted data is readable again.
This is why downloading and safeguarding the recovery key immediately after enabling encryption is essential: it is the only way back after a hardware change if the cluster is unavailable.
Encryption in a Cluster
In a multi-node deployment every node needs the same MEK. A freshly added node starts with no MEK, so it cannot decrypt the admin password to log in or call the standard, admin-authorised key-exchange endpoint. OptimiDoc resolves this with a cluster bootstrap: the new node authenticates to the master over the cluster's IP-whitelisted internal channel, the master validates it and releases the MEK, and the new node then stores the MEK under its own DPAPI and loads the data keys. From that point the node participates like any other. See Cluster Nodes for the node lifecycle.
In Summary
OptimiDoc encrypts stored secrets automatically with a versioned, rotatable AES-256 key hierarchy, protected on each server by Windows DPAPI. As an administrator your responsibilities are light but important: after enabling encryption, run Re-encrypt All Data to bring existing values in, download the recovery key and store it offline, and keep your licence details safe (the recovery key derives from them). Rotate keys per your security policy, and remember that the recovery key — not the server — is what makes disaster recovery possible.
Related articles