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.