Encryption keys

To send somebody encrypted mail, a mail app needs their public key. The server can publish the OpenPGP keys of the people at a domain in a Web Key Directory (WKD), the place apps such as Thunderbird, GnuPG, Proton Mail and Mailvelope look for them. Somebody writing to ada@example.com then finds Ada’s key without asking her for it.

The organisation decides which domains publish. Each person publishes their own key: nobody can publish a key for somebody else, administrators included, because a key somebody else chose could be one they hold the other half of.

The examples use the vsx shell function from the Quick start.

Turning a domain on

On the console, open Domains, choose the domain and find Encryption keys. Choose Publish people’s keys.

From the command line:

vsx admin openpgp on example.com
vsx admin openpgp show example.com

Then let mail apps reach the directory:

1. Point openpgpkey.example.com at the server, with a CNAME to its host name such as mail.example.com. Apps ask this name first.
2. Include openpgpkey.example.com in the server’s certificate. Apps fetch keys only over HTTPS with a certificate that names it.

If example.com itself points at the server, apps can also reach the directory there, at https://example.com/.well-known/openpgpkey/, and the openpgpkey name is not needed.

Publishing your key

Each person publishes their own key on the server’s page:

1. Open https://mail.example.com/account/encryption-keys and sign in with your address and password, and your second step if you are asked for one.
2. The page lists each of your addresses, whether its domain publishes keys, and the key published for it: its kind, fingerprint and expiry.
3. Under the address, paste your public key as gpg --export --armor you@example.com prints it, or choose the .asc or .pgp file, then choose Publish it. Publishing again replaces the key with the new one.
4. To stop publishing it, choose Take it down.

An address at a domain that does not publish keys says so, and has nothing to publish with. If the key is refused, the page says why.

A mail app that supports it can do the same through the API:

curl -X PUT https://mail.example.com/api/v1/tenants/1/accounts/7/openpgp-keys/ada@example.com \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"key\": $(gpg --export --armor ada@example.com | jq -Rs .)}"

key is the public key, ASCII-armored as gpg --export --armor writes it, or the binary key in base64. A new key replaces the one published before. To stop publishing, send DELETE to the same address.

The key is published when:

• it is for one of your own addresses, at a domain that publishes keys;
• it has a user ID with that address, signed by the key itself;
• it has not expired and has not been revoked;
• it has a key that can receive encrypted mail;
• it holds no private key. A file with a private key in it is refused, and nothing of it is kept.

What is published is only what was checked: the primary key, the user ID for that address and its signature, and each subkey the primary key signed. Other addresses on the same key, and other people’s signatures on it, are left out.

Supported keys are version 4 and version 6, with RSA of 2048 to 8192 bits, ECDSA on NIST P-256, P-384 or P-521, or Ed25519. Their signatures must use SHA-256, SHA-384 or SHA-512.

When a key is refused, the answer says why, for example:

the key was not published: no user ID for ada@example.com is signed by the key itself

Seeing and removing keys

Encryption keys on the domain’s page lists every published key with its address, algorithm, fingerprint and expiry. Anybody who may see the domain sees the list. Organisation administrators and the domain’s administrators can remove a key, for example one that was lost or stolen, and can turn the domain off.

vsx admin openpgp remove ada@example.com
vsx admin openpgp off example.com

Turning a domain off removes every key published under it. People publish theirs again if it is turned back on. Each change is recorded in the audit log.

S/MIME certificates

Outlook, Apple Mail and other apps that encrypt with S/MIME look for a colleague’s certificate in the organisation’s address book. Each person publishes their own certificate there, for one of their addresses, and it appears on their card in the address book that every colleague’s app reads over CardDAV. As with OpenPGP keys, nobody can publish a certificate for somebody else.

Each person publishes their certificate on the same page as their key, https://mail.example.com/account/encryption-keys:

1. Under the address, find S/MIME certificate. Every one of your addresses has one, whether or not its domain publishes OpenPGP keys.
2. Paste the certificate as PEM, or choose its .pem, .cer, .crt or .der file, then choose Publish it. Publishing again replaces it.
3. The page shows the certificate’s subject, issuer, serial number, fingerprint and the dates it is valid between.
4. To take it down, choose Take it down.

Publish the certificate only. The .p12 or .pfx file your certificate authority gave you also holds your private key, and is refused.

A mail app that supports it publishes through the API:

curl -X PUT https://mail.example.com/api/v1/tenants/1/accounts/7/smime-certificates/ada@example.com \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"certificate\": $(jq -Rs . < ada.pem)}"

certificate is the certificate as PEM, or DER in base64, at most 64 KiB. A new certificate replaces the one published before, and DELETE to the same address takes it down.

The certificate is published when:

• it is one certificate, and the file holds no private key; a PKCS #12 (.p12 or .pfx) file is refused, since it carries the key;
• it names the address in its subject alternative name, or in its subject’s email address. An address whose part before the @ is not plain ASCII, such as jörg@example.com, is named as an SmtpUTF8Mailbox, as RFC 8398 says; its domain may be written either way, and its local part must match exactly, apart from the case of plain letters;
• it is within its validity period;
• when it lists what it may be used for, email protection is among them.

Whether it was issued by an authority other people trust is for their mail apps to check, as they do for any certificate.

On the console, a domain’s page has an S/MIME certificates card listing each published certificate with its subject, issuer, fingerprint and validity. The organisation’s administrators and the domain’s can remove one. From the command line:

vsx admin smime show example.com
vsx admin smime remove ada@example.com

Signed mail arriving is checked too: the filter verifies S/MIME and OpenPGP signatures and records whether they hold in the message trace. See S/MIME signatures and OpenPGP signatures.

What mail apps fetch

A mail app looking up ada@example.com asks for:

https://openpgpkey.example.com/.well-known/openpgpkey/example.com/hu/<hash>?l=ada

where <hash> is made from ada. The server answers with the key, as binary. It also serves an empty policy file beside it, which tells apps that the domain runs a directory. A domain that does not publish keys answers neither.

To check what an app will find, ask GnuPG:

gpg --auto-key-locate clear,wkd --locate-keys ada@example.com