ContextQMD
Back to Chezmoi

age

assets/chezmoi.io/docs/user-guide/encryption/age.md

2.70.23.0 KB
Original Source

age

chezmoi supports encrypting files with age.

Generate a key using chezmoi age-keygen:

console
$ chezmoi age-keygen --output=$HOME/key.txt
Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

Specify age encryption in your configuration file, being sure to specify at least the identity and one recipient:

<!-- example-formats -->
toml
encryption = "age"
[age]
    identity = "/home/user/key.txt"
    recipient = "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"
<!-- /example-formats -->

chezmoi supports multiple identities and multiple recipients:

<!-- example-formats -->
toml
encryption = "age"
[age]
    identities = ["/home/user/key1.txt", "/home/user/key2.txt"]
    recipients = ["recipient1", "recipient2"]
<!-- /example-formats -->

!!! note

Make sure `encryption` is added to the top level section at the beginning of
the config, before any other sections.

Symmetric encryption

To use age's symmetric encryption, specify a single identity and enable symmetric encryption in your config file, for example:

<!-- example-formats -->
toml
encryption = "age"
[age]
    identity = "~/.ssh/id_rsa"
    symmetric = true
<!-- /example-formats -->

Symmetric encryption with a passphrase

To use age's symmetric encryption with a passphrase, set age.passphrase to true in your config file, for example:

<!-- example-formats -->
toml
encryption = "age"
[age]
    passphrase = true
<!-- /example-formats -->

You will be prompted for the passphrase whenever you run chezmoi add --encrypt and whenever chezmoi needs to decrypt the file, for example when you run chezmoi apply, chezmoi diff, or chezmoi status.

Builtin age encryption

chezmoi has builtin support for age encryption which is automatically used if the age command is not found in $PATH.

!!! info

The builtin age encryption does not support passphrases, symmetric
encryption, or SSH keys.

Passphrases are not supported because chezmoi needs to decrypt files
regularly, e.g. when running a `chezmoi diff` or a `chezmoi status`
command, not just when running `chezmoi apply`. Prompting for a passphrase
each time would quickly become tiresome.

Symmetric encryption may be supported in the future. Please [open an
issue][issue] if you want this.

SSH keys are not supported as the [age documentation explicitly recommends
not using them][nossh]:

> When integrating age into a new system, it's recommended that you only
> support X25519 keys, and not SSH keys. The latter are supported for
> manual encryption operations.