nervuri
/
NetSigil
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

better README

This commit is contained in:
nervuri 2021-03-21 17:19:23 +00:00
parent e6d37b204b
commit c212abe0af
1 changed files with 40 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
README.md
View File

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