Decentralized Identifiers (DIDs) are a new type of identifier for verifiable, decentralized digital identity. These new identifiers are designed to enable the controller of a DID to prove control over it and to be implemented independently of any centralized registry, identity provider, or certificate authority. These sorts of identifiers often utilize a heavy-weight registry, such as ones utilizing Decentralized Ledger Technologies (DLT), to create, read, update, and deactivate DIDs. This specification describes a non-registry based DID Method based on expanding a cryptographic public key into a DID Document. This approach provides the simplest possible implementation of a DID Method that is able to achieve many, but not all, of the benefits of utilizing DIDs.

Portions of the work on this specification have been funded by the United States Department of Homeland Security's Science and Technology Directorate under contract HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.

Introduction

Decentralized Identifiers (DIDs) [[DID-CORE]] are a new type of identifier for verifiable, decentralized digital identity. These new identifiers are designed to enable the controller of a DID to prove control over it and to be implemented independently of any centralized registry, identity provider, or certificate authority. These sorts of identifiers often utilize a heavy-weight registry, such as ones utilizing Decentralized Ledger Technologies (DLT), to create, read, update, and deactivate DIDs.

While DLT-based DID Methods have great decentralization characteristics, and some of the more centralized DID Methods provide strong system control guarantees, the general approaches tend to be expensive to setup and operate. Some use cases requiring DIDs do not need the guarantees provided by these heavy-weight systems. For example, a DID that will only be used for a single, ephemeral interaction might not need to be registered, updated, or deactivated. It is for this class of use cases that the did:key method exists.

The rest of this document outlines the syntax for the did:key method, the operations it supports, and some security and privacy considerations that implementers might want to be aware of when implementing.

The did:key Format

The format for the did:key method conforms to the [[DID-CORE]] specification and is simple. It consists of the did:key prefix, followed by a Multibase [[MULTIBASE]] base58-btc encoded value that is a concatenation of the Multicodec [[MULTICODEC]] identifier for the public key type and the raw bytes associated with the public key format.

The ABNF for the key format is described below:

did-key-format := did:key:<mb-value>
mb-value       := z[a-km-zA-HJ-NP-Z1-9]+
      

Alternatively, the encoding rules can also be thought of as the application of a series of transformation functions on the raw public key bytes:

did-key-format := did:key:MULTIBASE(base58-btc, MULTICODEC(public-key-type, raw-public-key-bytes))

A simple example of a valid Ed25519 did:key DID is:

did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH
      

Operations

The following section outlines the DID operations for the did:key method. Implementers might note that this DID Method is purely generative, requiring no look ups in a registry. Since did:key values are not stored in any registry, they cannot be updated or deactivated.

Create

Creating a did:key value consists of creating a cryptographic key pair and encoding the public key using the format provided in Section . The creation of a DID Document is also performed by taking the public key value and expanding it into DID Document. An example is given below that expands the ed25519 did:key did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH into its associated DID Document:

{
  "@context": "https://w3id.org/did/v1",
  "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
  "publicKey": [{
    "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    "publicKeyBase58": "B12NYF8RrR3h41TDCTJojY59usg3mbtbjnFs7Eud1Y6u"
  }],
  "authentication": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" ],
  "assertionMethod": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" ],
  "capabilityDelegation": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" ],
  "capabilityInvocation": [ "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH" ],
  "keyAgreement": [{
    "id": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH#zBzoR5sqFgi6q3iFia8JPNfENCpi7RNSTKF7XNXX96SBY4",
    "type": "X25519KeyAgreementKey2019",
    "controller": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
    "publicKeyBase58": "JhNWeSVLMYccCk7iopQW4guaSJTojqpMEELgSLhKwRr"
  }]
}
        

Read

Reading a did:key value is a matter of deterministically expanding the value to a DID Document. This process is described in Section .

Update

This DID Method does not support updating the DID Document.

Deactivate

This DID Method does not support deactivating the DID Document.

Test Vectors

For a full list of test vectors see test vectors.

Ed25519 / X25519

These DID always start with z6Mk.

          did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp
          did:key:z6MkjchhfUsD6mmvni8mCdXHw216Xrm9bQe2mBH1P5RDjVJG
          did:key:z6MknGc3ocHs3zdPiJbnaaqDi58NGb4pk1Sp9WxWufuXSdxf
        

X25519

These DID always start with z6LS.

          did:key:z6LSeu9HkTHSfLLeUs2nnzUSNedgDUevfNQgQjQC23ZCit6F
          did:key:z6LStiZsmxiK4odS4Sb6JmdRFuJ6e1SYP157gtiCyJKfrYha
          did:key:z6LSoMdmJz2Djah2P4L9taDmtqeJ6wwd2HhKZvNToBmvaczQ
        

Secp256k1

These DID always start with zQ3s.

          did:key:zQ3shokFTS3brHcDQrn82RUDfCZESWL1ZdCEJwekUDPQiYBme
          did:key:zQ3shtxV1FrJfhqE1dvxYRcCknWNjHc3c5X1y3ZSoPDi2aur2
          did:key:zQ3shZc2QzApp2oymGvQbzP8eKheVshBHbU4ZYjeXqwSKEn6N
        

BLS 12381

These DID always start with zUC7.

          did:key:zUC7K4ndUaGZgV7Cp2yJy6JtMoUHY6u7tkcSYUvPrEidqBmLCTLmi6d5WvwnUqejscAkERJ3bfjEiSYtdPkRSE8kSa11hFBr4sTgnbZ95SJj19PN2jdvJjyzpSZgxkyyxNnBNnY
          did:key:zUC7KKoJk5ttwuuc8pmQDiUmtckEPTwcaFVZe4DSFV7fURuoRnD17D3xkBK3A9tZqdADkTTMKSwNkhjo9Hs6HfgNUXo48TNRaxU6XPLSPdRgMc15jCD5DfN34ixjoVemY62JxnW
        

P-256

These DID always start with zXwpB.

          did:key:zXwpBnMdCm1cLmKuzgESn29nqnonp1ioqrQMRHNsmjMyppzx8xB2pv7cw8q1PdDacSrdWE3dtB9f7Nxk886mdzNFoPtY
          did:key:zXwpBzzzpUofYSorhHTeGwKWCKTBvUkNEkgHtCivNyQTixsyGmHiQfkjGtum3SxJxsetka9rp3VB2gkKF5zchhwHNEfC
        

P-384

These DID always start with zACH.

          did:key:zACHdaSNFRwUmdgukpbVe9iGeDcqgs8ad5aTorGvwW65PLKBopzGCkggJETpAGALEyY6wmv684bxYLfuKNCdGVUxRAh1BiY8tuZKP7mrz24D7t2hp2Zhg1JToiRCQFfghfPFKQnJ
          did:key:zACHck3hF2p6keLoo4f4FYi83JxyU4gJkY9uQhE8xcfdvFfqN6VD7EnUjTsun2wnij6zAhFZehwZhaWPhRAFsjD1CVBTNdK2qz24KdUksRVANHcX7MvzQsmvE9Ktk8PjeEqpLxAJ
        

P-521

These DID always start with zJss7x.

          did:key:zJss7xLxvT5rcYS7frBJtToymirNayBALM2avZCe1anYqfZbzNCtqAsR3zEpVs7SdJtD8VzZMDE68L6eYu73bRJi8KjHvtTwkLyzAz1Pa6AuMhhmb9dz1PdUtT2wjcL6rByp5FZnwHfMEJtg9tW8wEgxYZGDVSEFecbaSc3vah97kCDh6FuggqB1B
          did:key:zJss7xGbDiKzPpjeRPnxiDVAH3PFqqCiJ4P34RSDjw35EG2Dk6Phnr5GnhsUa4KVamJsf4BP5iCPfCdkd9xKsnNaMbr6YYcY4ueSTZgLGwtgM5815bZD9s3btuMn13eiBxDdsWmEtuLQgjbN9SQ83Wef3Z1hK9Lk96Z7yd6f23eeSrWiahTsY3rjJ
        

Security and Privacy Considerations

There are a number of security and privacy considerations that implementers will want to take into consideration when implementing this specification.

Key Rotation Not Supported

The did:key method is a purely generative method, which means that updates are not supported. This can be an issue if a did:key is expected to be used over a long period of time. For example, if a did:key is ever compromised, it is not possible to rotate the compromised key. For this reason, using a did:key for interactions that last weeks to months is strongly discouraged.

Deactivation Not Supported

The did:key method is a purely generative method, which means that deactivations are not supported. This can be an issue if a did:key is expected to be used over a long period of time. For example, if a did:key is ever compromised, it is not possible to deactivate the DID to stop an attacker from using it. For this reason, using a did:key for interactions that last weeks to months is strongly discouraged.

Key Derivation Lacks Proof

Some implementations might utlize a key derivation function when converting from an ed25519 public key to a Curve25519 ECDH key, used in the keyAgreement verification method. It is expected that this is a relatively safe operation, but implementers might consider that there exists no mathematical proof that confirms this assumption.

Long Term Usage is Discouraged

Since there is no support for update and deactivate for the did:key method, it is not possible to recover from a security compromise. For this reason, using a did:key for interactions that last weeks to months is strongly discouraged.

Acknowledgements

The Working Group would like to thank the following individuals for reviewing and providing feedback on the specification (in alphabetical order):

TBD...