README.md 2.84 KB
Newer Older
qua's avatar
qua committed
1 2 3 4 5 6
# WkdSrv

The Web Key Directory API daemon.

Provides an HTTP-API to create, retrieve, and delete OpenPGP keys to or from a [Web Key Directory](https://wiki.gnupg.org/WKD).

qua's avatar
qua committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
WKD enables other programs to fetch OpenPGP public keys via HTTP from the provider of the email address's domain. E.g. if you compose a message using Thunderbird+enigmail to alice@example.org without having their key yet, enigmail will automatically send an HTTP request to `https://openpgpkey.example.org/...` in order to receive alice's public key.

This API abstracts the chores to get public keys into the storage format and filename encoding that WKD defines.


## Usage

The code is built into a container image. Run it like this:

```
podman run -t -p 443:4443 -v /path/to/configdir:/config -v /path/to/storage:/storage registry.code.immerda.ch/immerda/container-images/wkd-srv:latest
```

* `/path/to/configdir` must include the TLS CA certificate, the TLS server's certificate, and the TLS server's key. Read the paths from `conf/example.yml`, or provide a custom config file called `wkd-srv.yml` inside the configdir with different paths.
* `/path/to/storage` will have sub-directories with the stored keys in it. This directory should be served publicly unter the path `https://openpgpkey.$domain/.well-known/`.

Instead of podman you can also use docker.


qua's avatar
qua committed
26 27
## API Details

qua's avatar
qua committed
28
Except for `/status`, only requests providing a valid TLS-client-certificate are accepted.
qua's avatar
qua committed
29 30 31 32 33

These endpoints are available:

### Create

qua's avatar
qua committed
34
To add a key, or update the key for the given address, send a POST request:
qua's avatar
qua committed
35 36

```HTTP
qua's avatar
qua committed
37
POST /EMAILADDRESS
qua's avatar
qua committed
38 39 40 41 42 43

-----BEGIN PGP PUBLIC KEY BLOCK-----
...
-----END PGP PUBLIC KEY BLOCK-----
```

qua's avatar
qua committed
44
The key material in the HTTP body may also be in binary form. All user IDs that do not match the given email address will be filtered out, and keys without a user ID will not be published.
qua's avatar
qua committed
45

qua's avatar
qua committed
46
Possible Responses:
qua's avatar
qua committed
47

qua's avatar
qua committed
48 49
**Success*: HTTP status code 201, no body content.
**Failure*: HTTP status code 4xx/5xx and an error messages as body (a string).
qua's avatar
qua committed
50 51


qua's avatar
qua committed
52
### Get
qua's avatar
qua committed
53

qua's avatar
qua committed
54
To get a key from the API, e.g. for internal tools that don't implement the WKD logic, send a GET request:
qua's avatar
qua committed
55 56 57 58 59

```
GET /EMAILADDRESS
```

qua's avatar
qua committed
60 61 62
Possible responses:
**Success*: HTTP status code 200 and the key material in binary form as body.
**Failure*: HTTP status code 4xx/5xx and an error message as body (a string).
qua's avatar
qua committed
63 64 65 66


### Delete

qua's avatar
qua committed
67
To delete a key, send a DELETE request:
qua's avatar
qua committed
68 69 70 71 72

```
DELETE /EMAILADDRESS
```

qua's avatar
qua committed
73 74 75
Possible responses:
**Success*: HTTP status code 204, no body content.
**Failure*: HTTP status code 4xx/5xx and an error message as body (a string).
qua's avatar
qua committed
76 77 78 79 80



### Status

qua's avatar
qua committed
81
To check if the service is available, send this GET request (optionally without a TLS client certificate):
qua's avatar
qua committed
82 83

```
qua's avatar
qua committed
84
GET /status
qua's avatar
qua committed
85 86
```

qua's avatar
qua committed
87 88 89
Possible responses:
**Success*: HTTP status code 204, no body content.
**Failure*: HTTP status code 4xx/5xx and an error message as body (a string).
qua's avatar
qua committed
90 91