Documentation for batou secrets with age.

Using batou with age as a secrets backend works similar to using batou with gpg as before. There is a small format change in the secrets.cfg file, as well as renaming the secret files from “secret-” to “secret-.gpg” or “secret-*.age” for age encrypted secrets.

You also should set some environment variables to make sure that age is configured to use the correct keys.

secrets.cfg.* file

In the secrets.cfg.* file, the [batou] section has a new key secret_provider. If that key is not set, batou will use the file extension of the secret file to determine the secret provider. If the key is set, on saving the secret provider will be chosen based on the value of the key.

It looks like this:

[batou]
members =
    https://github.com/user1.keys,
    https://github.com/user2.keys
secret_provider = age

You can see that using the age secret provider allows us to specify keys from https sources. This is because age accepts ssh public keys as encryption recipients.

We accept ssh public keys (beginning with ssh-) as well as age public keys (beginning with age1), or http(s):// urls to ssh public-key files.

GPG is still supported as before.

On saving a file with changes, the secret_provider key will be added to the secrets.cfg file. If you do not change the file, the file will not even be re-encrypted.

Moving a project to the new secrets format

Essentially, you just have to rename the secret files from secret-* to secret-*.gpg as well as renaming the secrets.cfg file to secrets.cfg.gpg.

Upgrading a project to the new secrets format is done by running ./batou migrate if your batou version supports age secrets. This will append .gpg to all existing secret files, since only gpg was supported before.

You can still use the gpg encrypted secrets on newer batou versions. In case you want to use age encrypted secrets, edit the secrets.cfg(.gpg) file using ./batou secrets edit and add the secret_provider = age key to the [batou] section. Once you close the editor, the secrets will be re-encrypted using age.

New environment variables

Age needs to know which secret key to use for decryption. Set the BATOU_AGE_IDENTITIES key to your ssh private key file, or a comma separated list of ssh private key files to try to use for decryption.

By default, batou will use the search order of ssh (~/.ssh/id_rsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ecdsa_sk, ~/.ssh/id_ed25519, ~/.ssh/id_ed25519_sk and ~/.ssh/id_dsa).

You can run this in your shell or add it to your .bashrc or .zshrc file:

export BATOU_AGE_IDENTITIES=$HOME/.ssh/id_ed25519

SSH Key decryption using 1password integration

If your ssh key is encrypted, you can use the BATOU_AGE_IDENTITY_PASSPHRASE environment variable to provide a 1password reference url to your ssh key passphrase.

export BATOU_AGE_IDENTITY_PASSPHRASE="op://<vault>/<item>[/<section>]/<field>"

You can find the secret reference url in the 1password 8 app, by right clicking on the arrow next to the password field and selecting “Copy Secret Reference”. Follow the 1password documentation for more information.

You need to set up the 1password cli to use the op command. See the 1password cli documentation.

If you do not set the BATOU_AGE_IDENTITY_PASSPHRASE environment variable, you will be prompted for the passphrase on every run of batou that uses age.

Changes in the project exposed API

No changes