|
| 1 | +age(1) -- simple, modern, and secure file encryption |
| 2 | +==================================================== |
| 3 | + |
| 4 | +## SYNOPSIS |
| 5 | + |
| 6 | +`age` [`--encrypt`] (`-r` <RECIPIENT> | `-R` <PATH>)... [`--armor`] [`-o` <OUTPUT>] [<INPUT>]<br> |
| 7 | +`age` [`--encrypt`] `--passphrase` [`--armor`] [`-o` <OUTPUT>] [<INPUT>]<br> |
| 8 | +`age` `--decrypt` [`-i` <PATH>]... [`-o` <OUTPUT>] [<INPUT>]<br> |
| 9 | + |
| 10 | +## DESCRIPTION |
| 11 | + |
| 12 | +`age` encrypts or decrypts <INPUT> to <OUTPUT>. The <INPUT> argument is |
| 13 | +optional and defaults to standard input. Only a single <INPUT> file may be |
| 14 | +specified. If `-o` is not specified, <OUTPUT> defaults to standard output. |
| 15 | + |
| 16 | +If `--passphrase` is specified, the file is encrypted with a passphrase |
| 17 | +requested interactively. Otherwise, it's encrypted to one or more |
| 18 | +[RECIPIENTS][RECIPIENTS AND IDENTITIES] specified with `-r`/`--recipient` or |
| 19 | +`-R`/`--recipients-file`. Every recipient can decrypt the file. |
| 20 | + |
| 21 | +In `--decrypt` mode, passphrase-encrypted files are detected automatically and |
| 22 | +the passphrase is requested interactively. Otherwise, one or more |
| 23 | +[IDENTITIES][RECIPIENTS AND IDENTITIES] specified with `-i`/`--identity` are |
| 24 | +used to decrypt the file. |
| 25 | + |
| 26 | +`age` encrypted files are binary and not malleable, with around 200 bytes of |
| 27 | +overhead per recipient, plus 16 bytes every 64KiB of plaintext. |
| 28 | + |
| 29 | +## OPTIONS |
| 30 | + |
| 31 | +* `-o`, `--output`=<OUTPUT>: |
| 32 | + Write encrypted or decrypted file to <OUTPUT> instead of standard output. |
| 33 | + If <OUTPUT> already exists it will be overwritten. |
| 34 | + |
| 35 | + If encrypting without `--armor`, `age` will refuse to output binary to a |
| 36 | + TTY. This can be forced by specifying `-` as <OUTPUT>. |
| 37 | + |
| 38 | +* `--version`: |
| 39 | + Print the version and exit. |
| 40 | + |
| 41 | +### Encryption options |
| 42 | + |
| 43 | +* `-e`, `--encrypt`: |
| 44 | + Encrypt <INPUT> to <OUTPUT>. This is the default. |
| 45 | + |
| 46 | +* `-r`, `--recipient`=<RECIPIENT>: |
| 47 | + Encrypt to the explicitly specified <RECIPIENT>. See the |
| 48 | + [RECIPIENTS AND IDENTITIES][] section for possible recipient formats. |
| 49 | + |
| 50 | + This option can be repeated and combined with `-R`/`--recipients-file`, |
| 51 | + and the file can be decrypted by all provided recipients independently. |
| 52 | + |
| 53 | +* `-R`, `--recipients-file`=<PATH>: |
| 54 | + Encrypt to the [RECIPIENTS][RECIPIENTS AND IDENTITIES] listed in the |
| 55 | + file at <PATH>, one per line. Empty lines and lines starting with `#` |
| 56 | + are ignored as comments. |
| 57 | + |
| 58 | + If <PATH> is `-`, the recipients are read from standard input. In |
| 59 | + this case, the <INPUT> argument must be specified. |
| 60 | + |
| 61 | + This option can be repeated and combined with `-r`/`--recipient`, |
| 62 | + and the file can be decrypted by all provided recipients independently. |
| 63 | + |
| 64 | +* `-p`, `--passphrase`: |
| 65 | + Encrypt with a passphrase, requested interactively from the terminal. |
| 66 | + `age` will offer to auto-generate a secure passphrase. |
| 67 | + |
| 68 | + This options can't be used with `-r`/`--recipient` or |
| 69 | + `-R`/`--recipients-file`. |
| 70 | + |
| 71 | +* `-a`, `--armor`: |
| 72 | + Encrypt to an ASCII-only "armored" encoding. |
| 73 | + |
| 74 | + `age` armor is a strict version of PEM with type `AGE ENCRYPTED FILE`, |
| 75 | + canonical "strict" Base64, no headers, and no support for leading and |
| 76 | + trailing extra data. |
| 77 | + |
| 78 | + Decryption transparently detects and decodes ASCII armoring. |
| 79 | + |
| 80 | +### Decryption options |
| 81 | + |
| 82 | +* `-d`, `--decrypt`: |
| 83 | + Decrypt <INPUT> to <OUTPUT>. |
| 84 | + |
| 85 | + If <INPUT> is passphrase encrypted, it will be automatically detected |
| 86 | + and the passphrase will be requested interactively. Otherwise, the |
| 87 | + [IDENTITIES][RECIPIENTS AND IDENTITIES] specified with `-i`/`--identity` |
| 88 | + are used. |
| 89 | + |
| 90 | + ASCII armoring is transparently detected and decoded. |
| 91 | + |
| 92 | +* `-i`, `--identity`=<PATH>: |
| 93 | + Decrypt using the [IDENTITIES][RECIPIENTS AND IDENTITIES] at <PATH>. |
| 94 | + |
| 95 | + <PATH> may be one of the following: |
| 96 | + |
| 97 | + a\. A file listing [IDENTITIES][RECIPIENTS AND IDENTITIES] one per line. |
| 98 | + Empty lines and lines starting with "`#`" are ignored as comments. |
| 99 | + |
| 100 | + b\. An SSH private key file, in PKCS#1, PKCS#8, SEC 1, or OpenSSH format. |
| 101 | + If the private key is password-protected, the password is requested |
| 102 | + interactively only if the SSH identity matches the file. See the |
| 103 | + [SSH keys][] section for more information, including supported key types. |
| 104 | + |
| 105 | + c\. "`-`", causing one of the options above to be read from standard input. |
| 106 | + In this case, the <INPUT> argument must be specified. |
| 107 | + |
| 108 | + This option can be repeated. Identities are tried in the order in which |
| 109 | + are provided, and the first one matching one of the file's recipients is |
| 110 | + used. Unused identities are ignored. |
| 111 | + |
| 112 | + If `-e`/`--encrypt` is explicitly specified (to avoid confusion), |
| 113 | + `-i`/`--identity` may also be used to encrypt to the `RECIPIENTS` |
| 114 | + corresponding to the `IDENTITIES` listed at <PATH>. This allows using an |
| 115 | + identity file as a symmetric key, if desired. |
| 116 | + |
| 117 | +## RECIPIENTS AND IDENTITIES |
| 118 | + |
| 119 | +`RECIPIENTS` are public values, like a public key, that a file can be encrypted |
| 120 | +to. `IDENTITIES` are private values, like a private key, that allow decrypting |
| 121 | +a file encrypted to the corresponding `RECIPIENT`. |
| 122 | + |
| 123 | +### Native X25519 keys |
| 124 | + |
| 125 | +Native `age` key pairs are generated with age-keygen(1), and provide small |
| 126 | +encodings and strong encryption based on X25519. They are the recommended |
| 127 | +recipient type for most applications. |
| 128 | + |
| 129 | +A `RECIPIENT` encoding begins with `age1` and looks like the following: |
| 130 | + |
| 131 | + age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh |
| 132 | + |
| 133 | +An `IDENTITY` encoding begins with `AGE-SECRET-KEY-1` and looks like the |
| 134 | +following: |
| 135 | + |
| 136 | + AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ |
| 137 | + |
| 138 | +An encrypted file can't be linked to the native recipient it's encrypted to |
| 139 | +without access to the corresponding identity. |
| 140 | + |
| 141 | +### SSH keys |
| 142 | + |
| 143 | +As a convenience feature, `age` also supports encrypting to RSA or Ed25519 |
| 144 | +ssh(1) keys. RSA keys must be at least 2048 bits. This feature employs more |
| 145 | +complex cryptography, and should only be used when a native key is not available |
| 146 | +for the recipient. Note that SSH keys might not be protected long-term by the |
| 147 | +recipient, since they are revokable when used only for authentication. |
| 148 | + |
| 149 | +A `RECIPIENT` encoding is an SSH public key in `authorized_keys` format |
| 150 | +(see the `AUTHORIZED_KEYS FILE FORMAT` section of sshd(8)), starting with |
| 151 | +`ssh-rsa` or `ssh-ed25519`, like the following: |
| 152 | + |
| 153 | + ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8= |
| 154 | + ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa |
| 155 | + |
| 156 | +The comment at the end of the line, if present, is ignored. |
| 157 | + |
| 158 | +In recipient files passed to `-R`/`--recipients-file`, unsupported but valid |
| 159 | +SSH public keys are ignored with a warning, to facilitate using |
| 160 | +`authorized_keys` or GitHub `.keys` files. (See [EXAMPLES][].) |
| 161 | + |
| 162 | +An `IDENTITY` is an SSH private key _file_ passed individually to |
| 163 | +`-i`/`--identity`. Note that keys held on hardware tokens such as YubiKeys |
| 164 | +or accessed via ssh-agent(1) are not supported. |
| 165 | + |
| 166 | +An encrypted file _can_ be linked to the SSH public key it was encrypted to. |
| 167 | +This is so that `age` can identify the correct SSH private key before |
| 168 | +requesting its password, if any. |
| 169 | + |
| 170 | +## EXAMPLES |
| 171 | + |
| 172 | +Generate a new identity, encrypt data, and decrypt: |
| 173 | + |
| 174 | + $ age-keygen -o key.txt |
| 175 | + Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p |
| 176 | + |
| 177 | + $ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age |
| 178 | + |
| 179 | + $ age -d -o data.tar.gz -i key.txt data.tar.gz.age |
| 180 | + |
| 181 | +Encrypt `example.jpg` to multiple recipients and output to `example.jpg.age`: |
| 182 | + |
| 183 | + $ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \ |
| 184 | + -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg |
| 185 | + |
| 186 | +Encrypt to a list of recipients: |
| 187 | + |
| 188 | + $ cat > recipients.txt |
| 189 | + # Alice |
| 190 | + age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p |
| 191 | + # Bob |
| 192 | + age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg |
| 193 | + |
| 194 | + $ age -R recipients.txt example.jpg > example.jpg.age |
| 195 | + |
| 196 | +Encrypt and decrypt a file using a passphrase: |
| 197 | + |
| 198 | + $ age -p secrets.txt > secrets.txt.age |
| 199 | + Enter passphrase (leave empty to autogenerate a secure one): |
| 200 | + Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train". |
| 201 | + |
| 202 | + $ age -d secrets.txt.age > secrets.txt |
| 203 | + Enter passphrase: |
| 204 | + |
| 205 | +Encrypt and decrypt with an SSH public key: |
| 206 | + |
| 207 | + $ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age |
| 208 | + |
| 209 | + $ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg |
| 210 | + |
| 211 | +Encrypt to the SSH keys of a GitHub user: |
| 212 | + |
| 213 | + $ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age |
| 214 | + |
| 215 | +## SEE ALSO |
| 216 | + |
| 217 | +age-keygen(1) |
| 218 | + |
| 219 | +## AUTHORS |
| 220 | + |
| 221 | +Filippo Valsorda <[email protected]> |
0 commit comments