DocumentationDiscussions
Documentation
DocumentationDiscussions

The Secret Key

Seq uses AES-256 to 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 4 months ago