71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
# NetSigil
|
|
|
|
NetSigil signs directories and verifies directory signatures. It allows anyone to check if files on a server have been tampered with (by the 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] - **not yet implemented**
|
|
|
|
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.
|
|
|
|
## How it works
|
|
|
|
### Signing
|
|
|
|
0. Walks you through installing `signify`, if not already installed ([apt](https://en.wikipedia.org/wiki/Advanced_Packaging_Tool) only, for now).
|
|
1. Walks you through generating a keypair; stores keys in `$XDG_DATA_HOME/signify/` (or `~/.local/share/signify/`).
|
|
2. Generates a `SHA256SUMS` file containing hashes of all files in the specified directory (including subdirectories).
|
|
3. Puts `key.pub` and `SHA256SUMS` into a tar.gz archive.
|
|
4. Signs the archive, embedding the signature in the gzip header.
|
|
5. Saves the signed archive within the directory, as `.well-known/signature-bundle`.
|
|
|
|
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).
|
|
|
|
### Verifying
|
|
|
|
Verification is not yet implemented, but here is an approximation of how it will work:
|
|
|
|
0. User runs `netsigil --verify scheme://example.org:port/~user/file`.
|
|
1. Download `scheme://example.org:port/~user/file`.
|
|
2. If we already have a `SHA256SUMS` file for `scheme://example.org:port/~user`, then go to 7.
|
|
3. Download `scheme://example.org:port/~user/.well-known/signature-bundle`.
|
|
4. If not already present, extract `key.pub` from `signature-bundle` and store it locally (Trust on first use).
|
|
5. Use `key.pub` to verify `signature-bundle`.
|
|
6. Extract `SHA256SUMS` from `signature-bundle` and store it locally.
|
|
7. Check if the hash of `file` matches the one in `SHA256SUMS`. If it does, stop here. Perhaps output the requested file to stdout.
|
|
8. On hash mismatch: if step 2 was true, then go to step 3; else, stop.
|
|
|
|
Note that in this example, `.well-known` is under `~user`, not directly under `example.org`. This is to account for multi-user systems (pubnixes/tilde communities).
|
|
|
|
Verification can also 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
|
|
```
|
|
|
|
## Contributing
|
|
|
|
If you don't want to [make an account here](https://tildegit.org/user/sign_up), just shoot me an email: https://nervuri.net/contact
|
|
|
|
---
|
|
|
|
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/).
|