161 lines
4.4 KiB
Markdown
161 lines
4.4 KiB
Markdown
# Sig #
|
|
|
|
The simple GPG signature toolchain for directories or git repos.
|
|
|
|
## Features
|
|
|
|
* Generate sha256 manifest for all files in directory
|
|
* Use git for listing if available
|
|
* Add detached signatures to manifest
|
|
* Verify manifest has a minimum threshold of unique detached signatures
|
|
* Verify git history contains a minimum threshold of unique commit siguatures
|
|
* Verify signatures belong to a defined GPG alias group
|
|
|
|
## Install
|
|
|
|
1. Clone
|
|
|
|
```
|
|
git clone git@gitlab.com/pchq/sig.git sig
|
|
```
|
|
|
|
2. Manually generate manifest
|
|
|
|
```
|
|
git ls-files \
|
|
| grep -v .sig \
|
|
| xargs openssl sha256 -r \
|
|
| sed -e 's/ \*/ /g' -e 's/ \.\// /g'
|
|
```
|
|
|
|
3. Manually verify manifest
|
|
|
|
```
|
|
for file in .sig/*.asc; do gpg --verify $file .sig/manifest.txt; done
|
|
gpg log --show-signature
|
|
less sig
|
|
```
|
|
|
|
4. Self verify
|
|
|
|
```
|
|
./sig verify --threshold 3
|
|
```
|
|
|
|
5. Copy to $PATH
|
|
|
|
```
|
|
cp sig ~/.local/bin/
|
|
```
|
|
|
|
## Methods
|
|
|
|
### Git
|
|
|
|
This method verifies a git repo contains signed commits by one or more authors.
|
|
|
|
If 'threshold' is specified, it searches history until enough unique signatures
|
|
are found to satisify the threshold, ensuring all commits between are signed.
|
|
|
|
If 'group' is specified, all signatures must be by keys that belong to a
|
|
defined gpg alias group.
|
|
|
|
Note: this only proves the history had multiple participants, but not that
|
|
the current HEAD was verified by all participants.
|
|
|
|
#### Assumptions
|
|
- Single sig mode: Repo HEAD controlled by signer
|
|
- Multi-sig mode: Repo has contributions from multiple individuals
|
|
- Multi-sig group mode: Repo has contributions from specified individuals
|
|
- Sha1 is not broken
|
|
|
|
### Detached
|
|
|
|
This method verifies the state of this folder was signed exactly as-is by one
|
|
or more authors.
|
|
|
|
If 'threshold' is specified, then that number of signatures must be present.
|
|
|
|
If 'group' is specified, all signatures must be by keys that belong to a
|
|
defined gpg alias group.
|
|
|
|
#### Assumptions
|
|
- Single sig mode: Folder contents controlled by signer
|
|
- Multi-sig mode: Folder contents verified by multiple signers
|
|
- Multi-sig group mode: Folder contents approved by specified individuals
|
|
- Sha256 is not broken
|
|
|
|
## Usage
|
|
|
|
* sig verify [-g,--group=<group>] [-t,--threshold=<N>] [-m,--method=<git|detached> ]
|
|
* Verify m-of-n signatures by given group are present for directory
|
|
* sig add
|
|
* Add signature to manifest for this directory
|
|
* sig manifest
|
|
* Generate hash manifest for this directory
|
|
* sig help
|
|
* Show help text.
|
|
* sig version
|
|
* Show version information.
|
|
|
|
|
|
## Examples
|
|
|
|
#### Verify 1 signature via Detached and Git methods
|
|
|
|
```
|
|
sig verify
|
|
```
|
|
|
|
#### Verify 2 unique signatures via Detached and Git methods
|
|
|
|
```
|
|
sig verify --threshold 2
|
|
```
|
|
|
|
#### Verify 3 unique signatures from specified signing group via Git method
|
|
|
|
```
|
|
sig verify --threshold 2 --group myteam --method git
|
|
```
|
|
|
|
#### Add Detached Signature
|
|
|
|
```
|
|
sig add
|
|
```
|
|
|
|
## Frequently Asked Questions
|
|
|
|
### Why Bash?
|
|
|
|
Because it is easy to quickly verify at any time, has wide OS compatibility andthe majority of the needed operations are calling other programs already on
|
|
your system like gpg and openssl.
|
|
|
|
If this were in another language it would be harder to audit on the fly, would
|
|
require the user to have a specific language toolchain installed, and it would
|
|
still mostly just be a bunch of shell executions to call system binaries
|
|
anyway.
|
|
|
|
### Why PGP?
|
|
|
|
In spite of many popular claims to the contrary, PGP is still the most well
|
|
supported protocol for distribution, verification, and signing for keys held
|
|
by individual humans. It is also the only protocoal with wide HSM support
|
|
allowing you to keep keys out of system memory and requier physical approval
|
|
for each operation. E.G a trezor, ledger, or yubikey.
|
|
|
|
Popular alternatives like signify or straight openssl have poor support for
|
|
these workflows.
|
|
|
|
Admittedly the GnuPG codebase itself is a buggy dated mess, but PGP as a spec
|
|
is still Pretty Good for many use cases. A recent modern rewrite by a number
|
|
of former GnuPG team members is near complete and set to give PGP a long and
|
|
stable future.
|
|
|
|
See: https://sequoia-pgp.org/
|
|
|
|
The only promising alternative to GnuPG for software signing that has hsm
|
|
support and the very attractive feature of expiring signatures is [The Update Framework](https://theupdateframework.io) which may be supported as an alternate
|
|
method in the future if m-of-n multisig is ever implemented.
|