Comprehensive Explanation

registrar

Process Definition

A registrar in the KERI ecosystem is an AID (Autonomic Identifier) that functions as a backer for transaction event logs (TELs). Registrars provide secondary root-of-trust services specifically for credential lifecycle management, operating within the public verifiable credential registry infrastructure.

Core Functions

Registrars accomplish several critical functions:

1. TEL Backing: Provide witnessing and verification services for transaction event logs that track credential issuance and revocation states
2. State Persistence: Maintain copies of TEL events to ensure availability and verifiability
3. Consensus Participation: Participate in agreement protocols for TEL event validation
4. Discovery Support: Enable discovery of credential state information through various mechanisms

When Registrars Are Used

Registrars are employed when:

• A QVI (Qualified vLEI Issuer) or other credential issuer establishes a public verifiable credential registry
• Credential lifecycle events (issuance, revocation) need to be tracked in a verifiable, distributed manner
• High-availability access to credential state information is required
• The credential ecosystem requires separation between key management (KEL) and credential state management (TEL)

Key Participants

The registrar process involves:

• Credential Issuers: Controllers who create and manage credentials, anchoring TEL events to their KELs
• Registrars: Identifiers designated to back specific TELs, providing witnessing services
• Validators/Verifiers: Entities that query registrars to verify credential state
• Management TEL Controllers: Entities that maintain the list of authorized registrars

Process Flow

Registry Initialization

The registrar process begins with the creation of a management TEL:

1. Management TEL Inception: The credential issuer creates a management TEL that signals the creation of a Virtual Credential Registry (VCR)
2. Registrar List Establishment: The management TEL includes an initial list of registrar AIDs that will serve as backers
3. KEL Anchoring: The management TEL inception event is anchored to the issuer's KEL through event source seals
4. Registrar Notification: Designated registrars are notified (typically via OOBI) of their role

Credential Lifecycle Management

For each credential issued:

1. VC TEL Creation: A VC TEL is created for the specific credential
2. Management TEL Reference: The VC TEL contains a reference to its corresponding management TEL
3. Issuance Event: An issuance event is created in the VC TEL and anchored to the issuer's KEL
4. Registrar Witnessing: Registrars designated in the management TEL receive and witness the VC TEL events
5. State Tracking: The VC TEL tracks state transitions (issued, revoked) for the credential

Registrar Rotation

The list of registrars can be updated:

1. Rotation Event Creation: The management TEL controller creates a rotation event specifying the new registrar list
2. KEL Anchoring: The rotation event is anchored to the controller's KEL
3. Registrar Transition: New registrars are onboarded while old registrars may be phased out
4. State Continuity: Existing VC TELs continue to reference the management TEL, which now points to the updated registrar list

State Verification

When a verifier needs to check credential state:

1. Registrar Discovery: The verifier discovers registrar endpoints through OOBIs, well-known URIs, or other discovery mechanisms
2. TEL Query: The verifier queries one or more registrars for the VC TEL associated with a specific credential
3. Event Validation: The verifier validates the TEL events by checking their anchoring to the issuer's KEL
4. State Determination: The verifier determines the current credential state (issued, revoked) based on the validated TEL

Technical Requirements

Cryptographic Requirements

Registrars must satisfy several cryptographic constraints:

Identifier Type: According to Document 30, registrars should use non-transferable AIDs (ephemeral identifiers) for their own identity. This design choice means registrar security relies on pool-based threshold structures rather than individual key rotation capabilities.

Cryptographic Strength: All registrar key-pairs must provide approximately 128 bits of cryptographic strength. Compliant algorithms include:

• Ed25519 for digital signatures
• EcDSASecp256k1 for ECDSA-based signatures
• CESR-compatible encoding for all cryptographic primitives

Signature Verification Infrastructure: Registrars must implement robust signature verification for:

• TEL event signatures from credential issuers
• KEL event signatures that anchor TEL events
• Event source seals that bind TEL events to KEL events

Ledger-Based Registrars

When registrars use distributed ledger technology (DLT) for TEL storage:

Approved DID Methods: According to Document 30, registrars must use GLEIF Approved DID Methods when operating as ledger backers. Approval is required down to the individual ledger implementation level, not just the DID method specification.

Single Registrar Recommendation: The specification states registrars should use only one Registrar per KEL when using ledger-based backing to maintain consistency and avoid synchronization complexity.

Ledger-Specific Security: Each ledger implementation must provide appropriate security guarantees for the use case, including:

• Immutability of recorded TEL events
• Availability of historical state information
• Resistance to censorship or manipulation

Witness Pool Configuration

When registrars operate as traditional KERI witnesses (non-ledger mode):

Minimum Pool Size: Must use a minimum pool of 5 witnesses with KAACE (KERI's Agreement Algorithm for Control Establishment) sufficient majority threshold.

Access Control Independence: Registrars should use access control independent of the Controller keys for:

• Configuring the registrar host infrastructure
• Accepting events for witnessing
• This prevents poisoning attacks if controller keys are compromised

Discovery Mechanisms: Registrars must publish their endpoints through multiple channels:

• Well-Known URIs: Following IETF RFC-8615 on websites associated with the entity
• OOBIs: Out-of-band introductions for direct discovery
• KERI DHT: Distributed hash table for decentralized discovery
• DID Resolvers: For DID-based identifier resolution
• Ledgers: For ledger-backed registrar discovery

Timing Considerations

Event Queuing: According to Document 29, registrars should implement event queuing mechanisms that operate during a period of time to allow several block confirmations as a safety measure. This is particularly critical for ledger-based registrars to protect against blockchain reorganizations.

Confirmation Delays: The queuing system should wait for sufficient confirmations before events are considered stably anchored, protecting against:

• Blockchain forks
• Reorganizations that could affect event ordering
• Temporary network partitions

Error Handling

Registrars must handle several error conditions:

Duplicity Detection: If a registrar receives conflicting TEL events for the same credential, it must:

• Record both versions in a duplicitous event log (DEL)
• Report the duplicity to validators
• Refuse to provide a single authoritative state until the conflict is resolved

KEL Validation Failures: If TEL events cannot be validated against their anchoring KEL:

• Reject the events as invalid
• Do not propagate unverifiable state information
• Log the validation failure for audit purposes

Network Partitions: During network partitions:

• Continue accepting events from reachable issuers
• Maintain eventual consistency when connectivity is restored
• Use BADA (Best Available Data Acceptance) policies for conflict resolution

Usage Patterns

Typical Scenarios

Enterprise Credential Issuance: In the vLEI ecosystem, QVIs use registrars to track the lifecycle of:

• Legal Entity vLEI Credentials
• Official Organizational Role (OOR) credentials
• Engagement Context Role (ECR) credentials

The registrar infrastructure enables verifiers to check credential validity without contacting the issuer directly, improving scalability and privacy.

Supply Chain Credentials: Organizations issuing supply chain credentials use registrars to:

• Track product authenticity credentials
• Manage chain-of-custody attestations
• Enable downstream verification without centralized infrastructure

Educational Credentials: Educational institutions use registrars to:

• Publish degree and certificate issuance/revocation state
• Enable employer verification without student involvement
• Maintain long-term credential validity records

Best Practices

Registrar Selection: When choosing registrars:

• Select entities with strong operational security practices
• Prefer geographically and jurisdictionally diverse registrars
• Consider using a mix of organizational and ledger-based registrars
• Ensure registrars have appropriate service level agreements

Registrar Pool Management: For optimal security and availability:

• Use threshold structures where credential state is considered valid when confirmed by a sufficient majority of registrars
• Implement registrar rotation policies to refresh the registrar pool periodically
• Monitor registrar availability and performance metrics
• Have contingency plans for registrar failures or compromises

Privacy Considerations: When privacy is important:

• Consider using blinded revocation registries where state is hidden until presentation
• Implement salty nonce blinding factors to prevent rainbow table attacks
• Use selective disclosure mechanisms to limit correlation

Ledger Integration: When using ledger-based registrars:

• Ensure the ledger provides appropriate finality guarantees
• Implement sufficient confirmation delays for blockchain-based registrars
• Consider the cost and performance implications of on-chain storage
• Evaluate the governance and security model of the underlying ledger

Integration Considerations

KERI Agent Integration: When integrating registrars with KERIA (KERI Agent):

• Use the KAPI (KERI Application Programming Interface) for standardized interactions
• Implement proper KRAM (KERI Request Authentication Method) for replay attack protection
• Support IPEX (Issuance and Presentation Exchange) for credential workflows

Witness Infrastructure Reuse: Registrars can leverage existing witness infrastructure:

• The same software components can serve both witness and registrar roles
• Witnesses for KELs can also serve as registrars for TELs
• This reuse reduces operational complexity and infrastructure costs

Discovery Protocol Integration: Registrars should integrate with:

• OOBI protocols for initial discovery
• Percolated discovery mechanisms for decentralized endpoint location
• Watcher networks for aggregated discovery services

Credential Presentation Workflows: During credential presentation:

• Verifiers should query multiple registrars for redundancy
• Implement caching strategies to reduce registrar query load
• Support both synchronous and asynchronous verification patterns
• Handle registrar unavailability gracefully with fallback mechanisms

Relationship to KERI Architecture

Registrars represent a parallel infrastructure component to the backer/witness model used in KELs, adapted specifically for transaction event logs that track credential issuance and revocation states. This architectural parallelism means:

• KEL witnesses provide consensus for key state changes
• TEL registrars provide consensus for credential state changes
• Both use similar agreement algorithms and threshold structures
• Both enable decentralized verification without centralized infrastructure

The separation between KEL and TEL infrastructure allows:

• Independent scaling of key management and credential management
• Different security models for keys versus credentials
• Specialized optimization for each use case
• Flexible deployment where KEL and TEL infrastructure can be co-located or separated

This design reflects KERI's broader philosophy of creating composable, modular infrastructure where each component serves a specific purpose while maintaining interoperability through standardized protocols and cryptographic verification mechanisms.