1AGE(1) AGE(1)
2
6 age - simple, modern, and secure file encryption
7
9 age [--encrypt] (-r RECIPIENT | -R PATH)... [--armor] [-o OUTPUT] [IN‐
10 PUT]
11 age [--encrypt] --passphrase [--armor] [-o OUTPUT] [INPUT]
12 age --decrypt [-i PATH | -j PLUGIN]... [-o OUTPUT] [INPUT]
13
15 age encrypts or decrypts INPUT to OUTPUT. The INPUT argument is op‐
16 tional and defaults to standard input. Only a single INPUT file may be
17 specified. If -o is not specified, OUTPUT defaults to standard output.
18 If -p/--passphrase is specified, the file is encrypted with a
20 passphrase requested interactively. Otherwise, it´s encrypted to one or
21 more RECIPIENTS specified with -r/--recipient or -R/--recipients-file.
22 Every recipient can decrypt the file.
23 In -d/--decrypt mode, passphrase-encrypted files are detected automati‐
25 cally and the passphrase is requested interactively. Otherwise, one or
26 more IDENTITIES specified with -i/--identity are used to decrypt the
27 file.
28 age encrypted files are binary and not malleable, with around 200 bytes
30 of overhead per recipient, plus 16 bytes every 64KiB of plaintext.
31
33 -o, --output=OUTPUT
34 Write encrypted or decrypted file to OUTPUT instead of standard
35 output. If OUTPUT already exists it will be overwritten.
36 If encrypting without --armor, age will refuse to output binary
38 to a TTY. This can be forced by specifying - as OUTPUT.
39 --version
41 Print the version and exit.
42 Encryption options
44 -e, --encrypt
45 Encrypt INPUT to OUTPUT. This is the default.
46 -r, --recipient=RECIPIENT
48 Encrypt to the explicitly specified RECIPIENT. See the RECIPI‐
49 ENTS AND IDENTITIES section for possible recipient formats.
50 This option can be repeated and combined with other recipient
52 flags, and the file can be decrypted by all provided recipients
53 independently.
54 -R, --recipients-file=PATH
56 Encrypt to the RECIPIENTS listed in the file at PATH, one per
57 line. Empty lines and lines starting with # are ignored as com‐
58 ments.
59 If PATH is -, the recipients are read from standard input. In
61 this case, the INPUT argument must be specified.
62 This option can be repeated and combined with other recipient
64 flags, and the file can be decrypted by all provided recipients
65 independently.
66 -p, --passphrase
68 Encrypt with a passphrase, requested interactively from the ter‐
69 minal. age will offer to auto-generate a secure passphrase.
70 This option can´t be used with other recipient flags.
72 -a, --armor
74 Encrypt to an ASCII-only "armored" encoding.
75 age armor is a strict version of PEM with type AGE ENCRYPTED
77 FILE, canonical "strict" Base64, no headers, and no support for
78 leading and trailing extra data.
79 Decryption transparently detects and decodes ASCII armoring.
81 -i, --identity=PATH
83 Encrypt to the RECIPIENTS corresponding to the IDENTITIES listed
84 in the file at PATH. This is equivalent to converting the file
85 at PATH to a recipients file with age-keygen -y and then passing
86 that to -R/--recipients-file.
87 For the format of PATH, see the definition of -i/--identity in
89 the Decryption options section.
90 -e/--encrypt must be explicitly specified when using -i/--iden‐
92 tity in encryption mode to avoid confusion.
93 -j PLUGIN
95 Encrypt using the data-less plugin PLUGIN.
96 This is equivalent to using -i/--identity with a file that con‐
98 tains a single plugin IDENTITY that encodes no plugin-specific
99 data.
100 -e/--encrypt must be explicitly specified when using -j in en‐
102 cryption mode to avoid confusion.
103 Decryption options
105 -d, --decrypt
106 Decrypt INPUT to OUTPUT.
107 If INPUT is passphrase encrypted, it will be automatically de‐
109 tected and the passphrase will be requested interactively. Oth‐
110 erwise, the IDENTITIES specified with -i/--identity are used.
111 ASCII armoring is transparently detected and decoded.
113 -i, --identity=PATH
115 Decrypt using the IDENTITIES at PATH.
116 PATH may be one of the following:
118 a. A file listing IDENTITIES one per line. Empty lines and lines
120 starting with "#" are ignored as comments.
121 b. A passphrase encrypted age file, containing IDENTITIES one
123 per line like above. The passphrase is requested interactively.
124 Note that passphrase-protected identity files are not necessary
125 for most use cases, where access to the encrypted identity file
126 implies access to the whole system.
127 c. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH for‐
129 mat. If the private key is password-protected, the password is
130 requested interactively only if the SSH identity matches the
131 file. See the SSH keys section for more information, including
132 supported key types.
133 d. "-", causing one of the options above to be read from stan‐
135 dard input. In this case, the INPUT argument must be specified.
136 This option can be repeated. Identities are tried in the order
138 in which are provided, and the first one matching one of the
139 file´s recipients is used. Unused identities are ignored, but it
140 is an error if the INPUT file is passphrase-encrypted and
141 -i/--identity is specified.
142 -j PLUGIN
144 Decrypt using the data-less plugin PLUGIN.
145 This is equivalent to using -i/--identity with a file that con‐
147 tains a single plugin IDENTITY that encodes no plugin-specific
148 data.
149
151 RECIPIENTS are public values, like a public key, that a file can be en‐
152 crypted to. IDENTITIES are private values, like a private key, that al‐
153 low decrypting a file encrypted to the corresponding RECIPIENT.
154 Native X25519 keys
156 Native age key pairs are generated with age-keygen(1), and provide
157 small encodings and strong encryption based on X25519. They are the
158 recommended recipient type for most applications.
159 A RECIPIENT encoding begins with age1 and looks like the following:
161 age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh
165 An IDENTITY encoding begins with AGE-SECRET-KEY-1 and looks like the
169 following:
170 AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
174 An encrypted file can´t be linked to the native recipient it´s en‐
178 crypted to without access to the corresponding identity.
179 SSH keys
181 As a convenience feature, age also supports encrypting to RSA or
182 Ed25519 ssh(1) keys. RSA keys must be at least 2048 bits. This feature
183 employs more complex cryptography, and should only be used when a na‐
184 tive key is not available for the recipient. Note that SSH keys might
185 not be protected long-term by the recipient, since they are revokable
186 when used only for authentication.
187 A RECIPIENT encoding is an SSH public key in authorized_keys format
189 (see the AUTHORIZED_KEYS FILE FORMAT section of sshd(8)), starting with
190 ssh-rsa or ssh-ed25519, like the following:
191 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8=
195 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa
196 The comment at the end of the line, if present, is ignored.
200 In recipient files passed to -R/--recipients-file, unsupported but
202 valid SSH public keys are ignored with a warning, to facilitate using
203 authorized_keys or GitHub .keys files. (See EXAMPLES.)
204 An IDENTITY is an SSH private key file passed individually to
206 -i/--identity. Note that keys held on hardware tokens such as YubiKeys
207 or accessed via ssh-agent(1) are not supported.
208 An encrypted file can be linked to the SSH public key it was encrypted
210 to. This is so that age can identify the correct SSH private key before
211 requesting its password, if any.
212 Plugins
214 age can be extended through plugins. A plugin is only loaded if a cor‐
215 responding RECIPIENT or IDENTITY is specified. (Simply decrypting a
216 file encrypted with a plugin will not cause it to load, for security
217 reasons among others.)
218 A RECIPIENT for a plugin named example starts with age1example1, while
220 an IDENTITY starts with AGE-PLUGIN-EXAMPLE-1. They both encode arbi‐
221 trary plugin-specific data, and are generated by the plugin.
222 When either is specified, age searches for age-plugin-example in the
224 PATH and executes it to perform the file header encryption or decryp‐
225 tion. The plugin may request input from the user through age to com‐
226 plete the operation.
227 Plugins can be freely mixed with other plugins or natively supported
229 keys.
230 A plugin is not bound to only encrypt or decrypt files meant for or
232 generated by the plugin. For example, a plugin can be used to decrypt
233 files encrypted to a native X25519 RECIPIENT or even with a passphrase.
234 Similarly, a plugin can encrypt a file such that it can be decrypted
235 without the use of any plugin.
236 Plugins for which the IDENTITY/RECIPIENT distinction doesn´t make sense
238 (such as a symmetric encryption plugin) may generate only an IDENTITY
239 and instruct the user to perform encryption with the -e/--encrypt and
240 -i/--identity flags. Plugins for which the concept of separate identi‐
241 ties doesn´t make sense (such as a password-encryption plugin) may in‐
242 struct the user to use the -j flag.
243
245 age will exit 0 if and only if encryption or decryption are successful
246 for the full length of the input.
247 If an error occurs during decryption, partial output might still be
249 generated, but only if it was possible to securely authenticate it. No
250 unauthenticated output is ever released.
251
253 Files encrypted with a stable version (not alpha, beta, or release can‐
254 didate) of age, or with any v1.0.0 beta or release candidate, will de‐
255 crypt with any later version of the tool.
256 If decrypting older files poses a security risk, doing so might cause
258 an error by default. In this case, a flag will be provided to force the
259 operation.
260
262 Generate a new identity, encrypt data, and decrypt:
263 $ age-keygen -o key.txt
267 Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
268 $ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
270 $ age -d -o data.tar.gz -i key.txt data.tar.gz.age
272 Encrypt example.jpg to multiple recipients and output to exam‐
276 ple.jpg.age:
277 $ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
281 -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg
282 Encrypt to a list of recipients:
286 $ cat > recipients.txt
290 # Alice
291 age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
292 # Bob
293 age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
294 $ age -R recipients.txt example.jpg > example.jpg.age
296 Encrypt and decrypt a file using a passphrase:
300 $ age -p secrets.txt > secrets.txt.age
304 Enter passphrase (leave empty to autogenerate a secure one):
305 Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".
306 $ age -d secrets.txt.age > secrets.txt
308 Enter passphrase:
309 Encrypt and decrypt with a passphrase-protected identity file:
313 $ age-keygen | age -p > key.age
317 Public key: age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5
318 Enter passphrase (leave empty to autogenerate a secure one):
319 Using the autogenerated passphrase "hip-roast-boring-snake-mention-east-wasp-honey-input-actress".
320 $ age -r age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5 secrets.txt > secrets.txt.age
322 $ age -d -i key.age secrets.txt.age > secrets.txt
324 Enter passphrase for identity file "key.age":
325 Encrypt and decrypt with an SSH public key:
329 $ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age
333 $ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg
335 Encrypt and decrypt with age-plugin-yubikey:
339 $ age-plugin-yubikey # run interactive setup, generate identity file and obtain recipient
343 $ age -r age1yubikey1qwt50d05nh5vutpdzmlg5wn80xq5negm4uj9ghv0snvdd3yysf5yw3rhl3t secrets.txt > secrets.txt.age
345 $ age -d -i age-yubikey-identity-388178f3.txt secrets.txt.age
347 Encrypt to the SSH keys of a GitHub user:
351 $ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age
355
359 age-keygen(1)
360
362 Filippo Valsorda age@filippo.io
363 September 2022 AGE(1)