Disclaimer: this post is a machine translation of the original Chinese version. Please refer to the original content for accurate information.

Preface#

Keyoxide is similar to Keybase.io, used for verifying the identity consistency of online accounts.

For example, search for contact@forgejo.org on Keyoxide.org, and you’ll see that Forgejo owns a Mastodon instance account @forgejo@floss.social, the domain forgejo.org, and a Forgejo instance account @forgejo@codeberg.org.

You can also search using OpenPGP public key fingerprints. For instance, search for my fingerprint (which can be found on the “Contact” page) on Keyoxide.org, and you’ll see that Yuki claims ownership of accounts such as ActivityPub, Matrix, Forgejo, as well as the domain obsp.de.

Each query performs real-time verification, and successfully verified entries will display a green checkmark next to them. This ensures the information is up to date.

Currently, Keyoxide employs two identity verification systems: one is the Ariadne Signature Profile, and the other is the widely adopted OpenPGP.

Keyoxide is decentralized—not only because anyone can run their own Keyoxide instance, but also because OpenPGP utilizes a federated information system. When you need to retrieve a public key, you can obtain the public key associated with an email address from large key servers like keys.openpgp.org, exchange public keys directly with your contacts in a peer-to-peer manner, or use WKD to fetch the public key.

So, what is WKD? WKD stands for Web Key Directory, and as the name suggests, it is a method of retrieving keys by making an HTTPS request to a specific directory on a website. For example, if Alice’s email address is alice@example.org, and Bob wants to obtain her public key but cannot find valid results on large key servers (because Alice hasn’t published it publicly), asking Alice directly would waste time waiting for her reply. If example.org supports WKD, Bob can run gpg --locate-key alice@example.org to fetch her public key. This command essentially performs the following actions:

  • Perform a WKD hash on the string “alice” to obtain the hash string “kei1q4tipxxu1yj79k9kfukdhfy631xe”
    • You can verify it by running gpg-wks-client --print-wkd-hash alice@example.org in the terminal
  • Combine the hash string, the domain example.org, and the general format of WKD to obtain the WKD URL
    • It should look like https://openpgpkey.example.org/.well-known/openpgpkey/example.org/hu/kei1q4tipxxu1yj79k9kfukdhfy631xe?l=alice
    • Or https://example.org/.well-known/openpgpkey/example.org/hu/kei1q4tipxxu1yj79k9kfukdhfy631xe?l=alice
    • The first type, known as the subdomain method URL, is more favored by GnuPG compared to the second type, the direct method URL.
  • The content of this WKD URL via curl
    • It is not ASCII-armored but in binary format, making it unreadable.
  • gpg --import

You might notice that unlike the --search-key operation on a keyserver, GnuPG does not prompt you to confirm whether to import the key. This is because keys published via WKD are generally considered valid and trustworthy. If Alice owns the domain example.org and has exclusive control over its directory, the key discovered through WKD can be assumed to have been published by Alice herself. If Alice is merely a user of example.org, then at the very least, the key was published by Alice’s administrator.

Currently, email providers supporting WKD include systemli.org, posteo.de, Proton, Mailfence, and ForwardEmail, among others. Since disroot.org, which I use, does not support WKD, the public key you find on Keyoxide will show as originating from an HKP server. However, Forgejo provides WKD support for forgejo.org, so Keyoxide will display the public key as coming from WKD, and you can click the WKD link to verify it.

If you use a domain email, you can self-host WKD. If your provider supports WKD, you can CNAME the subdomain openpgpkey to the provider’s domain. If the provider does not support it, you can also directly CNAME to wkd.keys.openpgp.org, which is a WKD as a service offering by openpgp.org.

Creating Notation#

Assuming:

  • You own a domain named doma.in
  • You have created a public key for your email address you@doma.in
  • You wish to prove ownership of this domain

What you need to do is simple:

  • Add a note to your public key: “I own doma.in”
  • Add a TXT record to the domain: “Public key fingerprint xxx is correct” (this record can optionally be hashed)

As you’ve likely noticed, these two records are not equivalent. With just the note on the public key, we can find doma.in, but the fingerprint in the TXT record on doma.in doesn’t lead us back to the public key. Moreover, since the fingerprint remains unchanged before and after the note, you have no way of knowing what public key fingerprint xxx actually said. We cannot and do not need to trace back from doma.in to you@doma.in, which is why the TXT record can be replaced with a hash (as for why someone might want to use a hash—it’s because they may have published their public key to a keyserver, where the fingerprint can be used to search and trace back to the public key).

Notes on public keys are referred to as Identity Claims on Keyoxide, which is quite straightforward—they are declarations of ownership over an identity. While asserting ownership, they also indicate where the proof can be found for that identity. The records returned by the claimed ownership items are called Identity Proofs, which can appear in places like TXT records of a domain, repositories on a Git instance, or posts on a Fediverse account. These locations must be editable only by the account owner. For example, you cannot claim a proof for a GitHub account in a gist under a username you do not claim—the reasoning is simple.

We run the following command to create a note:

gpg --edit-key FINGERPRINT
list #list all the uid under the fingerprint
uid N #select the uid to be edited
notation #add a new notation
proof@ariadne.id=dns:doma.in?type=TXT #claims that you own doma.in，with proof in its TXT record
save

Different online identities have different claims. You can check the supported claim/proof types yourself. Generally, claims follow the format proof@ariadne.id=CLAIM.

Creating a Proof#

We add a proof to doma.in by creating a TXT record in the following format:

openpgp4fpr: FINGERPRINT

The TTL can be any value.

Oh, and you can use argon2 or bcrypt for hashing to ensure a certain level of anonymity. Keyoxide’s documentation thoughtfully provides a hashing tool. Simply input the string openpgp4fpr: FINGERPRINT, then paste the output into the TXT record.

Now, upload your key to WKD or HKP! If all goes well, within the TTL period, you should be able to search for your email address or public key fingerprint on Keyoxide and see that you’ve successfully verified ownership of doma.in.

Miscellaneous#

If you accidentally write the claim incorrectly (which happens often), you can re-enter the notation section of the GnuPG identity editor and input -the incorrect notation to delete it. If you forget which notations you’ve added, you can enter showpref while editing the identity to view them.

For most of my proofs, I used argon2 hashing, though Matrix uses plaintext. Hashed values always show verification failures—even switching to bcrypt didn’t work. I’m not sure exactly where the issue lies, but I’ll check later to see if I can reproduce it. (Update: It’s solved. use /plain command to prevent Matrix from formatting the string.) That said, it’s not a big deal since the hash doesn’t serve much purpose unless you genuinely don’t want someone who knows the location of your proof to discover the location of your claim, and you also won’t leak this connection through other means… The likelihood of this seems quite low to me. If that’s truly the case, it’s better not to claim at all, as it could compromise your anonymity.

I haven’t yet tried using Ariadne Signature Profile or self-hosting a Keyoxide instance—I might write another tutorial on that later. Keyoxide’s official documentation is highly recommended; it’s well-structured and easy to understand.