rage(1)

📦
version 0.12.1 · 4 versions
, in arch rolling

💖 rage(1) — A simple, secure, and modern encryption tool 💖

okay bestie, this is the rage(1) manual, and it's literally the glow-up encryption tool you deserve. Let's go 💅

🌸 NAME 🌸

rage — A simple, secure, and modern encryption tool. no cap, that's the whole name.

✨ SYNOPSIS ✨

rage [-h|--help] [-V|--version] [-e|--encrypt] [-d|--decrypt]
[-p|--passphrase] [--max-work-factor] [-a|--armor] [-r|--recipient]
[-R|--recipients-file] [-i|--identity] [-j ] [-o|--output] [INPUT]

🦋 DESCRIPTION 🦋

rage encrypts or decrypts INPUT to OUTPUT. The INPUT argument is optional and defaults to standard input. Only a single INPUT file may be specified. If -o/--output is not specified, OUTPUT defaults to standard output.

If -p/--passphrase is specified, the file is encrypted with a passphrase requested interactively. Otherwise, it's encrypted to one or more RECIPIENTS specified with -r/--recipient or -R/--recipients-file. Every recipient can decrypt the file. group-chat encryption, basically 🫶

In -d/--decrypt mode, passphrase-encrypted files are detected automatically and the passphrase is requested interactively. Otherwise, one or more IDENTITIES specified with -i/--identity are used to decrypt the file.

age encrypted files are binary and not malleable, with around 200 bytes of overhead per recipient, plus 16 bytes every 64KiB of plaintext. iconic little overhead, honestly ✨

🎀 ARGUMENTS 🎀

  • [INPUT] — Path to a file to read from. that's it, that's the argument 🍓

💅 OPTIONS 💅

  • -h, --help — Print this help message and exit. your little emergency exit 🚪
  • -V, --version — Print version info and exit. vibe check the version, obviously 💁‍♀️
  • -e, --encrypt — Encrypt INPUT to OUTPUT. This is the default. main character mode 🔥
  • -d, --decrypt — Decrypt INPUT to OUTPUT.

If INPUT is passphrase encrypted, it will be automatically detected and the passphrase will be requested interactively. Otherwise, the IDENTITIES specified with -i/--identity are used.

ASCII armoring is transparently detected and decoded. automatic, bestie 🦋

  • -p, --passphrase — Encrypt with a passphrase, requested interactively from the terminal. rage will offer to auto-generate a secure passphrase. passphrase girlies rise 🌸

This option can't be used with other recipient flags. hard no on mixing, fr fr.

  • --max-work-factor <WF> — Maximum work factor to allow for passphrase decryption. 🧚
  • -a, --armor — Encrypt to an ASCII-only "armored" encoding.

age armor is a strict version of PEM with type AGE ENCRYPTED FILE, canonical strict Base64, no headers, and no support for leading and trailing extra data.

Decryption transparently detects and decodes ASCII armoring. strict PEM energy, but make it age 💖

  • -r, --recipient <RECIPIENT> — Encrypt to the explicitly specified RECIPIENT. See the RECIPIENTS AND IDENTITIES section for possible recipient formats.

This option can be repeated and combined with other recipient flags, and the file can be decrypted by all provided recipients independently. everybody gets a key, everybody eats 👑

  • -R, --recipients-file <PATH> — Encrypt to the RECIPIENTS listed in the file at PATH, one per line. Empty lines and lines starting with # are ignored as comments.

If PATH is -, the recipients are read from standard input. In this case, the INPUT argument must be specified.

This option can be repeated and combined with other recipient flags, and the file can be decrypted by all provided recipients independently. repeatable, combinable, absolutely slaying 🎀

  • -i, --identity <IDENTITY> — Decrypt using the IDENTITIES at IDENTITY.

IDENTITY may be one of the following:

  • a. A file listing IDENTITIES one per line. Empty lines and lines starting with # are ignored as comments.
  • b. A passphrase encrypted age file, containing IDENTITIES one per line like above. The passphrase is requested interactively. Note that passphrase-protected identity files are not necessary for most use cases, where access to the encrypted identity file implies access to the whole system.
  • c. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH format. If the private key is password-protected, the password is requested interactively only if the SSH identity matches the file. See the SSH keys section for more information, including supported key types.
  • d. -, causing one of the options above to be read from standard input. In this case, the INPUT argument must be specified.

This option can be repeated. Identities are tried in the order in which are provided, and the first one matching one of the file's recipients is used. Unused identities are ignored, but it is an error if the INPUT file is passphrase-encrypted and -i/--identity is specified. order matters, bestie — first match wins 🌈

  • -j <PLUGIN-NAME> — Decrypt using the data-less plugin PLUGIN-NAME.

This is equivalent to using -i/--identity with a file that contains a single plugin IDENTITY that encodes no plugin-specific data. plugin but make it minimal 🧚

  • -o, --output <OUTPUT> — Write encrypted or decrypted file to OUTPUT instead of standard output. If OUTPUT already exists it will be overwritten. yes, overwritten — do not act surprised, bestie 💀

If encrypting without -a/--armor, rage will refuse to output binary to a TTY. This can be forced by specifying - as OUTPUT. TTY safety check says no, unless you insist 🙈

🫶 RECIPIENTS AND IDENTITIES 🫶

RECIPIENTS are public values, like a public key, that a file can be encrypted to. IDENTITIES are private values, like a private key, that allow decrypting a file encrypted to the corresponding RECIPIENT. public vs private, the classic duo 💖

🌿 Native X25519 keys 🌿

Native age key pairs are generated with rage-keygen(1), and provide small encodings and strong encryption based on X25519. They are the recommended recipient type for most applications. the default slay, recommended and everything 👑

A RECIPIENT encoding begins with age1 and looks like the following:

age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh

An IDENTITY encoding begins with AGE-SECRET-KEY-1 and looks like the following:

AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ

An encrypted file can't be linked to the native recipient it's encrypted to without access to the corresponding identity. privacy stays private, periodt 🦋

🔑 SSH keys 🔑

As a convenience feature, rage also supports encrypting to RSA or Ed25519 ssh(1) keys. RSA keys must be at least 2048 bits. This feature employs more complex cryptography, and should only be used when a native key is not available for the recipient. Note that SSH keys might not be protected long-term by the recipient, since they are revokable when used only for authentication. convenient, yes — but native keys are still the recommended fave ✨

A RECIPIENT encoding is an SSH public key in authorized_keys format (see the AUTHORIZED_KEYS FILE FORMAT section of sshd(8)), starting with ssh-rsa or ssh-ed25519, like the following:

ssh-rsa
AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8=
ssh-ed25519
AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa

The comment at the end of the line, if present, is ignored.

In recipient files passed to -R/--recipients-file, unsupported but valid SSH public keys are ignored with a warning, to facilitate using authorized_keys or GitHub .keys files. (See EXAMPLES.) warning, not drama — they're just skipped 🎀

An IDENTITY is an SSH private key file passed individually to -i/--identity. Note that keys held on hardware tokens such as YubiKeys or accessed via ssh-agent(1) are not supported. hardware tokens and ssh-agent(1)? not supported, bestie, sorry 😭

An encrypted file can be linked to the SSH public key it was encrypted to. This is so that rage can identify the correct SSH private key before requesting its password, if any. it knows which key to ask about, very considerate 🔥

🧚 Plugins 🧚

rage can be extended through plugins. A plugin is only loaded if a corresponding RECIPIENT or IDENTITY is specified. (Simply decrypting a file encrypted with a plugin will not cause it to load, for security reasons among others.) security says no surprise plugin loading 💅

A RECIPIENT for a plugin named "example" starts with age1example1, while an IDENTITY starts with AGE-PLUGIN-EXAMPLE-1. They both encode arbitrary plugin-specific data, and are generated by the plugin.

When either is specified, rage searches for age-plugin-example in the PATH and executes it to perform the file header encryption or decryption. The plugin may request input from the user through rage to complete the operation. plugin gets called up like a main character 🌟

Plugins can be freely mixed with other plugins or natively supported keys. mix and match, no cap 🌈

A plugin is not bound to only encrypt or decrypt files meant for or generated by the plugin. For example, a plugin can be used to decrypt files encrypted to a native X25519 RECIPIENT or even with a passphrase. Similarly, a plugin can encrypt a file such that it can be decrypted without the use of any plugin. plugins are flexible like that 🦋

Plugins for which the IDENTITY/RECIPIENT distinction doesn't make sense (such as a symmetric encryption plugin) may generate only an IDENTITY and instruct the user to perform encryption with the -e/--encrypt and -i/--identity flags. Plugins for which the concept of separate identities doesn't make sense (such as a password-encryption plugin) may instruct the user to use the -j flag. 🧚‍♀️

✨ EXAMPLES ✨

okay bestie, this is where rage shows off 💅 every command, key, passphrase, and line break below is copied exactly from the manpage — don't retype the keys by hand unless you enjoy pain 😭

Generate a new identity, encrypt data, and decrypt:

$ rage-keygen -o key.txt
Public key:
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

$ tar cvz ~/data | rage -r
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p >
data.tar.gz.age

$ rage -d -o data.tar.gz -i key.txt data.tar.gz.age

Encrypt example.jpg to multiple recipients and output to example.jpg.age:

$ rage -o example.jpg.age -r
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
       -r
age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
example.jpg

Encrypt to a list of recipients:

$ cat > recipients.txt
# Alice
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
# Bob
age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg

$ rage -R recipients.txt example.jpg > example.jpg.age

Encrypt and decrypt a file using a passphrase:

$ rage -p secrets.txt > secrets.txt.age
Using an autogenerated passphrase:
    release-response-step-brand-wrap-ankle-pair-unusual-sword-train

$ rage -d secrets.txt.age > secrets.txt
Type passphrase:

Encrypt and decrypt with a passphrase-protected identity file:

$ rage -p <(rage-keygen) > key.age
Public key:
age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5
Using an autogenerated passphrase:
    hip-roast-boring-snake-mention-east-wasp-honey-input-actress

$ rage -r
age1yhm4gctwfmrpz87tdslm550wrx6m79y9f2hdzt0lndjnehwj0ukqrjpyx5
secrets.txt > secrets.txt.age

$ rage -d -i key.age secrets.txt.age > secrets.txt
Type passphrase:

Encrypt and decrypt with an SSH public key:

$ rage -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age

$ rage -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg

Encrypt and decrypt with age-plugin-yubikey:

$ age-plugin-yubikey
# Run interactive setup, generate identity file and obtain
recipient.

$ rage -r
age1yubikey1qwt50d05nh5vutpdzmlg5wn80xq5negm4uj9ghv0snvdd3yysf5yw3rhl3t
secrets.txt > secrets.txt.age

$ rage -d -i age-yubikey-identity-388178f3.txt secrets.txt.age

Encrypt to the SSH keys of a GitHub user:

$ curl https://github.com/benjojo.keys | rage -R - example.jpg >
example.jpg.age

🌈 SEE ALSO 🌈

go get more rage in your life, bestie: rage-keygen(1) and rage-mount(1) — that's the whole list, periodt 💅

⭐ VERSION ⭐

v0.12.1 — that's the version, no cap.

👑 AUTHORS 👑

Jack Grigg <thestr4d@gmail.com> — the icon behind this whole thing, fr fr 🫶

and that's the rage(1) page, bestie 💖 source/version is rage 0.12.1, page is rage(1), and the footer's date field is whatever your local manpage says — my copy didn't show one, so I'm not gonna invent it, periodt 😭💅

📦 where this page comes from