Seq uses AES-256 to reversibly encrypt secrets that are required at runtime. A single encryption key is used for this purpose, which Seq refers to as the "secret key".
The secret key used by a Seq instance is fixed, and must not be changed once the Seq instance is configured. The key can, however, be moved between storage locations/providers at any time.
The secret key is used for encryption of:
- Backups, allowing Seq to automatically back up to partially-trusted network locations, and to safely provide downloadable backups from the Seq UI/API
- Passwords for external NuGet feeds
- Client keys/secrets used in OIDC login provider configuration
- Sensitive configuration settings for plug-in apps
Seq never uses reversible encryption for user passwords or API keys: these are stored as one-way salted hashes using a suitable password hashing algorithm.
When Seq starts up for the first time, if no key has been pre-configured, it will generate one and write it to
Seq.json in its root storage directory.
This value will appear under the
On Windows, the value is encrypted using machine-scoped DPAPI. This allows any authenticated user on the Seq server to decrypt and read the value, but offers some protection against attacks that exfiltrate the
On Docker/Linux, where no local encryption mechanism is provided by the OS, the value is stored in plain text by default. See Secret Key Providers below to plug in additional key storage options.
When deploying Seq, it's often more convenient to pre-generate the secret key, and record this in a password manager or secret vault, in addition to configuring Seq to use it.
seq executable, and
datalust/seq Docker container, can both generate secret key values that can be copied to another Seq deployment:
On Windows, use
seq show-key --generate. On Docker/Linux, use
docker run --rm -it datalust/seq show-key --generate.
These commands will print a Base64-encoded, cryptographically-random secret key to
The secret key for a Seq instance can be set:
- using the
seq config setcommand, passing
- with the
SEQ_STORAGE_SECRETKEYenvironment variable, or
- using a secret key provider.
The secret key will also be set when restoring a backup with the
seq restore command.
On Windows it is generally preferred to use
seq config set or edit
Seq.json, as these will both cause the stored key to be encrypted with DPAPI.
For additional security, and on Docker/Linux, a Secret Key Provider can provide the key each time Seq starts up.
A secret key provider is an executable or script that is deployed alongside Seq (for example, under
Scripts/ in the Seq storage directory), that Seq invokes each time it starts up.
The secret key provider can retrieve the key from anywhere, including a key vault or config store. It should write the (Base64-encoded) key to
STDOUT and exit with code 0. If the secret key provider fails, it should return a non-zero exit code.
The secret key provider is configured in two parts: the path to an executable, and optionally, arguments that Seq will supply when the executable is invoked. It's possible that the executable will be a shell like
/bin/sh, and the arguments will be the path to a script file that the shell will run.
These can be set through
SEQ_SECRETKEY_PROVIDERARGS or with
Our simple example secret key provider will just use the
echo command to print the key to
# In secret-key-provider.sh
# Generate your own secret key, don't reuse this one :-)
For Seq to use the script, it needs to be stored in a location accessible to Seq within the Docker container. This might be a separate mounted volume, or under the
/data mount. We'll save it to
To configure the secret key provider, we'll place an init script in
seqsvr config set -k secretKey.provider -v /bin/bash
seqsvr config set -k secretKey.providerArgs -v /data/Scripts/secret-key-provider.sh
The first time the Seq container starts, it'll run and then archive the init script. From then on, Seq will call
/data/Scripts/secret-key-provider.sh whenever it needs the secret key.
Quick tip! If you're having trouble escaping quotes and other characters to set
secretKey.providerArgson the command line, try passing
-v. This way, you can type (or pipe from a file) the provider arguments, without needing any escaping at all.
Updated over 2 years ago