The did:keri DID Method

2.1. Events

A Key Event is an atomic transaction over the Key State of an Identifier. While all events have some semantic meaning within KERI, only a subset will change the keys in a Key State (rotation and delegated rotation).¶

2.2. Key Event Log

The Key Event Log is a type of hash-chained data structure from which the Key State of an Identifier can be derived. It can always be used to recreate the state at any point ("event-sourcing").¶

2.3. Key Event Receipt Log

The Key Event Receipt Logs are built from receipts of events signed by the witnesses of those events (these are called commitments); these are also append-only but not hash-chained.¶

2.4. Key State

Key State represents the current values for the keys, witnesses and thresholds for a given identifier, signed by a provider. The signature from the provider signifies that the provider has verified the KEL for the identifier and the result of that verification is the key state. The key state is represented in a Key State Notification Message detailed fully in Event Serialization Key State Messages. The following fields are defined for a Key State Notification Message:¶

• v: Version String¶
• i: Identifier Prefix¶
• s: Sequence Number¶
• t: Message Type¶
• d: Event Digest (Seal or Receipt)¶
• p: Prior Event Digest¶
• kt: Keys Signing Threshold¶
• k: List of Signing Keys (ordered key set)¶
• n: Next Key Set Commitment¶
• wt: Witnessing Threshold¶
• w: List of Witnesses (ordered witness set)¶
• wr: List of Witnesses to Remove (ordered witness set)¶
• wa: List of Witnesses to Add (ordered witness set)¶
• c: List of Configuration Traits/Modes¶
• a: List of Anchors (seals)¶
• da: Delegator Anchor Seal in Delegated Event (Location Seal)¶
• di: Delegator Identifier Prefix in Key State¶
• rd: Merkle Tree Root Digest¶
• e: Last received Event Map in Key State¶
• ee: Last Establishment Event Map in Key State¶
• vn: Version Number ("major.minor")¶

Key state notification messages differ depending on whether the signer is using a delegated identifier. The follow examples detail the fields needed for each permutation.¶

        {
          "v": "KERI10JSON00011c_",
          "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
          "s": "2",
          "t": "ksn",
          "d": "EAoTNZH3ULvaU6JR2nmwyYAfSVPzhzZ-i0d8JZS6b5CM",
          "te": "rot",
          "kt": "1",
          "k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
          "n": "EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM",
          "wt": "1",
          "w": ["DnmwyYAfSVPzhzS6b5CMZ-i0d8JZAoTNZH3ULvaU6JR2"],
          "c": ["eo"],
          "ee":
            {
              "s":  "1",
              "d":  "EAoTNZH3ULvaU6JR2nmwyYAfSVPzhzZ-i0d8JZS6b5CM",
              "wr": ["Dd8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CMZ-i0"],
              "wa": ["DnmwyYAfSVPzhzS6b5CMZ-i0d8JZAoTNZH3ULvaU6JR2"]
            },
          "di": "EJZAoTNZH3ULvYAfSVPzhzS6b5CMaU6JR2nmwyZ-i0d8"
        }


        {
          "v": "KERI10JSON00011c_",
          "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
          "s": "2",
          "t": "ksn",
          "d": "EAoTNZH3ULvaU6JR2nmwyYAfSVPzhzZ-i0d8JZS6b5CM",
          "te": "rot",
          "kt": "1",
          "k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
          "n": "EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM",
          "wt": "1",
          "w": ["DnmwyYAfSVPzhzS6b5CMZ-i0d8JZAoTNZH3ULvaU6JR2"],
          "c": ["eo"],
          "ee":
            {
              "s":  "1",
              "d":  "EAoTNZH3ULvaU6JR2nmwyYAfSVPzhzZ-i0d8JZS6b5CM",
              "wr": ["Dd8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CMZ-i0"],
              "wa": ["DnmwyYAfSVPzhzS6b5CMZ-i0d8JZAoTNZH3ULvaU6JR2"]
            },
          "di": "EJZAoTNZH3ULvYAfSVPzhzS6b5CMaU6JR2nmwyZ-i0d8"
        }

2.5. Resolver Metadata

did:keri defines keyState DID Document Metadata (see DID Document Metadata in [[?DID-RESOLUTION]]).¶

• keyState is the verified state of the KEL for the identifier represented by this DID Doc (See Key State).¶

  {
      "didDocument": DID_DOCUMENT_OBJECT,
      "didDocumentMetadata": {
          "keyState":  {
            "v": "KERI10JSON00011c_",
            "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
            "t": "ksn",
            "kt": "1",
            "k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
            "n": "EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM",
            "wt": "1",
            "w": ["DnmwyYAfSVPzhzS6b5CMZ-i0d8JZAoTNZH3ULvaU6JR2"],
            "c": ["eo"],
            "e":
              {
                "s": "2",
                "t": "rot",
                "d": "EAoTNZH3ULvaU6JR2nmwyYAfSVPzhzZ-i0d8JZS6b5CM",
              },
            "ee":
              {
                "s": "1",
                "d": "EAoTNZH3ULvaU6JR2nmwyYAfSVPzhzZ-i0d8JZS6b5CM",
                "wr": ["Dd8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CMZ-i0"],
                "wa": ["DnmwyYAfSVPzhzS6b5CMZ-i0d8JZAoTNZH3ULvaU6JR2"]
              },
            "di": "",
            "a": {}
          }
      }
  }
  

  ¶

2.6. The DID Document

The following field MAY appear in a did:keri DID document: verificationMethod¶

Non-normative note: multiple namespaces using the same DID method could prove control or replay history for one controlling keypair that has been used across multiple ledgers. KERL logs could be stored in a secondary root of trust (i.e., a ledger), and similar or identical resolver metadata could be returned by querying the same identifier there.¶

3.1. Method Name

The method name that identifies this DID method SHALL be: keri¶

A DID that uses this method MUST begin with the following prefix: did:keri:. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is the method specific identifier (MSI) described below.¶

3.2. Method Specific Identifier

The method specific identifier for the did:keri method is the prefix for a content self-addressing self-certifying identifier.¶

A self-addressing, self-certifying identifier is cryptographically bound to the inception keys used to create it. The rationale and process for the derivation of an identifier is described in detail in the Derivation Codes section of [[KID0001]]¶

     did:keri:EXq5YqaL6L48pf0fu7IUhL0JRaU2_RxFP0AL43wYn148

4.1. Create

Creation of a did:keri DID is accomplished by creating, signing and publishing an Inception event. If witnesses are listed in the inception event, the receipts are also required for DID creation to be complete.¶

Detailed steps for prefix derivation are in [[KID0001]] and witness configuration in [[KID0009]]. Inception events are covered in [[KID0003]].¶

4.2. Read

Steps to resolve a `did:keri:$PREFIX` DID:¶

1. Find the Key Event Log for the prefix `$PREFIX`. The method for discovering the Key Event Log is outside the scope of this specification. Possible implementations include the use of a Distributed Hash Table (DHT), anchoring a KEL in a ledger or the use of a gossip protocol involving a witness network.¶
2. Process the KEL into a Key State, according to the state validation rules/semantics of KERI as defined in [[KID0008]]¶
3. Create a DID Document with the DID `did:keri:$PREF`¶
4. For each key K in the Key State, add a Verification Method to the DID Doc containing K and the appropriate type, with the ID of K being K's prefix form (alternatively, the ID could be an integer of K's index in the current signer list)¶
5. Add the Key State as DID Document Metadata as defined inResolver Metadata¶

Establishment of control authority can be done independently of DID document contents, as long as the Key State is provided in the DID Document Metadata. See Resolver Metadata.¶

4.3. Update

Updating a did:keri DID is accomplished by publishing establishment events to the KEL for performing operations such as key rotation and updating signature thresholds, witnesses and delegates.¶

A detailed description of event types, their semantics and uses can be found in [[KID0003]].¶

4.4. Deactivate

Deactivation of a did:keri DID consists of rotation to 0 controlling keys, which terminates the ability to recover the identifier and indicates that the identifier has been abandoned. Identifiers which are delegated to by an abandoned Identifier are also considered abandoned (delegating Ixn events can no longer be created).¶

Detailed steps are specified in [[KID0003]].¶

5.1. Surveillance

A robust witness network along with consistent witness rotation provides protection from monitoring and association of an individual's activity inside a KERI network.¶

5.2. Stored Data Compromise

For resolvers that simply discover the Key State endorsed by another party in a discovery network, caching policies of that network would guide stored data security considerations. In the event that a resolver is also the endorsing party, meaning they have their own KERI identifier and are verifying the KEL and signing the Key State themselves, leveraging the facilities provided by the KERI protocol (key rotation, witness maintenance, multi-sig) should be used to protect the identities used to sign the Key State.¶

See [[KID0005]] for information on KERI key rotation, [[KID0009]] for a discussion on witnesses and [[KID0004]] for KERI's support of multi-sig.¶

5.3. Unsolicited Traffic

DID Documents are not required to provide endpoints and thus not subject to unsolicited traffic.¶

5.4. Misattribution

This DID Method relies on KERI's duplicity detection to determine when the non-repudiable controller of a DID has been inconsistent and can no longer be trusted. This establishment of non-repudiation enables consistent attribution.¶

See [[KID0010]] for a detailed description of KERI’S Agreement Algorithm for Control Establishment (KAACE).¶

5.5. Correlation

The root of trust for KERI identifiers is entropy and therefore offers no direct means of correlation. In addition, KERI provides two modes of communication, direct mode and indirect mode. Direct mode allows for pairwise (n-wise as well) relationships that can be used to establish private relationships.¶

See [[KID0001]] for a description of KID prefix generation and [[KID0009]] for a comparison between Direct and Indirect modes.¶

5.6. Identification

The root of trust for KERI identifiers is entropy and therefore offers no direct means of identification. In addition, KERI provides two modes of communication, direct mode and indirect mode. Direct mode allows for pairwise (n-wise as well) relationships that can be used to establish private relationships.¶

See [[KID0001]] for a description of KID prefix generation and [[KID0009]] for a comparison between Direct and Indirect modes.¶

5.7. Secondary Use

The Key State made available in the metadata of this DID method is generally available and can be used by any party to retrieve and verify the state of the KERL for the given identifier.¶

5.8. Disclosure

No data beyond the Key State for the identifier is provided by this DID method.¶

5.9. Exclusion

This DID method provides no opportunity for correlation (See Section 5.5), identification (See Section 5.6) or disclosure (See Section 5.8) and therefore there is no opportunity to exclude the controller from knowing about data that others have about them.¶

6.1. Key State Verification

Users of a did:keri did method resolver MUST verify the key state returned in the document metadata of the resolution result. The signature of the resolver can be used to determine if the resolver is dysfunctional and should no longer be trusted. However it should not be used to verify the key state.¶

The only definitive method for verifying the key state is to pass the key state to a KERI library and perform the verification of that key state.¶

A breakdown of the security considerations from [[RFC3552]] is provided below.¶

6.2. Confidentiality Violations, Password Sniffing

All private keys used to establish control over the KERI identifier of a KERI DID method DID should be held secret. KERI's use of delegation ensures that private keys for each identifier never need to be transferred. DID controllers can delegate levels of authority of other identities to enable remote agents.¶

See [[KID0007]] for a discussion of delegation.¶

In addition, pre-rotation mechanism provides key rotation capabilities while eliminating exposure of the next public key until it is rotated into the current signing key. Enforcing key rotation for every event of a given identifier provides further protection against key exposure.¶

See [[KID0005]] for a description of pre-rotation and the protections it provides¶

6.3. Replay Attacks

did:keri relies on the KERI protocol which is not susceptible to replay attacks. The hash linking, signatures and sequence numbers of events ensures that replayed messages do not effect the protocol.¶

See [[KID0003]] for a description of KERI events.¶

6.4. Message Insertion, Deletion, Modification

did:keri relies on the KERI protocol which is not susceptible to message deletion or modification attacks. The hash linking, signatures and sequence numbers of events ensures that messages can not be modified or deleted without immediate detection. In addition, KERI's duplicity detection mechanisms allow easy detection of inserted messages allowing validators to determine the consistency of a DID controller.¶

See [[KID0003]] for a description of KERI events and [[KID0010]] for the KAACE algorithm.¶

6.5. Man-In-The-Middle Attacks

The protections mentioned in Replay Attacksand Message Attacksrender Man-In-The-Middle attacks ineffective against the KERI protocol and this DID Method.¶