From c212abe0afb3afe3fbebfceaa6f03fc110bb8599 Mon Sep 17 00:00:00 2001
From: nervuri <seva@nervuri.net>
Date: Sun, 21 Mar 2021 17:19:23 +0000
Subject: [PATCH] better README

---
 README.md | 47 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 1b2616b..75529ed 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,9 @@
 # NetSigil
 
+NetSigil signs directories and verifies directory signatures.  This allows you and others to detect tampering by whoever might have access to wherever you upload them (hosting provider, attackers, etc).  Use it to:
+
 * Sign an entire [Website]/[Gemini capsule]/[Gopher hole]
-* Verify any file on a signed [Website]/[Gemini capsule]/[Gopher hole]
-
-Uses [signify](https://www.openbsd.org/papers/bsdcan-signify.html).  GPG support might be added later.
-
-Generates `.well-known/signature-bundle`, a signed tar.gz file.
-
-Explained here: https://lists.orbitalfox.eu/archives/gemini/2021/005585.html
+* Verify any file on a signed [Website]/[Gemini capsule]/[Gopher hole] - **not yet implemented**
 
 Usage:
 
@@ -15,3 +11,40 @@ Usage:
 netsigil --sign <dir>    # Sign a local copy of your site
 netsigil --verify <URL>  # Verify remote signature
 ```
+
+Uses [signify](https://www.openbsd.org/papers/bsdcan-signify.html).  GPG support might be added later.
+
+Generates `.well-known/signature-bundle`, a signed tar.gz file.
+
+Best used within a script that synchronizes local files with the server.  This is [how I use it](https://gitlab.com/nervuri/nervuri.net/-/blob/master/sync.sh#L10).
+
+## How it works
+
+### Signing
+
+1. Walks you through installing `signify` and generating a keypair.
+2. Generates a SHA256SUMS file containing hashes of all files in a directory, including subdirectories.
+3. Puts the public key and the SHA256SUMS file into an archive which it then signs using signify's `-z` option, which embeds the signature in the gzip header.
+
+### Verifying
+
+Verification is not yet implemented, but can be done manually.  Here is an example for the Gemini protocol (using [agunua](https://framagit.org/bortzmeyer/agunua) to download files):
+
+```
+# Download `signature-bundle`
+agunua --insecure --binary gemini://rawtext.club/~nervuri/.well-known/signature-bundle > signature-bundle
+# Extract the public key
+tar -xf signature-bundle key.pub
+# Verify `signature-bundle`
+signify -Vz -p key.pub -x signature-bundle >/dev/null && echo 'Signature OK'
+# Extract `SHA256SUMS`
+tar -xf signature-bundle SHA256SUMS
+# Download two files from the capsule, mirroring the directory structure
+agunua --insecure --binary gemini://rawtext.club/~nervuri/contact.gmi > contact.gmi
+mkdir keys && agunua --insecure --binary gemini://rawtext.club/~nervuri/keys/index.gmi > keys/index.gmi
+# Verify them both
+sha256sum -c --ignore-missing SHA256SUMS
+```
+---
+
+The idea for this program spawned [on the Gemini mailing list](https://lists.orbitalfox.eu/archives/gemini/2021/005585.html).  Special thanks to [Christophe Henry](https://gmi.sbgodin.fr/) and [Francesco Camuffo](https://fmac.xyz/).