TODO Working Group P. Feairheller Internet-Draft GLEIF Intended status: Informational 4 May 2023 Expires: 5 November 2023 The did:keri DID Method draft-pfeairheller-did-keri-latest Abstract KERI provides a means for secure and decentralised key management. This specification defines a DID method based on KERI. Discussion Venues This note is to be removed before publishing as an RFC. Source for this draft and an issue tracker can be found at https://github.com/WebOfTrust/ietf-did-keri. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 5 November 2023. Copyright Notice Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction 2. Concepts 2.1. Events 2.2. Key Event Log 2.3. Key Event Receipt Log 2.4. Key State 2.5. Resolver Metadata 2.6. The DID Document 3. The did:keri Format 3.1. Method Name 3.2. Method Specific Identifier 4. Operations 4.1. Create 4.2. Read 4.3. Update 4.4. Deactivate 5. Privacy Considerations 5.1. Surveillance 5.2. Stored Data Compromise 5.3. Unsolicited Traffic 5.4. Misattribution 5.5. Correlation 5.6. Identification 5.7. Secondary Use 5.8. Disclosure 5.9. Exclusion 6. Security Considerations 6.1. Key State Verification 6.2. Confidentiality Violations, Password Sniffing 6.3. Replay Attacks 6.4. Message Insertion, Deletion, Modification 6.5. Man-In-The-Middle Attacks 7. Conventions and Definitions 8. IANA Considerations 9. References 9.1. Normative References 9.2. Informative References Acknowledgments Author's Address 1. Introduction The Key Event Receipt Infrastructure is a system for secure self- certifying Identifiers which aims at minimum sufficiency and maximum security. It defines mechanisms for proving the Root of Trust for self-certifying Identifiers and their associated Key State. This spec defines a transform from Key State to DID Document, such that any valid Key Event Log can be processed into a DID Document. A close analogy is did:peer, except that where the data model of did:peer is a DID Document and JSON patches on said Document, the basic data model of did:keri is an append-only log of Key Events. KERI-based Identifiers are suitable for both any-wise and n-wise purposes. 2. Concepts 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 (https://github.com/decentralized-identity/keri/blob/master/kids/ kid0003.md#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 (https://w3c-ccg.github.io/did-resolution/#output- documentmetadata) 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. The did:keri Format The format for the did:keri method conforms to the [[DID-CORE]] specification and is simple. It consists of the did:keri: prefix, followed by the identifier prefix. 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 (https://github.com/decentralized- identity/keri/blob/master/kids/kid0001.md#derivation-codes) section of [[KID0001]] did:keri:EXq5YqaL6L48pf0fu7IUhL0JRaU2_RxFP0AL43wYn148 4. Operations The following section outlines the DID operations for the did:keri method. 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. Privacy Considerations A breakdown of the privacy considerations from [[RFC6973]] section 5 is provided below. 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. Security Considerations 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. 7. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 8. IANA Considerations This document has no IANA actions. 9. References 9.1. Normative References [CESR] Smith, S., "Composable Event Streaming Representation (CESR)", 2021, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 9.2. Informative References [KERI] Smith, S., "Key Event Receipt Infrastructure (KERI)", 2021, . Acknowledgments TODO acknowledge. Author's Address Phil Feairheller GLEIF Email: Philip.Feairheller@gleif.org