From b194267aaa208277d92745842f5c966ded326af5 Mon Sep 17 00:00:00 2001
From: Filippo Valsorda <1225294+FiloSottile@users.noreply.github.com>
Date: Mon, 30 Dec 2019 02:24:38 +0100
Subject: [PATCH] README: add more usage examples

---
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index dbca57b..6e202da 100644
--- a/README.md
+++ b/README.md
@@ -8,10 +8,12 @@ It features small explicit keys, no config options, and UNIX-style composability
 $ age-keygen -o key.txt
 Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
 $ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
-$ age -d -i key.txt -o data.tar.gz data.tar.gz.age
+$ age -d -i key.txt data.tar.gz.age > data.tar.gz
 ```
 
-The format specification is at [age-encryption.org/v1](https://age-encryption.org/v1). To discuss the spec or other age related topics, please email the mailing list at age-dev@googlegroups.com. Subscribe at [groups.google.com/d/forum/age-dev](https://groups.google.com/d/forum/age-dev) or by emailing age-dev+subscribe@googlegroups.com.
+The format specification is at [age-encryption.org/v1](https://age-encryption.org/v1). To discuss the spec or other age related topics, please email [the mailing list](https://groups.google.com/d/forum/age-dev) at age-dev@googlegroups.com. age was designed by [@Benjojo12](https://twitter.com/Benjojo12) and [@FiloSottile](https://twitter.com/FiloSottile).
+
+An alternative interoperable Rust implementation is available at [github.com/str4d/rage](https://github.com/str4d/rage).
 
 ## Usage
 
@@ -38,6 +40,40 @@ KEY is a path to a file with age secret keys, one per line
 Multiple keys can be provided, and any unused ones will be ignored.
 ```
 
+### Multiple recipients
+
+Files can be encrypted to multiple recipients by repeating `-r/--recipient`. Every recipient will be able to decrypt the file.
+
+```
+$ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
+    -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg
+```
+
+### Passphrases
+
+Files can be encrypted with a passphrase by using `-p/--passphrase`. By default age will automatically generate a secure passphrase. Passphrase protected files are automatically detected at decrypt time.
+
+```
+$ age -p secrets.txt > secrets.txt.age
+Enter passphrase (leave empty to autogenerate a secure one):
+Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".
+$ age -d secrets.txt.age > secrets.txt
+Enter passphrase:
+```
+
+### SSH keys
+
+As a convenience feature, age also supports encrypting to `ssh-rsa` and `ssh-ed25519` SSH public keys, and decrypting with the respective private key file. (`ssh-agent` is not supported.)
+
+```
+$ cat ~/.ssh/id_ed25519.pub
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIZDRcvS8PnhXr30WKSKmf7WKKi92ACUa5nW589WukJz filippo@Bistromath.local
+$ age -r "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIZDRcvS8PnhXr30WKSKmf7WKKi92ACUa5nW589WukJz" example.jpg > example.jpg.age
+$ age -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg
+```
+
+Note that SSH key support employs more complex cryptography, and embeds a public key tag in the encrypted file, making it possible to track files that are encrypted to a specific public key.
+
 ## Installation
 
 On macOS or Linux, you can use Homebrew:
@@ -56,4 +92,10 @@ git clone https://filippo.io/age && cd age
 go build -o . filippo.io/age/cmd/...
 ```
 
+On OpenBSD -current and 6.7+, you can use the port:
+
+```
+pkg_add age
+```
+
 Help from new packagers is very welcome.