Skip to content

Vault

The Backend and the Frontend can read their KEK from a HashiCorp Vault at startup, instead of SMARTAGT_KEK. The KEK is read once and kept in memory: a restart reads the vault again.

Prerequisites

Item Expected
Secrets engine KV version 2, mounted on secret
Secret kek field holding the KEK, base64 of 32 bytes
Authentication Token allowed to read this secret, for example path "secret/data/smartagt/backend/kek" { capabilities = ["read"] }
TLS Vault authority trusted by the SmartAGT server

Procedure

1. Write the KEK to the vault

Once per component:

vault kv put -mount=secret smartagt/backend/kek kek=-

Enter the current KEK of the component on standard input, then confirm with Ctrl+D.

Expected result: vault kv get -mount=secret smartagt/backend/kek shows the kek field.

2. Declare the provider

In the component YAML:

smartagt:
  security:
    encryption:
      kek_provider:
        type: vault
        config:
          url: "https://vault.example.org:8200"
          key_path: "smartagt/backend/kek"   # path under the secret mount

3. Provide the token

In the service environment, a file readable by the service account, and the vault authority if it is private:

SMARTAGT_SECURITY_ENCRYPTION_KEK__PROVIDER_CONFIG_TOKEN_FILE=/etc/smartagt/vault-token-backend
VAULT_CACERT=/etc/smartagt/vault-ca.pem

Remove SMARTAGT_KEK from this environment and from any --preserve-env command: as long as this variable exists, it takes precedence over the vault, without any error message. On Windows, these variables go into the service environment. For the Frontend, apply the same step to its YAML and bff.env, with its own path in the vault.

4. Restart the services

Restart the services of the component: Operations.

Expected result: the service log shows KEK récupérée depuis Vault (len=32).

Special cases

Token lifetime

SmartAGT does not renew the token. Choose a lifetime that covers restarts, or renew it before it expires.

run.bin commands

The init and pki commands read the KEK the same way. Run them with the same YAML and environment as the service, for example sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD,SMARTAGT_SECURITY_ENCRYPTION_KEK__PROVIDER_CONFIG_TOKEN_FILE,VAULT_CACERT.

Startup messages
Message Cause
Échec d'authentification auprès de Vault Invalid or expired token
Lecture KEK depuis Vault échouée Wrong path, missing read right, engine other than KV version 2 on secret, or non-base64 value
Champ 'kek' introuvable dans le secret Vault Secret present without a kek field
KEK invalide : 32 octets attendus Field value that is not a base64 KEK of 32 bytes
CERTIFICATE_VERIFY_FAILED Vault authority missing from VAULT_CACERT

The service then refuses to start.