git-sig/README.md

131 lines
2.9 KiB
Markdown
Raw Normal View History

2020-11-16 12:21:30 +00:00
# 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
2020-11-16 12:31:25 +00:00
```
git clone git@gitlab.com/pchq/sig.git sig
```
2020-11-16 12:21:30 +00:00
2020-11-16 12:36:05 +00:00
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
2020-11-16 12:31:25 +00:00
```
for file in .sig/*.asc; do gpg --verify $file .sig/manifest.txt; done
gpg log --show-signature
less sig
```
2020-11-16 12:21:30 +00:00
2020-11-16 12:36:05 +00:00
4. Self verify
2020-11-16 12:31:25 +00:00
```
./sig verify --threshold 3
```
2020-11-16 12:21:30 +00:00
2020-11-16 12:36:05 +00:00
5. Copy to $PATH
2020-11-16 12:31:25 +00:00
```
cp sig ~/.local/bin/
```
2020-11-16 12:21:30 +00:00
## 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
2020-11-16 12:43:14 +00:00
#### 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
2020-11-16 12:21:30 +00:00
```
sig verify
```
2020-11-16 12:43:14 +00:00
#### Verify 2 unique signatures via Detached and Git methods
2020-11-16 12:21:30 +00:00
```
sig verify --threshold 2
```
2020-11-16 12:43:14 +00:00
#### Verify 3 unique signatures from specified signing group via Git method
2020-11-16 12:21:30 +00:00
```
sig verify --threshold 2 --group myteam --method git
```
2020-11-16 12:43:14 +00:00
#### Add Detached Signature
2020-11-16 12:21:30 +00:00
```
sig add
```