age: add more documentation and examples

README.md

@@ -1,11 +1,11 @@
-# Hardware-based SSH/GPG agent
+# Hardware-based SSH/GPG/age agent
 
 [![Build](https://github.com/romanz/trezor-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/romanz/trezor-agent/actions)
 [![Chat](https://badges.gitter.im/romanz/trezor-agent.svg)](https://gitter.im/romanz/trezor-agent)
 
-This project allows you to use various hardware security devices to operate GPG and SSH.  Instead of keeping your key on your computer and decrypting it with a passphrase when you want to use it, the key is generated and stored on the device and never reaches your computer.  Read more about the design [here](doc/DESIGN.md).
+This project allows you to use various hardware security devices to operate GPG, SSH and age.  Instead of keeping your key on your computer and decrypting it with a passphrase when you want to use it, the key is generated and stored on the device and never reaches your computer.  Read more about the design [here](doc/DESIGN.md).
 
-You can do things like sign your emails, git commits, and software packages, manage your passwords (with [pass](https://www.passwordstore.org/) and [gopass](https://www.justwatch.com/gopass/), among others), authenticate web tunnels and file transfers, and more.
+You can do things like sign your emails, git commits, and software packages, manage your passwords (with [pass](https://www.passwordstore.org/) and [passage](https://github.com/FiloSottile/passage), among others), authenticate web tunnels and file transfers, and more.
 
 See the following blog posts about this tool:
 
@@ -22,7 +22,7 @@ This repository contains source code for one library as well as
 agents to interact with several different hardware devices:
 
 * [`libagent`](https://pypi.org/project/libagent/): shared library
-* [`trezor-agent`](https://pypi.org/project/trezor-agent/): Using Trezor as hardware-based SSH/PGP agent
+* [`trezor-agent`](https://pypi.org/project/trezor-agent/): Using Trezor as hardware-based SSH/PGP/age agent
 * [`ledger_agent`](https://pypi.org/project/ledger_agent/): Using Ledger as hardware-based SSH/PGP agent
 * [`jade_agent`](https://pypi.org/project/jade_agent/): Using Blockstream Jade as hardware-based SSH/PGP agent
 * [`keepkey_agent`](https://pypi.org/project/keepkey_agent/): Using KeepKey as hardware-based SSH/PGP agent
@@ -40,4 +40,5 @@ releases.
     Note: If you're using Windows, see [trezor-ssh-agent](https://github.com/martin-lizner/trezor-ssh-agent) by Martin Lízner.
 
 * **GPG** instructions and common use cases are [here](doc/README-GPG.md)
+* **age** instructions and common use cases are [here](doc/README-age.md)
 * Instructions to configure a Trezor-style **PIN entry** program are [here](doc/README-PINENTRY.md)

doc/README-GPG.md

@@ -87,7 +87,7 @@ when committing to git.
 
 ### Manage passwords
 
-Password managers such as [pass](https://www.passwordstore.org/) and [gopass](https://www.justwatch.com/gopass/) rely on GPG for encryption so you can use your device with them too.
+Password managers such as [pass](https://www.passwordstore.org/) rely on GPG for encryption so you can use your device with them too.
 
 ##### With `pass`:
 

doc/README-age.md

@@ -0,0 +1,77 @@
+# `age` Agent
+
+Note: the age-related code is still under development, so please try the current implementation
+and please let me [know](https://github.com/romanz/trezor-agent/issues/new) if something doesn't
+work well for you. If possible:
+
+ * record the session (e.g. using [asciinema](https://asciinema.org))
+ * collect the agent log by setting `TREZOR_AGE_PLUGIN_LOG` environment variable
+
+Thanks!
+
+## 1. Configuration
+
+Install [age 1.1.0+](https://github.com/FiloSottile/age/releases/tag/v1.1.0) or [rage 0.9.0+](https://github.com/str4d/rage/releases/tag/v0.9.0).
+
+Generate an identity by running:
+
+```
+$ age-plugin-trezor -i "John Doe" | tee identity
+# recipient: age1wpl78afms4x36mucnd4j65sanrtj9873up47qq39h68q0aw7n4xqdlw6tk
+# SLIP-0017: John Doe
+AGE-PLUGIN-TREZOR-1FFHKSM3QG3HK2PEPD5D
+```
+
+## 2. Usage
+
+### Encrypt
+
+Use the recipient ID from above (see [age](https://github.com/FiloSottile/age#usage)/[rage](https://github.com/str4d/rage#usage) instructions):
+```
+$ date | age -r age1wpl78afms4x36mucnd4j65sanrtj9873up47qq39h68q0aw7n4xqdlw6tk > secret.age
+```
+
+### Decrypt
+
+Make sure `age-plugin-trezor` is installed and available (it will be invoked by `age` for decryption):
+
+```
+$ age -d -i identity < secret.age 
+Mon 26 Dec 2022 21:10:26 IST
+```
+
+### Manage passwords with `passage`
+
+First install `passage` from https://github.com/FiloSottile/passage and initialize it to use your hardware-based identity:
+```
+$ mkdir -p ~/.passage/store
+
+$ age-plugin-trezor -i "John Doe" | tee ~/.passage/identities
+# recipient: age1wpl78afms4x36mucnd4j65sanrtj9873up47qq39h68q0aw7n4xqdlw6tk
+# SLIP-0017: John Doe
+AGE-PLUGIN-TREZOR-1FFHKSM3QG3HK2PEPD5D
+
+$ awk '/# recipient:/ {print $3}' ~/.passage/identities | tee ~/.passage/identities
+age1wpl78afms4x36mucnd4j65sanrtj9873up47qq39h68q0aw7n4xqdlw6tk
+```
+
+```
+$ passage generate Dev/github 32
+$ passage generate Social/hackernews 32
+$ passage generate Social/twitter 32
+$ passage generate VPS/linode 32
+$ passage
+Passage
+├── Dev
+│   └── github
+├── Social
+│   ├── hackernews
+│   └── twitter
+└── VPS
+    └── linode
+```
+In order to paste them into the browser, you'd need to decrypt the password using your hardware device:
+```
+$ passage --clip VPS/linode
+Copied VPS/linode to clipboard. Will clear in 45 seconds.
+```