Decentralized Identifiers (DIDs)

The IDK implements Decentralized Identifiers (DIDs) following the W3C DID Core specification.

What are DIDs?

DIDs are globally unique identifiers that enable verifiable, decentralized digital identity. Unlike traditional identifiers, DIDs:

• Are controlled by the subject, not a central authority
• Can be resolved to DID Documents containing public keys and service endpoints
• Support multiple methods for different use cases and trust models

Supported DID Methods

Method	Description	Use Case	Network Required
did:key	Public key encoded in the identifier	Testing, ephemeral identities	No
did:jwk	JWK encoded in the identifier	JOSE ecosystem interop	No
did:web	Web-hosted DID documents	Production, organizations	Yes

did:key

Self-contained DIDs where the public key is encoded directly in the identifier. No network access required for resolution.

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
        └── Multibase-encoded public key

Supported key types:

• Ed25519 (OKP) - Recommended
• P-256, P-384, P-521 (EC)
• secp256k1 (EC)

did:jwk

DIDs based on JSON Web Keys. The full JWK is base64url-encoded in the identifier.

did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6Ii4uLiIsInkiOiIuLi4ifQ
        └── Base64url-encoded JWK

did:web

Web-hosted DID documents. The identifier maps to a URL where the DID document is hosted.

did:web:example.com              → https://example.com/.well-known/did.json
did:web:example.com:users:alice  → https://example.com/users/alice/did.json

Architecture

The IDK's DID support is organized into focused services:

Managed vs External DIDs

The IDK distinguishes between two DID roles:

Role	Description	Capabilities
MANAGED	Created and controlled locally	Full lifecycle: create, sign, update, deactivate
EXTERNAL	Received from another party	Resolution and verification only

import com.sphereon.did.manager.DidRole

// Check DID role
val managedDid = didManager.findByDid("did:key:z6Mk...")
when (managedDid?.role) {
    DidRole.MANAGED -> println("Can sign with this DID")
    DidRole.EXTERNAL -> println("Resolution only")
    null -> println("DID not found")
}

DID Documents

A DID Document contains the public keys and service endpoints associated with a DID:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:web:example.com",
  "verificationMethod": [{
    "id": "did:web:example.com#key-1",
    "type": "JsonWebKey2020",
    "controller": "did:web:example.com",
    "publicKeyJwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "...",
      "y": "..."
    }
  }],
  "authentication": ["did:web:example.com#key-1"],
  "assertionMethod": ["did:web:example.com#key-1"],
  "service": [{
    "id": "did:web:example.com#hub",
    "type": "LinkedDomains",
    "serviceEndpoint": "https://example.com"
  }]
}

Verification Purposes

Keys can be assigned to different verification purposes:

Purpose	Description
authentication	Prove control of the DID
assertionMethod	Issue verifiable credentials
keyAgreement	Establish encrypted communication
capabilityInvocation	Invoke capabilities
capabilityDelegation	Delegate capabilities

Modules

Module	Description
lib-did-core-public	Core DID models and types
lib-did-resolver-public/impl	DID resolution
lib-did-manager-public/impl	DID lifecycle management
lib-did-methods-key	did:key method
lib-did-methods-jwk	did:jwk method
lib-did-methods-web	did:web method
lib-did-persistence-api	Persistence interfaces
lib-did-persistence-memory	In-memory storage
lib-did-persistence-sqlite	SQLite storage
lib-did-rest-resolver-server	Universal Resolver REST API

Dependencies

Full DID Support

dependencies {
    // Core
    implementation("com.sphereon.idk:lib-did-core-public:0.25.0")

    // Resolution
    implementation("com.sphereon.idk:lib-did-resolver-public:0.25.0")
    implementation("com.sphereon.idk:lib-did-resolver-impl:0.25.0")

    // Management
    implementation("com.sphereon.idk:lib-did-manager-public:0.25.0")
    implementation("com.sphereon.idk:lib-did-manager-impl:0.25.0")

    // Methods
    implementation("com.sphereon.idk:lib-did-methods-key:0.25.0")
    implementation("com.sphereon.idk:lib-did-methods-jwk:0.25.0")
    implementation("com.sphereon.idk:lib-did-methods-web:0.25.0")

    // Persistence
    implementation("com.sphereon.idk:lib-did-persistence-api:0.25.0")
    implementation("com.sphereon.idk:lib-did-persistence-sqlite:0.25.0")
}

Resolution Only

dependencies {
    implementation("com.sphereon.idk:lib-did-core-public:0.25.0")
    implementation("com.sphereon.idk:lib-did-resolver-public:0.25.0")
    implementation("com.sphereon.idk:lib-did-resolver-impl:0.25.0")
    implementation("com.sphereon.idk:lib-did-methods-web:0.25.0")
}

Next Steps

• DID Resolution - Resolve and query DIDs
• DID Management - Create, update, and manage DIDs
• Identifier Resolution - Unified identifier resolution