How-To Guides¶
This section outlines a few of the typical workflows which can be achieved with
age
. For further information on the different subcommands, see Command Line Interface (CLI)
or call age
with the --help
option.
Generate a Key Pair¶
New age private keys can be generated with the age generate
subcommand. By
default the key is printed to the standard output stream, but it can also
directly by stored in a file.
$ pyage generate >> ~/.config/age/keys.txt
$ cat ~/.config/age/keys.txt
# created: 2020-02-10T13:34:27
# age1luj4yjndx48me58dalx200cs65qg9jhtcehjylnp8h9e2c9gduqqq8kduu
AGE-SECRET-KEY-1TPGEV9GPP6N39Z40RXTQQJMUHU40EJGDDWEFJDJFWVMY0F9FR9NSQRKGQL
Encrypt to a Public Key¶
Public keys of recipients must be provided in the age encrypt
command. The
simplest use case is to encrypt to an age public key starting with age1
.
$ echo "_o/" | pyage encrypt -o hello.age age1luj4yjndx48me58dalx200cs65qg9jhtcehjylnp8h9e2c9gduqqq8kduu
Decrypt Using a Private Key¶
age
will try private keys from several locations during decryption (see
Decryption). The following example works because the private key is
stored at
~/.config/age/keys.txt
(see
Generate a Key Pair).
$ pyage decrypt -i hello.age
_o/
Encrypt Using a Password¶
Besides asymmetric cryptography, age
can also encrypt to a password. The
same password is then required in order to decrypt the file. This can be seen
in the following example. Note that during the password prompt, entered
characters are not echoed to the terminal.
$ echo 'Hello Password!' | pyage encrypt -p -o hello_password.age
Type passphrase:
$ pyage decrypt -p -i hello_password.age
Type passphrase:
Hello Password!
Encrypt to a List of Recipients¶
Instead of providing a public key directly, age
can read recipients from a
file or an URL. Note that in this case, aliases are
not further expanded.
$ echo 'Hello file!' | pyage encrypt -o hello_recipients.age recipients.txt
$ echo 'Hello URL!' | pyage encrypt -o hello_recipients.age https://example.com/age-keys.txt
Encrypt to a GitHub User¶
GitHub serves the SSH public keys configured
in your profile at the url https://github.com/USERNAME.keys
. age
can
automatically read the keys at this URL if provided with the recipient
github:USERNAME
.
In the following example, decryption works because the corresponding private
key is stored in at ~/.ssh/id_rsa
.
$ echo 'Hello GitHub!' | pyage encrypt -o hello_github.age github:jojonas
$ pyage decrypt -i hello_github.age
Hello GitHub!
Use Aliases¶
Aliases can be configured in the file ~/.config/age/aliases.txt
. The file
contains one alias per line. The line must start with the alias label followed
by a colon. After the colon, multiple keys, files, URLs or GitHub usernames can
be specified, separated by a space character.
$ cat ~/.config/age/aliases.txt
filippo: age1luj4yjndx48me58dalx200cs65qnotarealkeyjylnp8h9e2c9gduqqq8kduu
ben: age1luj4yjndx48me58dalx200cs65qnotarealkeyjylnp8h9e2c9gduqqq8kduu github:Benjojo
jonas: age1luj4yjndx48me58dalx200cs65qg9jhtcehjylnp8h9e2c9gduqqq8kduu github:jojonas
$ echo 'Hello Alias!' | pyage encrypt -o hello_alias.age jonas