Skip to content
Like Keybase but distributed
JavaScript TypeScript HTML
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.

OpenPGP Proofs

This document describes a method of adding social proofs to OpenPGP keys in a way that can be independently verified by clients. This is similar to Keybase but decentralized.

An example:

$ gpg --export 653909a2f0e37c106f5faf546c8857e0d8e8f074 | node index.js
Key : openpgp4fpr:653909a2f0e37c106f5faf546c8857e0d8e8f074
User: Wiktor Kwapisiewicz <>


  ✓ github:wiktor-k

  ✓ reddit:wiktor-k

  ✓ hackernews:wiktor-k

If this is a person you were looking for you can locally sign the key:
  gpg --quick-lsign 653909a2f0e37c106f5faf546c8857e0d8e8f074

See also online version at

Technical details

Proofs are URIs to documents hosted on third-party sites (such as that can be used by proof-validating clients to check if the key owner has access to given social account.

(Inspect proofs from command line by using gpg --list-options show-notations --list-sigs D8E8F074 | grep proof).

Proof URIs are converted to URLs that are used to fetch JSON documents. These documents contain back-link data pointing to an OpenPGP key.

One additional document: proofs.json is needed for validators to properly handle proof URIs.

An example, given this proof URI:

It is matched to first entry in proofs.json, this regular expression:


Capturing groups are assigned names, in this case first group is a USERNAME and the second PROOFID.

These groups can be used to construct other elements, such as profile URL:


Or proof URL, that points to the JSON representation of the proof document:


The proof document is then fetched with appropriate headers and a number of checks, also defined in proofs.json is performed.

Checks always extract a piece of data from the JSON document by recursively extracing objects by keys.

For example the first check extracts owner object and then, from that object login key (["owner", "login"]). This is compared to a claim, that in this case is USERNAME that has been extracted from the URL.

If all checks succeed then the proof is considered validated.

For users

Proof documents can be added using platform specific editors only at the moment (for example GitHub gists). After the gist has been created a notation needs to be added to OpenPGP key that points to the proof document:

$ gpg --edit-key F470E50DCB1AD5F1E64E08644A63613A4D6E4094
sec  rsa1024/4A63613A4D6E4094
     created: 2013-10-18  expires: never       usage: SCEA
     trust: unknown       validity: full
ssb  rsa1024/E084F7446C202C97
     created: 2013-10-18  expires: never       usage: SEA
[  full  ] (1). Test McTestington <>


Use notation subcommand and enter and the proof URI.

For example:

gpg> notation
Enter the notation:
No notations on user ID "Test McTestington <>"
Adding notation:

Send the key to keyservers if you want others to be able to verify your proofs (this is not strictly needed).

For proof validators

Proof validation logic is designed to be as simple as possible. Proofs are extracted from OpenPGP self-signature notations using key and then matched to the data in proofs.json file.

JavaScript implementation of this process is in verifier.ts file. Additional implementations are planned.

For service providers

If you host a service and would like to add the ability for users to prove that they control that account there are only two steps:

  1. Expose user data (either profile info or a comment) in a JSON format that can be read by all sites (that is with appropriate CORS header: Access-Control-Allow-Origin: *). The document should include user name.

  2. Add an entry to proofs.json describing how to extract data (username and key fingerprint) from that document.

You can’t perform that action at this time.