DID Document

The most fundamental verification method, listing cryptographic public keys. These keys are used for digital signatures and encryption.

• Example Types: Ed25519VerificationKey2020, EcdsaSecp256k1VerificationKey2019, RSAVerificationKey2018.
• Structure: Includes the public key material, its ID (e.g., #key-1), controller (the DID), and type.
• Usage: Proves control of the corresponding private key for signing verifiable credentials or authentication challenges.

Links the DID to a specific blockchain account address, enabling on-chain verification of ownership and actions.

• Example Types: EcdsaSecp256k1RecoveryMethod2020, Ed25519BlockchainAccountId.
• Mechanism: The verification method contains the blockchain account address (e.g., an Ethereum 0x... address). A verifier can check that a signature from that address corresponds to a transaction or message linked to the DID.
• Use Case: Directly proving control of a wallet for decentralized finance (DeFi) or NFT interactions.

Properties within the DID Document that specify how each verification method can be used, defining its authorization scope.

• Key Properties:
  • authentication: Proves the DID subject is interacting with an entity (for logging in).
  • assertionMethod: Used for signing verifiable credentials and assertions.
  • keyAgreement: Establishes encrypted communication channels.
  • capabilityInvocation: Authorizes changes to the DID Document itself.
• Flexibility: A single verification method (like a public key) can be referenced by multiple relationships.

Verification methods can be defined directly within the DID Document or referenced from an external source.

• Embedded Method: The full public key or cryptographic data is included directly in the verificationMethod array. This is the most common approach.
• Referenced Method: The verificationMethod array contains a reference (URI) to a key or proof located elsewhere, such as a blockchain transaction or a secure hardware module. This is useful for key rotation or hardware security modules (HSMs).

Verification methods are often associated with specific cryptographic suites that define the exact algorithms and data formats for creating and verifying proofs.

• Linked Data Proofs: Standards like Ed25519Signature2020 or JsonWebSignature2020 define how to create a machine-readable, cryptographically-verifiable proof using a referenced verification method.
• Interoperability: Using standardized suites ensures verifiers from different systems can understand and validate the proofs generated by the DID subject.

A DID Document is a JSON object containing essential information for a DID. Its core components include:

• id: The DID itself, serving as the document's primary identifier.
• verificationMethod: An array of public keys, cryptographic suites, or other verification methods (e.g., Ed25519VerificationKey2020).
• authentication: Specifies which verification methods can be used to authenticate the DID subject.
• assertionMethod: Specifies methods for creating verifiable credentials.
• service: An array of service endpoints (e.g., a linked storage location, a messaging service) for interacting with the DID subject.

The process of retrieving a DID Document from its DID identifier is called resolution. This is performed by a DID Resolver, which follows the rules of the specific DID method.

• The resolver queries the underlying system (e.g., a blockchain, a distributed ledger, or a P2P network) where the DID is anchored.
• It fetches the corresponding DID Document data, which may be stored on-chain or referenced via a content-addressable system like IPFS.
• The output is a DID Resolution Result, a wrapper containing the document, metadata, and resolution status.

DID Documents are defined by the World Wide Web Consortium (W3C) as a core part of the Decentralized Identifiers (DIDs) v1.0 specification. The standard mandates the use of JSON-LD (JavaScript Object Notation for Linked Data).

• JSON-LD provides a formal data model and context (@context), enabling semantic interoperability.
• This allows documents to be understood as a graph of linked data, making them processable by machines across different systems and DID methods.
• The @context field typically points to https://www.w3.org/ns/did/v1.

Different DID methods store and manage DID Documents in distinct ways, influencing their structure and capabilities.

• did:ethr (Ethereum): The document is derived from an on-chain registry smart contract; public keys are Ethereum addresses.
• did:key: A simple, self-contained method where the public key is encoded directly into the DID itself, and the document is generated algorithmically.
• did:web: The DID Document is hosted at a predictable HTTPS URL, enabling easy adoption for web services.
• did:ion (Sidetree/ION): Uses a Layer 2 protocol on Bitcoin to create scalable, high-throughput DID operations with document history.

The service array is a critical component for enabling real-world interactions. It allows a DID controller to declare how they can be reached or what services they offer.

• Common endpoint types: LinkedDomains, DIDCommMessaging, CredentialRepository.
• For example, a DIDCommMessaging endpoint allows other entities to send encrypted messages to the DID subject.
• This design decouples the persistent identifier (DID) from ephemeral service locations, enabling seamless service migration and interoperability across different agent frameworks and ecosystems.

DID Documents are not static; they can be updated by entities that prove control. This is governed by the verificationMethod and authentication sections.

• To update a document (e.g., rotate a key, add a service), a controller must sign the update operation with a private key corresponding to a listed verification method.
• The specific update mechanism (e.g., a blockchain transaction, a signed patch file) is defined by the DID method.
• This provides a secure, cryptographic basis for self-sovereign identity, where the subject maintains control without relying on a central authority.