From 3044cfe932a18be2dbdc9ae7a8166006c6857485 Mon Sep 17 00:00:00 2001 From: Roman Zeyde Date: Mon, 26 Dec 2022 21:26:32 +0200 Subject: [PATCH] age: add more documentation and examples --- README.md | 9 +++--- doc/README-GPG.md | 2 +- doc/README-age.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 83 insertions(+), 5 deletions(-) create mode 100644 doc/README-age.md diff --git a/README.md b/README.md index fd08dce..6f9a828 100644 --- a/README.md +++ b/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) diff --git a/doc/README-GPG.md b/doc/README-GPG.md index 8a46955..3542ec4 100644 --- a/doc/README-GPG.md +++ b/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`: diff --git a/doc/README-age.md b/doc/README-age.md new file mode 100644 index 0000000..ad53282 --- /dev/null +++ b/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. +```