Process Flow

The designated aliases process follows a structured sequence of operations that establish, maintain, and verify the relationship between a primary AID and its designated aliases.

Step 1: Alias Identifier Creation

The process begins with the creation of the alias identifier itself. For did:webs identifiers, this involves:

1. AID Inception: The controller creates or uses an existing KERI AID with its associated KEL (Key Event Log)
2. DID Generation: A did:webs identifier is generated following the did:webs method specification, which includes:
   • Domain component (e.g., did.example.com)
   • Path component (often including the AID prefix)
   • Method-specific identifier string
3. DID Document Creation: A DID document is generated containing:
   • The did:webs identifier as the subject
   • Verification methods derived from the AID's current key state
   • Service endpoints for KERI protocol operations
   • The alsoKnownAs field (initially empty, to be populated by the designation process)

For did:keri identifiers, the process is more direct as the DID is essentially a wrapper around the native KERI AID, but the designation process remains the same.

Step 2: Attestation Creation

The controller creates a designated aliases attestation, which is a specialized ACDC (Authentic Chained Data Container) with unique characteristics:

1. No Issuee: Unlike typical ACDCs that have both an issuer and an issuee, the designated aliases attestation has no issuee field. This is because the attestation is self-referential—the controller is making a statement about their own identifiers.

2. Attestation Structure: The ACDC contains:

   • Issuer (i): The primary AID making the designation
   • Schema (s): Reference to the designated aliases schema (SAID: as documented in the schema registry)
   • Attributes (a): An array listing the designated identifiers
   • Registry (ri): Reference to the TEL registry managing the attestation status

3. Identifier List: The attributes section contains the complete list of identifiers being designated as aliases, which may include:

   • did:keri identifiers
   • did:webs identifiers
   • Other AID-controlled identifier formats

Example attestation structure (conceptual):

{
  "v": "ACDC10JSON00011c_",
  "d": "EAdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
  "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
  "ri": "EACmRy7xMwsxUelUauaXtMxTfPAMPAI6FkekeolOjkggt",
  "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao",
  "a": {
    "aliases": [
      "did:webs:did.example.com:EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
      "did:keri:EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"
    ]
  }
}

Step 3: Registry Anchoring

The designated aliases attestation must be anchored to the controller's KEL through a registry mechanism:

1. Registry Creation: If not already existing, a credential registry (TEL) is created for the issuing AID
2. Issuance Event: An issuance event is created in the TEL, recording:
   • The SAID of the designated aliases ACDC
   • The issuance timestamp
   • The issuer's AID
3. KEL Anchoring: The TEL issuance event is anchored to the issuer's KEL through an interaction event containing a seal of the TEL event
4. Witness Receipts: The KEL interaction event is witnessed according to the AID's witness configuration, providing distributed validation

This anchoring process ensures that:

• The designation is cryptographically bound to the controller's key state
• The designation can be verified by following the chain from the alias back to the KEL
• The designation's status (issued, revoked) can be tracked through the TEL

Step 4: DID Document Population

Once the attestation is created and anchored, the designated aliases populate the DID documents:

1. DID Document Update: For did:webs identifiers, the DID document's alsoKnownAs field is populated with:

   • The primary AID (in did:keri format if applicable)
   • Other designated aliases from the attestation
   • The equivalentId field may also be populated for stronger equivalence claims

2. Publication: The updated DID document is published to the web location specified by the did:webs method (typically at https://{domain}/.well-known/did.json or a path-specific location)

3. KERI Event Stream: The keri.cesr file (containing the KEL and TEL events) is published alongside the DID document, enabling full verification of the designation

Example DID document with designated aliases:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:webs:did.example.com:EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
  "alsoKnownAs": [
    "did:keri:EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"
  ],
  "verificationMethod": [
    {
      "id": "did:webs:did.example.com:EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM#key-1",
      "type": "JsonWebKey2020",
      "controller": "did:webs:did.example.com:EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
      "publicKeyJwk": {
        "kty": "OKP",
        "crv": "Ed25519",
        "x": "..."
      }
    }
  ]
}

Step 5: Verification Process

Verifiers can validate the designated aliases relationship through a multi-step verification process:

1. DID Resolution: Resolve the did:webs identifier to obtain the DID document
2. KERI Stream Retrieval: Fetch the keri.cesr file from the web location
3. KEL Verification: Verify the KEL events, including:
   • Inception event validation
   • Key rotation verification
   • Witness receipt validation
4. TEL Verification: Verify the TEL events, including:
   • Registry inception
   • Credential issuance event
   • Current status (not revoked)
5. Attestation Verification: Verify the designated aliases ACDC:
   • SAID integrity
   • Issuer signature
   • Schema compliance
   • Presence of the alias in the attestation's attributes
6. Cross-Reference Validation: Confirm that the alsoKnownAs field in the DID document matches the aliases listed in the attestation

Step 6: Status Management

The designated aliases mechanism supports dynamic status management:

1. Revocation: The controller can revoke the designation by:

   • Creating a revocation event in the TEL
   • Anchoring the revocation to the KEL
   • Updating the DID document to remove the alias from alsoKnownAs

2. Rotation: If the primary AID undergoes key rotation:

   • The KEL records the rotation event
   • The TEL remains valid (anchored to the AID, not specific keys)
   • The DID document's verification methods are updated to reflect new keys
   • The alsoKnownAs relationships remain intact

3. Addition: New aliases can be added by:

   • Creating a new designated aliases attestation (or updating the existing one)
   • Following the same anchoring and publication process
   • Updating all relevant DID documents

Technical Requirements

Cryptographic Requirements

The designated aliases mechanism relies on several cryptographic primitives and properties:

1. SAID Integrity: All ACDCs and critical data structures must use SAIDs (Self-Addressing Identifiers) to ensure content integrity. The SAID is computed as a cryptographic digest of the content, creating an immutable binding between the identifier and the data.

2. Digital Signatures: The designated aliases attestation must be signed by the issuing AID's current authoritative keys. The signature must:

   • Use the cryptographic suite specified in the AID's key state (typically Ed25519)
   • Be attached in CESR format for composability
   • Be verifiable against the public keys in the KEL at the time of issuance

3. Key State Verification: Verifiers must validate the entire key state history:

   • Verify all establishment events (inception and rotations)
   • Validate pre-rotation commitments
   • Confirm witness receipts meet the threshold
   • Ensure no duplicity in the KEL

4. TEL Anchoring: The TEL events must be properly anchored to the KEL through interaction events containing seals. The seal must include:

   • The TEL event's SAID
   • The TEL event's sequence number
   • Proper CESR encoding

5. Schema Validation: The designated aliases ACDC must conform to the official schema, which defines:

   • Required fields (issuer, schema, attributes)
   • Attribute structure (array of alias identifiers)
   • Absence of issuee field
   • Registry reference requirements

Timing Considerations

Several timing factors affect the designated aliases process:

1. Witness Propagation: After creating KEL events, time must be allowed for:

   • Witness receipt collection (typically milliseconds to seconds)
   • Witness consensus on event ordering
   • Receipt propagation to watchers and other infrastructure

2. DID Document Caching: did:webs resolvers may cache DID documents, leading to:

   • Stale alias information if updates occur
   • Need for cache invalidation strategies
   • TTL considerations for web-hosted documents

3. TEL Synchronization: The TEL must be synchronized with the KEL:

   • TEL events should be anchored promptly after creation
   • Verifiers may need to wait for KEL propagation before TEL verification
   • Out-of-order event handling must be supported

4. Revocation Timing: When revoking a designation:

   • The TEL revocation event must be created first
   • KEL anchoring must occur before DID document updates
   • Grace periods may be needed for verifier synchronization

Error Handling

Robust error handling is essential for the designated aliases mechanism:

1. Missing KEL Events: If KEL events cannot be retrieved:

   • Verifiers should reject the alias relationship
   • Fallback to cached KEL data may be acceptable with appropriate warnings
   • Retry mechanisms should be implemented with exponential backoff

2. TEL Inconsistencies: If TEL events conflict with KEL:

   • The KEL is authoritative
   • TEL events not properly anchored should be rejected
   • Verifiers should check for duplicity in both KEL and TEL

3. Schema Violations: If the attestation doesn't match the schema:

   • The designation should be rejected
   • Specific schema validation errors should be reported
   • Partial compliance should not be accepted

4. Signature Failures: If signatures cannot be verified:

   • The entire designation chain should be rejected
   • Key state at the time of signing must be reconstructed
   • Rotation events must be properly validated

5. Network Failures: When web resources are unavailable:

   • Implement retry logic with appropriate timeouts
   • Consider cached data with staleness warnings
   • Provide clear error messages about verification limitations

Usage Patterns

Typical Scenarios

Designated aliases are commonly used in several scenarios:

1. DID Method Bridging: Organizations using KERI infrastructure but needing W3C DID compatibility:

   • Create a primary KERI AID for core operations
   • Designate did:webs aliases for external interactions
   • Maintain single key management infrastructure
   • Enable verification through either method

2. Multi-Platform Identity: Entities operating across multiple ecosystems:

   • Use native KERI AIDs for KERI-aware systems
   • Designate did:webs for web-based verifiers
   • Designate did:keri for DID-aware but KERI-native systems
   • Maintain consistent identity across all platforms

3. Human-Readable Identifiers: Creating user-friendly identifiers:

   • Primary AID: EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM
   • Designated alias: did:webs:alice.example.com:alice
   • Users interact with readable identifier
   • System verifies through cryptographic AID

4. Legacy System Integration: Supporting systems that require specific identifier formats:

   • Maintain KERI security properties
   • Present identifiers in legacy-compatible formats
   • Enable gradual migration to KERI
   • Preserve verification capabilities

Best Practices

Implementers should follow these best practices:

1. Minimize Aliases: Create only necessary aliases to:

   • Reduce management overhead
   • Simplify verification
   • Minimize potential for confusion
   • Limit attack surface

2. Consistent Naming: Use consistent patterns for alias creation:

   • Include the primary AID in did:webs paths when possible
   • Use meaningful domain names
   • Document the relationship between aliases
   • Maintain naming conventions across the organization

3. Regular Auditing: Periodically review designated aliases:

   • Verify all aliases are still needed
   • Check for orphaned or unused aliases
   • Ensure DID documents are synchronized
   • Validate TEL status consistency

4. Revocation Planning: Establish clear revocation procedures:

   • Document when aliases should be revoked
   • Implement automated revocation for compromised keys
   • Communicate revocations to relying parties
   • Maintain revocation history for audit purposes

5. Documentation: Maintain comprehensive documentation:

   • List all designated aliases for each AID
   • Document the purpose of each alias
   • Record creation and revocation dates
   • Provide verification instructions for each alias type

Integration Considerations

Integrating designated aliases into existing systems requires careful planning:

1. Resolver Integration: DID resolvers must:

   • Support both did:keri and did:webs methods
   • Implement KERI event stream verification
   • Handle alsoKnownAs relationships correctly
   • Cache appropriately while respecting freshness requirements

2. Wallet Support: Digital wallets should:

   • Display all designated aliases for an AID
   • Allow users to select which alias to present
   • Verify alias relationships before use
   • Warn users about revoked aliases

3. Verifier Implementation: Verifiers must:

   • Support multiple identifier formats
   • Verify the complete chain from alias to KEL
   • Check TEL status for all credentials
   • Handle verification failures gracefully

4. Key Management: Key management systems should:

   • Treat all aliases as references to the same key material
   • Update all aliases when keys rotate
   • Revoke all aliases if keys are compromised
   • Maintain audit logs for all alias operations

5. Monitoring and Alerting: Operational systems should:

   • Monitor KEL and TEL synchronization
   • Alert on verification failures
   • Track alias usage patterns
   • Detect potential security issues

The designated aliases mechanism provides a powerful tool for bridging KERI's cryptographic security with the practical needs of diverse identifier ecosystems, enabling organizations to maintain strong security properties while supporting multiple identifier formats and use cases.

Verification Implementation

1. Complete Chain Verification: Verifiers must validate the entire chain:

   • Resolve the alias identifier to get the DID document
   • Fetch the KERI event stream (keri.cesr)
   • Verify the KEL from inception through current state
   • Verify the TEL events and their anchoring
   • Validate the designated aliases attestation
   • Confirm the alias appears in the attestation

2. Caching Considerations: Implement intelligent caching:

   • Cache KEL events (they are immutable once witnessed)
   • Cache DID documents with appropriate TTLs
   • Invalidate caches on key rotation events
   • Implement cache warming for frequently accessed identifiers

3. Error Handling: Implement robust error handling:

   • Distinguish between temporary network failures and permanent verification failures
   • Provide clear error messages indicating which verification step failed
   • Implement retry logic with exponential backoff
   • Log verification attempts for debugging and auditing

Security Considerations

1. Key Management: All designated aliases share the same underlying key material. Compromise of the primary AID's keys compromises all aliases. Implement:

   • Hardware security modules (HSMs) for key storage when appropriate
   • Multi-signature configurations for high-value identifiers
   • Regular key rotation schedules
   • Immediate revocation procedures for compromised keys

2. Revocation Procedures: When revoking a designation:

   • Create the TEL revocation event first
   • Anchor it to the KEL before updating DID documents
   • Update all DID documents to remove the alias from alsoKnownAs
   • Notify relying parties of the revocation
   • Maintain revocation history for audit purposes

3. Duplicity Detection: Monitor for duplicity in both KEL and TEL:

   • Implement watcher networks to detect conflicting events
   • Alert on any detected duplicity immediately
   • Have procedures for resolving duplicity incidents
   • Consider the designation invalid if duplicity is detected

Performance Optimization

1. Batch Operations: When managing multiple aliases:

   • Create a single attestation listing all aliases rather than multiple attestations
   • Batch KEL and TEL operations where possible
   • Update all DID documents in parallel

2. Witness Selection: Choose witnesses strategically:

   • Distribute witnesses geographically for availability
   • Use witnesses with high uptime and reliability
   • Consider witness performance when setting thresholds
   • Monitor witness responsiveness and replace slow witnesses

3. Resolution Optimization: For high-volume systems:

   • Implement aggressive caching of immutable data (KEL events)
   • Use CDNs for DID document distribution
   • Pre-compute verification results where possible
   • Implement parallel verification of independent components

Testing and Validation

1. Test Coverage: Implement comprehensive tests:

   • Attestation creation with various alias types
   • KEL and TEL anchoring verification
   • DID document generation and validation
   • Complete verification chain testing
   • Revocation and status management
   • Error handling and recovery

2. Integration Testing: Test with real infrastructure:

   • Deploy to test witness networks
   • Test with actual DID resolvers
   • Verify cross-platform compatibility
   • Test with various client implementations

3. Security Testing: Conduct security assessments:

   • Attempt to create invalid attestations
   • Test verification with tampered data
   • Verify revocation enforcement
   • Test key rotation scenarios
   • Assess resistance to replay attacks