Encryption

The service encrypts backup data before uploading it to storage. Reading encrypted backups requires both storage access and the encryption key. As an operator, you enable encryption by connecting a key manager. Project members choose the encryption mode when they create each plan.

Key hierarchy

Backup data is encrypted with data keys, one per encryption domain. A data key is only stored wrapped by a master key. The master key stays in your key manager, and is never stored in the database or on a node's disk. Deduplication happens within a domain:

Plan's choice	Domain	Effect
Repository key	One shared encrypted domain per repository	Identical data from all such plans is stored once.
Its own key (--encryption barbican)	A domain for this plan alone	Nothing is shared with any other plan. Losing the key makes the plan's backups unreadable.
Not encrypted (--encryption none)	One shared plain domain per repository	Stored as written, deduplicated across every unencrypted plan.

A plan's choice is made when it is created and never changes.

Choose the key manager

Driver	Result
barbican	Encrypted backups, master key in Barbican.
vault	Encrypted backups, master key in a HashiCorp Vault transit engine.
none	No encryption is possible, and every plan is unencrypted. The console hides the encryption choice and creates plans unencrypted. The API and CLI refuse a plan that does not say --encryption none. Backups then sit at the storage provider as written. Anyone who can read the bucket can read them.

Use Barbican or Vault to manage master keys. The deployment precheck rejects a local key file.

kolla-ansible

ferry_kms_driver: "barbican"
ferry_kms_barbican_secret_id: "<secret-id>"

Create the master key before deploying, so its creation is recorded in the audit log:

source /etc/kolla/admin-openrc.sh
./tools/create-kek.sh

It prints the secret id for globals.yml, and grants the service user read access to the secret. Without that access, the first repository registration fails with "Secret payload retrieval attempt not allowed". Running it again reuses the existing secret.

For Vault:

ferry_kms_driver: "vault"
ferry_kms_vault_address: "https://vault.mycompany.com:8200"
ferry_kms_vault_mount: "transit"
ferry_kms_vault_key_name: "ferry"
ferry_kms_vault_token_file: "/var/run/vault/ferry-token"

Helm

kms:
  driver: barbican
  barbican:
    secretId: <secret-id>

or

kms:
  driver: vault
  vault:
    address: https://vault.mycompany.com:8200
    mount: transit
    keyName: ferry
    tokenSecret: <secret-holding-the-token>
    tokenKey: token

Juju

juju config ferry kms-driver=barbican barbican-secret-id=<secret-id>

The charms support none and barbican.

Vault needs a transit engine and a key, and a policy for three operations on that key:

vault secrets enable transit
vault write -f transit/keys/ferry

path "transit/encrypt/ferry" { capabilities = ["update"] }
path "transit/decrypt/ferry" { capabilities = ["update"] }
path "transit/rewrap/ferry"  { capabilities = ["update"] }

Provide a Vault token directly or through a file. We recommend a token file renewed by Vault Agent. Managers reread the file when it changes and when Vault rejects a token.

Rotating the transit key is safe. New keys are wrapped under the new version. Every key already stored still decrypts under the version that wrapped it. Do not raise the transit key's min_decryption_version while stored keys still use an older version.

Changing the key manager later

warning

Choose the driver before the first backup. A repository's credentials and keys are sealed by the key manager in place when the repository is registered. A repository registered under one key manager does not open under another.

Pointing a deployment at a different key manager makes every existing repository fail to open with "wrapped key was produced by barbican, this KMS is vault". Nothing is corrupted, and switching back restores access. To move to a new key manager, register a new repository under it, move policies to the new repository, and let the old backups expire where they are.

Move a key to another cloud

Restoring a backup in another cloud needs the domain's data key there. Export it from the cloud that wrote the data and import it into the other, under a passphrase that travels separately:

ferry admin key fingerprint --repository <repository>
ferry admin key export --repository <repository> --domain <domain> --passphrase-file - --out domain.key
ferry admin key import --repository <repository> --domain <domain> --passphrase-file - -f domain.key

Unencrypted backups use the plain domain. Exporting its key fails with domain_not_encrypted. For encrypted domains, the export encrypts the key with the passphrase and binds it to the repository and domain. Every export is recorded in the audit log. Compare fingerprints on both clouds before attempting a restore.

On a locked repository, add recovery recipients before the first encrypted backup.