2018-11-22 15:40:59 +00:00
|
|
|
Hagrid
|
|
|
|
======
|
2018-08-16 18:35:19 +00:00
|
|
|
|
2018-11-22 15:40:59 +00:00
|
|
|
Hagrid is a verifying OpenPGP key server. When a new key is uploaded a
|
2018-09-19 20:27:25 +00:00
|
|
|
token is sent to each user ID via email. This token can be used to verify the
|
|
|
|
user ID. Keys can be queried by their verified user IDs (exact match) and their
|
2019-01-09 13:56:51 +00:00
|
|
|
primary keys fingerprint. Keys can be deleted by clicking a link send to all
|
2018-09-19 20:27:25 +00:00
|
|
|
user IDs.
|
|
|
|
|
|
|
|
Quick Start
|
|
|
|
-----------
|
|
|
|
|
2018-11-22 15:40:59 +00:00
|
|
|
Building Hagrid required a working [Rust _nightly_
|
2018-10-18 14:54:00 +00:00
|
|
|
toolchain](https://rust-lang.org). The key server uses the filesystem to store
|
|
|
|
keys, user IDs and tokens. To run it, supply the absolute path to where you
|
|
|
|
want the database to live and the absolute path to the template directory.
|
2018-09-19 20:27:25 +00:00
|
|
|
|
|
|
|
```bash
|
2019-02-27 08:01:23 +00:00
|
|
|
cargo run --bin hagrid -- `pwd`/dist
|
2018-09-19 20:27:25 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
This will spawn a web server listening on port 8080.
|
|
|
|
|
2019-01-09 13:56:51 +00:00
|
|
|
Hagrid uses `sendmail` for mailing, so you also need a working local mailer
|
|
|
|
setup. The FROM field of the mails can be configured with the `-F` switch.
|
|
|
|
|
2018-09-19 20:27:25 +00:00
|
|
|
Usage
|
|
|
|
-----
|
|
|
|
|
2019-02-28 15:57:03 +00:00
|
|
|
### HKP
|
|
|
|
|
2019-01-09 13:56:51 +00:00
|
|
|
Hagrid implements basic HKP (`op=get` and `op=index`) so tools like GnuPG and
|
|
|
|
OpenKeychain can use it directly. The differences to SKS are
|
2018-09-19 20:27:25 +00:00
|
|
|
|
2019-01-09 13:56:51 +00:00
|
|
|
- no support for `op=vindex`,
|
2019-03-01 09:10:46 +00:00
|
|
|
- only exact matches for user IDs are returned (i.e. `exact=on` is
|
|
|
|
always assumed),
|
|
|
|
- `op=index` returns either one or no keys,
|
|
|
|
- all packets that aren't public keys, user IDs or signatures are filtered out,
|
|
|
|
- Uploading a key via the HKP interface is not supported.
|
2018-09-19 20:27:25 +00:00
|
|
|
|
2019-02-28 15:57:03 +00:00
|
|
|
### VKS
|
|
|
|
|
2019-01-09 13:56:51 +00:00
|
|
|
Hagrid has it's own URL scheme to fetch keys, verify user IDs and delete keys.
|
|
|
|
It's meant to be machine readable, but it's not a REST API. The following URLs
|
|
|
|
are handled.
|
2018-09-19 20:27:25 +00:00
|
|
|
|
2019-02-28 15:57:03 +00:00
|
|
|
- `GET /vks/by-fingerprint/<FINGERPRINT>` retrieves the key with the given
|
2019-02-22 21:13:38 +00:00
|
|
|
fingerprint. Hexadecimal digits must be uppercase.
|
2019-02-28 15:57:03 +00:00
|
|
|
- `GET /vks/by-keyid/<KEY-ID>` retrieves the key with the given long key
|
2019-02-22 21:13:38 +00:00
|
|
|
ID. Hexadecimal digits must be uppercase.
|
2019-02-28 15:57:03 +00:00
|
|
|
- `GET /vks/by-email/<URL-encoded user ID>` retrieves the key with the given user
|
2019-01-09 13:56:51 +00:00
|
|
|
ID. Only exact matches are accepted.
|
|
|
|
- `GET /vks/verify/<token>` verifies a user ID using a token string send by
|
|
|
|
email.
|
|
|
|
- `GET /vks/delete/<fingerprint>` requests deletion of the key with the given
|
|
|
|
fingerprint.
|
|
|
|
- `GET /vks/confirm/<token>` confirms a keys deletion request using a token
|
|
|
|
string send by email.
|
2018-09-19 20:27:25 +00:00
|
|
|
|
2019-02-23 21:37:30 +00:00
|
|
|
Keys can also be fetched by their subkeys fingerprint and key
|
|
|
|
ID. Note: keys will show up even if no user IDs are verified.
|
2018-10-18 14:54:00 +00:00
|
|
|
|
|
|
|
Building
|
|
|
|
--------
|
|
|
|
|
2019-02-21 21:44:58 +00:00
|
|
|
Building Hagrid requires a working nightly Rust toolchain. The
|
2018-10-18 14:54:00 +00:00
|
|
|
easiest way to get the toolchain is to download [rustup](https://rustup.rs).
|
|
|
|
After rustup is installed, get the nightly compiler and tools:
|
|
|
|
|
|
|
|
```bash
|
2019-02-12 13:09:06 +00:00
|
|
|
cd hagrid
|
|
|
|
rustup override set nightly
|
2018-10-18 14:54:00 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
The web server can now be built with the cargo command:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cargo build --release
|
|
|
|
```
|
|
|
|
|
|
|
|
After compilation a binary is placed in `target/release/` called
|
2018-11-22 15:40:59 +00:00
|
|
|
`hagrid`. The binary is linked statically and can be copied everywhere.
|
2018-10-18 14:54:00 +00:00
|
|
|
|
|
|
|
```bash
|
2018-11-22 15:40:59 +00:00
|
|
|
cp target/release/hagrid /usr/local/bin
|
2018-10-18 14:54:00 +00:00
|
|
|
```
|
|
|
|
|
2019-02-21 21:44:58 +00:00
|
|
|
To deploy the key server copy all
|
2018-10-18 14:54:00 +00:00
|
|
|
directories under `public/` to a writable location. Then start the server with
|
|
|
|
the _absolute_ path to the directory as argument:
|
|
|
|
|
|
|
|
```bash
|
2019-02-12 13:09:06 +00:00
|
|
|
mkdir /var/lib/hagrid
|
|
|
|
cp -R dist/* /var/lib/hagrid
|
|
|
|
hagrid /var/lib/hagrid
|
2018-10-18 14:54:00 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
This will spawn the server in foreground, listening on `0.0.0.0:8080`. The
|
|
|
|
`--listen` argument can be used to change port and listen address. The server
|
2019-02-12 13:09:06 +00:00
|
|
|
will put all keys and runtime data under the base folder (`/var/lib/hagrid`
|
2018-10-18 14:54:00 +00:00
|
|
|
in the above example).
|
2018-11-22 15:40:59 +00:00
|
|
|
|
2019-01-09 13:56:51 +00:00
|
|
|
Reverse Proxy
|
|
|
|
-------------
|
|
|
|
|
2019-02-28 15:57:03 +00:00
|
|
|
Hagrid is designed to defer lookups to reverse proxy server like Nginx
|
|
|
|
and Apache. The key database is a set of 3 directories with static
|
|
|
|
files in them. The directory structure reflects Hagrids URL
|
|
|
|
scheme. This way, lookups via `/vks/by-finingerprint`,
|
|
|
|
`/vks/by-keyid`, and `/vks/by-email` can be handled by (multiple)
|
|
|
|
simple HTTP server(s). A sample configuration for Nginx is part of the
|
|
|
|
repository (`nginx.conf`).
|
2019-01-09 13:56:51 +00:00
|
|
|
|
2018-11-22 15:40:59 +00:00
|
|
|
Community
|
|
|
|
---------
|
|
|
|
|
|
|
|
We're in `##hagrid` on Freenode.
|