At-Rest Secret Encryption

Signotaur stores a number of sensitive values (passwords, secrets and private-key passphrases) that it needs at runtime but must never expose in plaintext on disk. This page explains how those secrets are protected at rest and what changes in version 2. It also covers how the protection is tied to the machine it was created on, and how to recover or migrate when something goes wrong.

What At-Rest Encryption Protects

Every secret Signotaur persists is encrypted with a single AES master key (and initialization vector). The following values are all protected this way:

  • The AES master key and vector themselves (see below).
  • OAuth client secrets (Google and GitHub).
  • The SMTP / email account password.
  • The ADCS account password.
  • Web-certificate PFX passwords.
  • The internal CA .pwd files (each is AES-encrypted under the master key).
  • The backup encryption passphrase used for scheduled .sigbak archives.

The Version 2 Sealing Model

In earlier versions, the AES master key and vector lived in plaintext in the Signotaur.Server.config.json configuration file. Anyone who copied the data folder held the key to every secret in it.

In version 2, the master key and vector are themselves sealed with DPAPI at machine scope (DataProtectionScope.LocalMachine). The plaintext key and vector no longer rest on disk; only the DPAPI-sealed form does, and only that specific machine can unseal it.

Key points:

  • Sealed once, automatically. The first time a version 2 server starts, it seals the existing master key and vector in place. This is a one-time, idempotent upgrade; sealed values are tagged with a DPAPI1: prefix so the server can tell sealed from unsealed and never double-seals.
  • No configuration change required. You do not enable or configure this; it happens on first start.
  • The AES layer is unchanged. Individual secrets are still AES-encrypted exactly as before. Only the master key that unlocks them is now sealed.

DPAPI machine-scope sealing binds the master key to the local machine. You cannot hand-copy the configuration file, keys, or data folder to another host and expect the secrets to decrypt there. The destination machine cannot unseal a key that was sealed on a different machine. The danger note in the configuration file reference about "copying the Key and Vector to migrate" applies only to pre-version-2 behaviour; in version 2 you must migrate using the archive command (below).

Migrating to a New or Reinstalled Machine

Because the master key is bound to the machine that sealed it, moving Signotaur to a new server (or recovering onto a reimaged or reinstalled one) must go through the server archive command rather than a file copy.

To migrate, run archive create on the source host to produce a passphrase-encrypted .sigbak bundle, copy that bundle to the destination, then run archive restore on the destination host. Restore re-seals the master key under the destination machine's DPAPI, so all secrets, certificates and database content decrypt correctly on the new machine. See the archive command for full usage.

A .sigbak bundle carries the master key in a passphrase-wrapped form (not DPAPI-sealed), so it is portable between machines; everything else in the bundle stays encrypted exactly as it was stored. The re-sealing happens only on the destination during restore.

Fail-Closed Behaviour

If the master key cannot be unsealed (for example because the configuration was copied from another host, DPAPI is broken, or the machine has been reimaged) Signotaur fails closed rather than silently producing garbage:

  • The server reports a clear error explaining that the master key cannot be unsealed.
  • Any component that needs a protected secret fails with guidance to restore on the original host or to use archive restore on the new host.
  • The web administration interface remains reachable (it falls back to an emergency self-signed certificate if necessary), so you can read the error and take action.

The server exposes a health flag, MasterKeyProtectedAtRest, which is true only when the master key is actually sealed at rest, along with an unseal-error state used to drive the status badges described next.

Footer Status Badges

When you are signed in as an administrator, Signotaur surfaces the at-rest-encryption health in the application footer with one of two status badges. When everything is sealed and healthy, no badge appears.

At-rest encryption footer status badges

Red: "Encryption unavailable"

Shown (with a shield-alert icon) when the master key cannot be unsealed. The badge explains that the master key can't be unsealed, gives the reason, and lists the likely causes and remediation:

  • The configuration was copied from another host.
  • DPAPI is broken on this machine.
  • The machine was reimaged or reinstalled.

Remediation is to restore on the original host, run archive restore on the new host, or reset encryption (see Recovery below).

Amber: "Secrets not protected at rest"

Shown (with a triangle-alert icon) when the master key is usable but is not sealed at rest, most likely because DPAPI fell back to plaintext. You can restart the server to re-seal it.

Recovery Paths

If the server reports that secrets cannot be decrypted or you see the red "Encryption unavailable" badge, choose the path that matches your situation:

  1. Restore on the original host. If the configuration or data folder was copied off the original machine, return to that machine (its DPAPI can still unseal the key) and run from there, or take a fresh archive create to migrate correctly.
  2. archive restore on the new host. If you are intentionally moving to a new or reinstalled machine, restore a .sigbak created on the source with archive restore; this re-seals the key under the destination's DPAPI. See the archive command.
  3. Reset encryption and re-enter secrets. If neither the original host nor a valid .sigbak is available, the encrypted secrets are unrecoverable. Reset the encryption configuration and re-enter every secret (OAuth client secrets, SMTP password, ADCS password, web-certificate PFX passwords, and the backup passphrase) from scratch.

See also Troubleshooting → Master key cannot be unsealed.