Secrets

A secret is a value an integration needs but nobody should read, such as an ERP’s API key or a database password. Weik.io seals every secret with AES-256-GCM under the installation’s master key, a file on each backend host that is never in the message server’s storage or in a backup. Secret values never live in Git, and an exported configuration has the secret’s name and description without its value.

Set a secret#

$ weikio secret set finance/erp-api-key --env production

The command asks for the value with hidden input, uses standard input when you pipe the value in, or the file --from-file gives. It never echoes the value or prints it masked. A secret without --env is the project’s default, which every environment uses unless it has its own. --integration erp-invoice-export sets a value only that integration receives.

An integration reads a secret as a plain Camel property placeholder, such as {{erp-api-key}}, the same way it reads a variable. A running integration isn’t touched by the change: the value reaches each deployment at its next start, and the command lists the deployments that use it with their weikio restart lines. --restart restarts them for you. Variables and secrets shows how values are picked per environment.

How a flow gets its secrets#

At each start the agent writes the deployment’s values into a properties file that only the agent’s user can read, and the integration reads them from there. A secret is never on a command line, so it doesn’t show in a process list. At the site, disk encryption protects that file, as Encryption at rest says.

Reveal a value#

Revealing a secret is a permission of its own, the verb reveal, and each environment decides whether reveals are allowed at all:

$ weikio secret reveal finance/erp-api-key --env devtest
$ weikio env set production --allow-secret-reveal=false

An environment that doesn’t allow reveals refuses them to everyone, platform administrators included. Each caller may reveal ten values a minute, and every reveal is in the audit trail as SecretRevealed, with who revealed it, when and from which address:

$ weikio audit query --since 7d --action SecretRevealed

A value that comes from an external secret store is never revealed.

The master key#

init doesn’t make the master key, you do, before the first start: 32 random bytes in a file only the images’ user can read. Keep a copy off the server and apart from the backup archives, because a restore needs it and no archive contains it.

To change the master key, create a new key file and re-seal everything with it:

$ head -c 32 /dev/urandom > /opt/weikio/master.key.new && chown 1654:1654 /opt/weikio/master.key.new && chmod 0400 /opt/weikio/master.key.new
$ docker compose run --rm infra weikio-backend secrets rotate --new-key-file /opt/weikio/master.key.new

The command re-seals every secret, every local user’s password hash and second factor and every signing key under the new key. Then put the new key where WEIKIO_MASTER_KEY_FILE points on every backend server and restart the backends one at a time, and the backup service seals its next archive with it. Keep the old key for as long as you keep the archives taken before the change, because they open only with it.

Secrets from Azure Key Vault or Vault#

The platform gets secret values from a Dapr secret store, which covers Azure Key Vault, HashiCorp Vault and the other stores Dapr supports, with no vendor SDK in Weik.io. You run the Dapr sidecar yourself in the backend’s network namespace, for example as a service with network_mode: "service:backend" in docker-compose.override.yaml, and give the backend these settings in the same file:

services:
  backend:
    environment:
      Weikio__Secrets__Dapr__Enabled: "true"
      Weikio__Secrets__Dapr__BaseUrl: http://localhost:3500
      Weikio__Secrets__Dapr__Store: <the name of the secret store component>
      Weikio__Secrets__Dapr__ApiTokenFile: /run/secrets/dapr-api-token
    volumes:
      - /path/to/dapr-api-token:/run/secrets/dapr-api-token:ro

Then run docker compose up -d, which reads the override file with the stack file.

The platform asks the store for a name only when no deployment override, variable or secret on the platform has it. Some stores, Azure Key Vault’s among them, answer a name they don’t have with an error. With such a store, a deployment that reads a name neither the platform nor the store has stays blocked, and its status says what the store answered. A placeholder with a default or marked optional, such as {{name:default}} or {{?name}}, starts without a value as plain Camel would, and the hub logs a warning.

Platform secrets#

Credentials the platform itself uses, such as the token of a telemetry forwarding destination or a DNS connection, are platform secrets. Only platform administrators set, list and delete them, no route reveals them and they’re never delivered to a deployment:

$ weikio platform secret set siem-token

A platform secret that a forwarding document, a DNS connection or a certificate authority uses can’t be deleted until nothing uses it.