The Secret Key
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".
Setup-time only
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.
Purpose of the Secret Key
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.
Default location and storage of the Secret Key
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 storage.secretKey
property:
{
"storage": {
"secretKey": "pmk.789453hfd8hfsda89/uy=",
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 Seq.json
file.
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.
Pre-generating a Secret Key
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.
The 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 STDOUT
.
Setting the Secret Key
The secret key for a Seq instance can be set:
- in
Seq.json
directly, - using the
seq config set
command, passing-k storage.secretKey
, - with the
SEQ_STORAGE_SECRETKEY
environment 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.
Secret Key Providers
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_PROVIDER
and SEQ_SECRETKEY_PROVIDERARGS
or with seq config
.
Example for Docker/Linux
Our simple example secret key provider will just use the echo
command to print the key to STDOUT
:
# In secret-key-provider.sh
# Generate your own secret key, don't reuse this one :-)
echo Zs7PVzr0OZYw48GRRl8Yq6t0HXO5Ye+doiwZCUFw2Ew=
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 /data/Scripts/secret-key-provider.sh
.
To configure the secret key provider, we'll place an init script in /data/Init/set-secret-key-provider
:
#!/bin/bash
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.providerArgs
on the command line, try passing--value-stdin
instead of-v
. This way, you can type (or pipe from a file) the provider arguments, without needing any escaping at all.
Updated almost 3 years ago