Publishing certificates

Publishing a certificate is a bit more involved than retrieving them. sq can publish directly to keyservers; for other distribution methods, sq can generate the necessary data or files.

The simplest way to publish to keyservers is:

$ sq network keyserver publish --cert EE99C48D11A4BE940569C4B3919EA6F609043A04

or more generally:

$ sq network keyserver publish $QUERY

sq searches inside the cert store for certificates matching $QUERY and publishes all results. $QUERY can be

  • a fingerprint: --cert $FINGERPRINT
  • a User ID: --userid "Alice Example"
  • an email address: --email alice@example.com
  • a file: --file $FILE

This example publishes the certificate to the default keyservers, which are keys.openpgp.org, mail-api.proton.me, keys.mailvelope.com, keyserver.ubuntu.com, and sks.pod01.fleetstreetops.com. This list can be customized by adding --server to the command:

$ sq network keyserver publish --server hkps://keys.openpgp.org --server hkps://some.other.keyserver.tld --email alice@example.com

If --server is used, the default servers are ignored. Note that --server expects the parameter to specify the protocol (e.g. hkps://), not just the hostname.

Generating and publishing files for WKD

Web Key Directory (WKD) is another way of distributing certificates. It defines a scheme which translates an email address into a URL (there are actually two schemes) that corresponds with a suitably configured webserver that will return the certificates upon request.

This requires the generation of files and directories complying with the scheme. sq can help by generating the required file structure:

$ sq network wkd publish --create --domain example.com /tmp/foo

This will create all files and directories under /tmp/foo, starting with the subdirectory .well-known. Only certificates with User IDs in the domain example.com will be included.

The above command will generate a directory structure according to the advanced method, to be used as content for https://openpgpkey.example.com/.well-known/openpgp/.... If you need the direct method (the second scheme, https://example.com/.well-known/openpgp/...), add --method direct to the command:

$ sq network wkd publish --create --method direct --domain example.com /tmp/foo

If there is already a directory structure present, using --create will return an error:

Error: Cannot create WKD because /tmp/foo already contains one

The certificates to include in the WKD directory structure can be selected using the following designators:

  • --cert $FINGERPRINT to use a certificate with that fingerprint
  • --userid $USER_ID any certificates matching $USER_ID
  • --email $EMAIL any certificates matching $EMAIL

Instead of using the cert store, certificates can also be taken from a keyring using --cert-file $FILE:

$ sq network wkd publish --cert-file /path/to/some/keyring.pgp --domain example.com --email alice@example.com /tmp/foo

or even all certificates for a domain in the cert store by omitting a filtering query:

$ sq network wkd publish --domain example.com /tmp/foo --all

If supplied with --rsync, sq invokes a local copy of rsync, passing the destination as-is. This is a useful way to update an existing published set of files efficiently:

$ sq network wkd publish --rysnc --domain example.com alice@myserver:/var/www/html --all

More on hosting a WKD: https://wiki.gnupg.org/WKDHosting

Generating records for DANE

For publishing certificates via DNS (aka DANE), a TXT record must be added to the zone file of the mail domain. The record can be generated like this:

$ sq network dane generate --domain example.com --cert-email alice@example.com

The result will be printed to STDOUT.

This example will generate a TXT record in OPENPGPKEY format. If your DNS server cannot handle this type of record, you can generate a generic record by adding --type generic.

Instead of specifying the certificates to publish (by --cert-email, --cert-userid or via fingerprint with --cert), you can choose --all.

$ sq network dane generate --type generic --domain example.com --cert-email alice@example.com

A more compact form of an OPENPGPKEY record can be generated by adding a size limit; sq will try to match that limit as best as it can:

$ sq network dane generate --size-limit 1024 --domain example.com --all

More on DANE can be found here: https://datatracker.ietf.org/doc/draft-ietf-dane-openpgpkey/12/.