GPG Key sharing via WKD (Web Key Directory)

If you are using GPG from time to time, the key exchange might be not easy in all situations. To simplify the process, you can host your own Web Key Directory.

Here you can find the specification document:

This mini-guide is for new-ish GPG versions (>2.2.12); might not work for older ones.

  • First things first, you will need a key that you will want to share in WKD. Generate one if you don't have it
  • You will need a subdomain
  • Make sure you can upload the files to this domain
  • Locate the WKD hash of your key
gpg --with-wkd-hash --fingerprint
pub   rsa4096 2023-07-29 [SC]
uid           [ultimate] You Lastname <>
sub   rsa4096 2023-07-29 [E]

In this example, the hash is 01234567890123456789012345678901

  • Export your key to a file
gpg --no-armor --export > 01234567890123456789012345678901
  • Upload your key to the server

Your URL to the key should match the specifications outlined in the document:

  1. The scheme https://,
  2. the string openpgpkey,
  3. the domain-part,
  4. the string /.well-known/openpgpkey/,
  5. the domain-part in lowercase,
  6. the string /hu/,
  7. the above-constructed 32-octet string
  • Ensure you can access this file over HTTPS in your browser as a test
  • Ensure this file is served with the proper content type
  • Test if your key is working, for this sq utility is very helpful
sq wkd get
  • Share instructions with someone you want to send an encrypted message to you (some email clients do this automatically)
gpg  --locate-external-keys
gpg: key DEADBEEFDEADBEEF: public key "You Lastname <>" imported
gpg: Total number processed: 1
gpg:               imported: 1
pub   rsa4096 2023-09-19 [SC]
uid           [ unknown] You Lastname <>
sub   rsa4096 2023-09-19 [E]

Here is an example with one of my keys:

gpg --locate-external-keys
gpg: checking the trustdb
gpg: marginals needed: 3  completes needed: 1  trust model: pgp
gpg: depth: 0  valid:   8  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 8u
gpg: next trustdb check due at 2025-04-11
gpg: key DCD447A914B69472: public key "Hexide Security <>" imported
gpg: Total number processed: 1
gpg:               imported: 1
pub   rsa4096 2023-09-19 [SC] [expires: 2027-01-01]
uid           [ unknown] Hexide Security <>
sub   rsa4096 2023-09-19 [E] [expires: 2027-01-01]


If, for whatever reason sq utility does not print out your key, try these things:

  • Print out the expected URL of the key with sq utility, and make sure you can access it in a web browser
sq wkd url
  • Make file is served with the correct content type
curl ''

Look for < content-type

> GET /.well-known/openpgpkey/ HTTP/2
> Host:
> User-Agent: curl/8.2.1
> Accept: */*
< HTTP/2 200 
< date: Tue, 19 Sep 2023 17:53:18 GMT
< content-type: application/octet-stream
< content-length: 2269
< accept-ranges: bytes
  • Make sure gpg utility is a higher version than 2.2.12
gpg --version