Creating and updating a keylist

First you must generate an authority key. For higher security, we recommend that you store this key on an OpenPGP smart card such as a Yubikey. Here's an example authority key:

$ gpg --list-keys "GPG Sync Example Authority"
pub   rsa4096 2019-02-12 [SC] [expires: 2020-02-12]
      EE332CC416B304EBDBC5D716F341C5E51FB69079
uid           [ultimate] GPG Sync Example Authority
sub   rsa4096 2019-02-12 [E] [expires: 2020-02-12]

Now create the keylist JSON file called keylist.json, like this:

{
  "metadata": {
    "signature_uri": "https://www.example.com/keylist.json.asc",
    "comment": "This is an example of a keylist file"
  },
  "keys": [
    {
      "fingerprint": "927F419D7EC82C2F149C1BD1403C2657CD994F73",
      "name": "Micah Lee",
      "email": "[email protected]",
      "comment": "Each key can have a comment"
    },
    {
      "fingerprint": "1326CB162C6921BF085F8459F3C78280DDBF52A1",
      "name": "R. Miles McCain",
      "email": "[email protected]"
    },
    {
      "fingerprint": "E0BE0804CF04A65C1FC64CC4CAD802E066046C02",
      "name": "Nat Welch",
      "email": "[email protected]"
    }
  ]
}

The keylist must be a valid JSON file. It might help to use a JSON validator after editing your keylist to make sure you don't have any little errors.

The keylist must have a metadata section, and that section must have a signature_uri field, which contains the URL of where your PGP signature file will be hosted. The keylist must also have a keys section, which is a list of PGP fingerprints and associated metadata. For each key, only the fingerprint field is required. All other fields are optional.

For more information, read the draft Distributing OpenPGP Keys with Signed Keylist Subscriptions Internet standard, which exactly defines the file format.

We recommend that you manually compare each person's fingerprint before adding it to this keylist. And while this isn't required by GPG Sync, it's a good idea to sign each person's key with your authority key, and have them sign the authority key back, so you can build an internal web of trust.

Next, create an ASCII-armored detached signature of your list of keylist using your authority key. Here's how I'm doing it in my example:

$ gpg --armor --local-user EE332CC416B304EBDBC5D716F341C5E51FB69079 --detach-sign keylist.json

This creates a second file, keylist.json.asc, which contains the signature.

Finally, upload keylist.json and keylist.json.asc to a publicly accessibly website (if you'd like, you could maintain this file in a public git repository). Note that the URL of keylist.json.asc must be what's defined in the keylist['metadata']['keylist_uri']. You can upload keylist.json at a different location if you'd like.

Each time there is a key change in your organization, you need to add the new key to keylist.json, re-sign it with your authority key, and re-upload both files to the same URLs.