GPG-WKS-SERVER(1)

📦
version 2.4.9 · 18 versions
, in alpine 3.22, alpine 3.23

💖 GPG-WKS-SERVER(1) — the Web Key Service server, bestie edition 💖

okay so real talk: this is gpg-wks-server, a chunky little helper from GNU Privacy Guard 2.4, and it lives in section 1 of the manual. Think of it as the server-side main character of the Web Key Service. It's giving ✨infrastructure✨ and honestly? iconic.

🌸 NAME 🌸

gpg-wks-server — a server that provides the Web Key Service. that's it, that's the vibe. 🫶

🎀 SYNOPSIS 🎀

gpg-wks-server [options] --receive
gpg-wks-server [options] --cron
gpg-wks-server [options] --list-domains
gpg-wks-server [options] --check-key user-id
gpg-wks-server [options] --install-key file user-id
gpg-wks-server [options] --remove-key user-id
gpg-wks-server [options] --revoke-key user-id

like, pick a mode, any mode. each one is a different little task. slay. 💅

🦋 DESCRIPTION 🦋

gpg-wks-server is the server-side implementation of the Web Key Service. no cap. here's the whole personality: it receives requests for publication, sends confirmation requests, receives confirmations, and publishes the key. it also has features to make setting up and maintaining a Web Key Directory way easier, which is super helpful ngl.

When you run it with the command --receive, a single Web Key Service mail gets processed. and lowkey the usual move is to pair that with the option --send so the created mails get sent straight back. there's an installation example further down if you wanna see it in action 👀.

The command --cron is for regular cleanup tasks. for example, non-confirmed requested should be removed after their expire time. best practice? run this command once a day from a cronjob. it's giving "self-care sunday but for your server." 🌸

The command --list-domains prints all configured domains. bonus: it also creates missing directories for the configuration and prints warnings pertaining to problems in the configuration. it's a lister and a fixer. multi-talented. 👑

The command --check-key (or just --check) checks whether a key with the given user-id is installed. if it is, the process returns success. want a diagnostic too? use the option -v. if the key is not installed, a diagnostic is printed and the process returns failure — and to suppress that diagnostic, use option -q. you can pass more than one user-id; see also option --with-file. so many options, so little time. 💀

The command --install-key manually installs a key into the WKD. the arguments are a file with the keyblock and the user-id to install. here's the lil trick: if the first argument resembles a fingerprint, the key is taken from the current keyring — and to force the use of a file instead, just prefix the first argument with ./. no arguments given? then the parameters are read from stdin, and the expected format is lines with the fingerprint and the mailbox separated by a space. stdin girlies stay winning 🙈.

The command --remove-key uninstalls a key from the WKD. if it works, the process returns success — and to also print a diagnostic, use option -v. if the key is not installed, a diagnostic is printed and the process returns failure; to suppress the diagnostic, use option -q. same energy as check-key, opposite direction. balance. 🦋

The command --revoke-key is not yet functional. she's not ready yet, okay?? give her time 😭

✨ OPTIONS ✨

gpg-wks-server understands these options, and yes we're listing every single one because we don't skip:

  • -C dir, --directory dir — use dir as the top level directory for domains. the default is ‘/var/lib/gnupg/wks’. 🏠
  • --from mailaddr — use mailaddr as the default sender address. 💌
  • --header name=value — add the mail header "name: value" to all outgoing mails. every single one gets the header, no exceptions. ✨
  • --send — directly send created mails using the sendmail command. requires installation of that command, so like, make sure it's there first bestie. 📨
  • -o file, --output file — write the created mail also to file. note that the value - for file would write it to stdout. very cute, very useful. 💖
  • --with-dir — when used with the command --list-domains, print for each installed domain the domain name and its directory name. 🗂️
  • --with-file — when used with the command --check-key, print for each user-id the address, 'i' for installed key or 'n' for not installed key, and the filename. iykyk. 📄
  • --verbose — enable extra informational output. she's chatty and we love that. 🗣️
  • --quiet — disable almost all informational output. the introvert setting. 🤫
  • --version — print version of the program and exit. classic. 🌈
  • --help — display a brief help page and exit. when in doubt, --help it out. 🎀

💅 EXAMPLES 💅

The Web Key Service requires a working directory to store keys pending for publication. as root, create a working directory:

# mkdir /var/lib/gnupg/wks
# chown webkey:webkey /var/lib/gnupg/wks
# chmod 2750 /var/lib/gnupg/wks

Then, under your webkey account, create directories for all your domains. here we do it for "example.net":

$ mkdir /var/lib/gnupg/wks/example.net

Finally run:

$ gpg-wks-server --list-domains

to create the required sub-directories with the permissions set correctly. slay. ✨

For each domain a submission address needs to be configured. all service mails are directed to that address. it can be the same address for all configured domains, for example:

$ cd /var/lib/gnupg/wks/example.net
$ echo key-submission@example.net >submission-address

The protocol requires that the key to be published is sent with an encrypted mail to the service. so you need to create a key for the submission address:

$ gpg --batch --passphrase '' --quick-gen-key key-submission@example.net
$ gpg -K key-submission@example.net

The output of the last command looks similar to this:

sec   rsa3072 2016-08-30 [SC]
      C0FCF8642D830C53246211400346653590B3795B
uid           [ultimate] key-submission@example.net
                bxzcxpxk8h87z1k7bzk86xn5aj47intu@example.net
ssb   rsa3072 2016-08-30 [E]

Take the fingerprint from that output and manually publish the key:

$ gpg-wks-server --install-key C0FCF8642D830C53246211400346653590B3795B \
>                key-submission@example.net

Finally that submission address needs to be redirected to a script running gpg-wks-server. the procmail command can be used for this: redirect the submission address to the user "webkey" and put this into webkey's ‘.procmailrc’:

:0
* !^From: webkey@example.net
* !^X-WKS-Loop: webkey.example.net
|gpg-wks-server -v --receive \
     --header X-WKS-Loop=webkey.example.net \
     --from webkey@example.net --send

like, that's the whole setup. you're basically a sysadmin now. 💜

👑 SEE ALSO 👑

gpg-wks-client(1) — her counterpart, her other half, her partner in crime 🫶

🌈 cute lil sign-off 🌈

that's the whole page bestie! this one's from GnuPG 2.4.9, dated 2025-02-19, and it ate, no crumbs. go configure your Web Key Directory and text me when it works 💖✨🎀🦋

you got this. periodt. 💅

📦 where this page comes from