better README

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/).

netsigil

@@ -13,7 +13,7 @@ set -o nounset  # -u
 
 finish() {
   # Clean up on exit
-  rm -rf $tempdir
+  rm -rf "${tempdir:-netsigil_tempdir_not_set}"
 }
 trap finish EXIT
 
@@ -89,9 +89,11 @@ if [ "$action" = 'sign' ]; then
   # Copy public key to temporary directory
   cp "$public_key" "$tempdir/key.pub"
 
+  # Remove the old signature-bundle, if it exists
+  rm -f .well-known/signature-bundle
+
   # Generate SHA256SUMS file
-  find -- * -type f -print0 | xargs -0 sha256sum > "$tempdir/SHA256SUMS"
-  # TODO: option to include hidden files
+  find -- . -type f -print | cut -d '/' -f 2- | sort | xargs sha256sum > "$tempdir/SHA256SUMS"
 
   # Go to temporary directory
   cd "$tempdir" || exit 1
@@ -100,7 +102,7 @@ if [ "$action" = 'sign' ]; then
   tar -czf signature-bundle-unsigned --remove-files key.pub SHA256SUMS
 
   # Sign the archive
-  echo "Signing with $datadir/signify/key.sec"
+  echo "Signing \`$target\` with \`$datadir/signify/key.sec\`"
   signify -Sz -s "$secret_key" -m signature-bundle-unsigned -x signature-bundle || exit 1
   rm signature-bundle-unsigned