1AGE(1)                                                                  AGE(1)
2
3
4

NAME

6       age - simple, modern, and secure file encryption
7

SYNOPSIS

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]... [-o OUTPUT] [INPUT]
13

DESCRIPTION

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
19       If --passphrase is specified, the file is encrypted with  a  passphrase
20       requested  interactively.  Otherwise, it´s encrypted to one or more RE‐
21       CIPIENTS specified with -r/--recipient or  -R/--recipients-file.  Every
22       recipient can decrypt the file.
23
24       In  --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
29       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

OPTIONS

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
37              If encrypting without --armor, age will refuse to output  binary
38              to a TTY. This can be forced by specifying - as OUTPUT.
39
40       --version
41              Print the version and exit.
42
43   Encryption options
44       -e, --encrypt
45              Encrypt INPUT to OUTPUT. This is the default.
46
47       -r, --recipient=RECIPIENT
48              Encrypt  to  the explicitly specified RECIPIENT. See the RECIPI‐
49              ENTS AND IDENTITIES section for possible recipient formats.
50
51              This option can  be  repeated  and  combined  with  -R/--recipi‐
52              ents-file, and the file can be decrypted by all provided recipi‐
53              ents independently.
54
55       -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
60              If PATH is -, the recipients are read from  standard  input.  In
61              this case, the INPUT argument must be specified.
62
63              This  option  can  be repeated and combined with -r/--recipient,
64              and the file can be decrypted by all provided  recipients  inde‐
65              pendently.
66
67       -p, --passphrase
68              Encrypt with a passphrase, requested interactively from the ter‐
69              minal. age will offer to auto-generate a secure passphrase.
70
71              This options can´t be used with -r/--recipient  or  -R/--recipi‐
72              ents-file.
73
74       -a, --armor
75              Encrypt to an ASCII-only "armored" encoding.
76
77              age  armor  is  a  strict version of PEM with type AGE ENCRYPTED
78              FILE, canonical "strict" Base64, no headers, and no support  for
79              leading and trailing extra data.
80
81              Decryption transparently detects and decodes ASCII armoring.
82
83   Decryption options
84       -d, --decrypt
85              Decrypt INPUT to OUTPUT.
86
87              If  INPUT  is passphrase encrypted, it will be automatically de‐
88              tected and the passphrase will be requested interactively.  Oth‐
89              erwise, the IDENTITIES specified with -i/--identity are used.
90
91              ASCII armoring is transparently detected and decoded.
92
93       -i, --identity=PATH
94              Decrypt using the IDENTITIES at PATH.
95
96              PATH may be one of the following:
97
98              a. A file listing IDENTITIES one per line. Empty lines and lines
99              starting with "#" are ignored as comments.
100
101              b. A passphrase encrypted age file,  containing  IDENTITIES  one
102              per  line like above. The passphrase is requested interactively.
103              Note that passphrase-protected identity files are not  necessary
104              for  most use cases, where access to the encrypted identity file
105              implies access to the whole system.
106
107              c. An SSH private key file, in PKCS#1, PKCS#8, or  OpenSSH  for‐
108              mat.  If  the private key is password-protected, the password is
109              requested interactively only if the  SSH  identity  matches  the
110              file.  See  the SSH keys section for more information, including
111              supported key types.
112
113              d. "-", causing one of the options above to be read  from  stan‐
114              dard input. In this case, the INPUT argument must be specified.
115
116              This  option  can be repeated. Identities are tried in the order
117              in which are provided, and the first one  matching  one  of  the
118              file´s recipients is used. Unused identities are ignored.
119
120              If  -e/--encrypt  is  explicitly specified (to avoid confusion),
121              -i/--identity may also be used to encrypt to the RECIPIENTS cor‐
122              responding  to  the IDENTITIES listed at PATH. This allows using
123              an identity file as a symmetric key, if desired.
124

RECIPIENTS AND IDENTITIES

126       RECIPIENTS are public values, like a public key, that a file can be en‐
127       crypted to. IDENTITIES are private values, like a private key, that al‐
128       low decrypting a file encrypted to the corresponding RECIPIENT.
129
130   Native X25519 keys
131       Native age key pairs are  generated  with  age-keygen(1),  and  provide
132       small  encodings  and  strong  encryption based on X25519. They are the
133       recommended recipient type for most applications.
134
135       A RECIPIENT encoding begins with age1 and looks like the following:
136
137
138
139           age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh
140
141
142
143       An IDENTITY encoding begins with AGE-SECRET-KEY-1 and  looks  like  the
144       following:
145
146
147
148           AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
149
150
151
152       An  encrypted  file  can´t  be  linked to the native recipient it´s en‐
153       crypted to without access to the corresponding identity.
154
155   SSH keys
156       As a convenience feature,  age  also  supports  encrypting  to  RSA  or
157       Ed25519  ssh(1) keys. RSA keys must be at least 2048 bits. This feature
158       employs more complex cryptography, and should only be used when  a  na‐
159       tive  key  is not available for the recipient. Note that SSH keys might
160       not be protected long-term by the recipient, since they  are  revokable
161       when used only for authentication.
162
163       A  RECIPIENT  encoding  is  an SSH public key in authorized_keys format
164       (see the AUTHORIZED_KEYS FILE FORMAT section of sshd(8)), starting with
165       ssh-rsa or ssh-ed25519, like the following:
166
167
168
169           ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8=
170           ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa
171
172
173
174       The comment at the end of the line, if present, is ignored.
175
176       In  recipient  files  passed  to  -R/--recipients-file, unsupported but
177       valid SSH public keys are ignored with a warning, to  facilitate  using
178       authorized_keys or GitHub .keys files. (See EXAMPLES.)
179
180       An  IDENTITY  is  an  SSH  private  key  file  passed  individually  to
181       -i/--identity. Note that keys held on hardware tokens such as  YubiKeys
182       or accessed via ssh-agent(1) are not supported.
183
184       An  encrypted file can be linked to the SSH public key it was encrypted
185       to. This is so that age can identify the correct SSH private key before
186       requesting its password, if any.
187

EXIT STATUS

189       age  will  exit 0 if and only if encryption or decryption are succesful
190       for the full length of the input.
191
192       If an error occurs during decryption, partial  output  might  still  be
193       generated,  but only if it was possible to securely authenticate it. No
194       unauthenticathed output is ever released.
195

BACKWARDS COMPATIBILITY

197       Files encrypted with a stable version (not alpha, beta, or release can‐
198       didate)  of age, or with any v1.0.0 beta or release candidate, will de‐
199       crypt with any later version of the tool.
200
201       If decrypting older files poses a security risk, doing so  might  cause
202       an  error  by  default, and a flag will be provided to force the opera‐
203       tion.
204

EXAMPLES

206       Generate a new identity, encrypt data, and decrypt:
207
208
209
210           $ age-keygen -o key.txt
211           Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
212
213           $ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
214
215           $ age -d -o data.tar.gz -i key.txt data.tar.gz.age
216
217
218
219       Encrypt  example.jpg  to  multiple  recipients  and  output  to   exam‐
220       ple.jpg.age:
221
222
223
224           $ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
225               -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg
226
227
228
229       Encrypt to a list of recipients:
230
231
232
233           $ cat > recipients.txt
234           # Alice
235           age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
236           # Bob
237           age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
238
239           $ age -R recipients.txt example.jpg > example.jpg.age
240
241
242
243       Encrypt and decrypt a file using a passphrase:
244
245
246
247           $ age -p secrets.txt > secrets.txt.age
248           Enter passphrase (leave empty to autogenerate a secure one):
249           Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".
250
251           $ age -d secrets.txt.age > secrets.txt
252           Enter passphrase:
253
254
255
256       Encrypt and decrypt with a passphrase-protected identity file:
257
258
259
260           $ age-keygen | age -p > key.age
261           Public key: age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5
262           Enter passphrase (leave empty to autogenerate a secure one):
263           Using the autogenerated passphrase "hip-roast-boring-snake-mention-east-wasp-honey-input-actress".
264
265           $ age -r age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5 secrets.txt > secrets.txt.age
266
267           $ age -d -i key.age secrets.txt.age > secrets.txt
268           Enter passphrase for identity file "key.age":
269
270
271
272       Encrypt and decrypt with an SSH public key:
273
274
275
276           $ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age
277
278           $ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg
279
280
281
282       Encrypt to the SSH keys of a GitHub user:
283
284
285
286           $ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age
287
288
289

SEE ALSO

291       age-keygen(1)
292

AUTHORS

294       Filippo Valsorda age@filippo.io
295
296
297
298                                September 2021                          AGE(1)
Impressum