This document describes the did:pgp: Decentralized Identifier (DID) Method. The name "pgp" comes from its use of notated OpenPGP keys. It aims to be a DID Document resolution mechanism and identifier which does not rely on a blockchain or the support of blockchain funding, and which, unlike did:plc:, does not rely on a potentially centralized host.

DID Format

The format of a DID with the "pgp" method is:

did:pgp:type:identifier
OR
did:pgp:identifier

where "type" is one of:

• missing/empty or "base58": then "identifier" is a public key fingerprint in base58check/base58-btc (the same as Bitcoin and did:key use)
• "email": then "identifier" is an email address
• "hex": then "identifier" is a public key fingerprint in lowercase hexadecimal

Examples

did:pgp:3VR48rg9ky7y6hDecbz2reDaLzMb
did:pgp:hex:b2b909b0c0b439683a1125813b1965c22d07d9f6

Parameters

One DID query parameter specific to did:pgp: is currently defined:

keyserver (URL, optional, can be repeated)

A keyserver to use when looking up the key. It is expected to be an hkps:// URL.

Resolvers are expected to ignore any query parameters they do not understand or don't want to use.

Operations

Create

To create a resolvable did:pgp::

1. Create a PGP key pair. GnuPG 2.0 or newer is recommended for this, if you don't have an OpenPGP tool you'd rather use. In any case, it MUST support notations on keys. Additionally, do not use RSA, it is insecure, and it has been broken! Ed25519 and Curve25519 is recommended instead; you could use a post-quantum cryptography suite if you'd like, but there is not much support for it at the moment so you probably should avoid that.
2. Publish a DID Document resolvable by a URL over the Internet. HTTPS is HIGHLY RECOMMENDED for this. It must live on a server where it can be resolved at any time.
   • The DID itself is derived during the creation of the DID document. It SHOULD use the "base58" type, without specifying it (i.e. just did:pgp:identifier).
3. Add a notation to your new PGP key pair. The notation name MUST be did-pgp@halsco.de, and the notation value MUST be the URL pointing to the DID document. The full notation will look like:

did-pgp@halsco.de=https://example.org/did-documents/halscode.json

1. Publish your new PGP public key to keyserver(s). We recommend at least hkps://pgp.mit.edu and hkps://keyserver.ubuntu.com.

Tip: When creating your DID Document, create the DID in the "id" field from the key itself. You can use email, but as that may change, you should use your key fingerprint instead.

Note: The did:pgp: will expire along with your key! Set the expiration accordingly.

Read

Don't attempt to use a did:pgp: without resolving it.

To resolve a did:pgp::

1. Try to connect to different HKPS keyservers (see our recommendations above, under Create), or use WKD if the type is "email". The order of which you try does not matter, and WKD support is optional but RECOMMENDED.
   • If a DID query parameter named "keyserver" is supplied, and it is an hkps:// URI, prioritize using the specified keyserver to look up the DID. This parameter MUST NOT be used in storage.
2. Request the key from the keyserver or WKD. If no key is found, go back to step 1 and try a different keyserver (or try WKD, if you haven't yet). If no key is found on any keyserver or from WKD, abort the protocol and consider this a permanent failure; the DID cannot be resolved.
3. Once you have a valid OpenPGP key, check its notations for one named did-pgp@halsco.de. There should only be one; if there is more than one, only consider the first one found. Its value should be a valid URL. If the resolving client does not support the URL scheme (i.e. maybe you don't support gemini:// yet), resolution has failed, and should not be tried again.
4. Resolve the URL to get the DID Document. If this fails, it may be considered a temporary error. (For example, 410 Gone should indicate that the DID Document should not be expected to resolve later, but a 404 Not Found, 503 Service Unavailable, or 504 Gateway Timeout may indicate that trying again later is possible.)
5. Check the "id" field in the DID document. If it is not the same DID you were supplying, it SHOULD be a did:pgp: which points to the same URL, or at least resolve to the same DID document (so you can stop a step early). Use that DID in storage or for any future reference.
   • If the did:pgp: here includes the keyserver query parameter, consider the document invalid.

Warning: If you cannot find a key anywhere, consider that the key has been retracted.

Update

There are two ways to update a did:pgp:, either by updating the key to change the URL pointing to the DID document, or by updating the DID document on the Web server hosting it. This document can only reliably cover the first case.

To update the URL of the DID Document which the did:plc: points to:

1. Replace the notation named did-pgp@halsco.de. Use the same name, but set the value to the new URL to resolve it to.
2. Publish your updated PGP public key to keyserver(s), just like you did when you created it.

Warning: The "id" field in the DID document is not expected to change! If it does change, the places where it is used may not update the one they are already using, which may lead to failures to resolve, or being treated as a different user/DID, etc. You should never do this, but if you do, beware the consequences!
Resolvers MAY reject DID documents with a changed "id" field.

Recommendations:

• If you were given a did:pgp:email: which fully resolves, remember the email address for that DID. You can use this to look up another key later, if the original DID does not mention it, and if the original key expires or gets revoked.
• Account for the possibility that the "id" field has changed, but still correctly resolves. The key might have changed; you MAY re-associate the DID with the new key, if both keys point to the same DID document.
• Remember all email addresses from user IDs in the resolved key, which you can use to look up a new key later if the original key expires or gets revoked. If possible, only do this for keyservers which you know verify email addresses.

Delete

To invalidate a did:pgp:, retract the key from all the keyservers you published it to, including, if you used WKD, the web-server you published it on according to WKD. A did:pgp: for a key which does not exist MUST be considered deleted.

You should also delete the DID document, but not before you've retracted the key. Again, this is not covered here.