#Understanding Controller Documents

This document explains Controller Documents (also known as Controlled Identifier Documents), a core concept in the W3C Controlled Identifier (CID) specification. Controller Documents serve as the foundation for verifiable cryptographic interactions in the Vidos ecosystem.

#What are Controller Documents?

Controller Documents are machine-readable documents that contain cryptographic material and service endpoints used to verify proofs from, and interact with, the controller of an identifier. In essence, they establish a trust anchor by providing the verification methods necessary to validate that someone has authority over a specific identifier.

Controller Documents are closely related to DID Documents in the Decentralized Identifiers ecosystem, serving as a more generalized concept that DID Documents implement.

Think of a Controller Document as a digital identity card that doesn't contain personal information but instead holds the cryptographic keys and service information needed to:

1. Verify digital signatures
2. Establish encrypted communication channels
3. Access services associated with the identifier
4. Prove control of the identifier

Controller Documents enable secure, verifiable interactions without requiring centralized authorities to validate identity claims.

#Core Components

A Controller Document consists of several key components:

#Identifiers

Every Controller Document includes identifiers that establish its context:

• Subject: The entity that the document describes, identified by the id property.
• Controller: The entity with authority to make changes to the document, which may be the same as or different from the subject.
• Also Known As: Optional additional identifiers for the same subject, creating connections between different identity systems.

#Verification Methods

Verification methods provide the cryptographic material necessary to verify proofs created by or on behalf of the subject. They typically include:

• Public Keys: Cryptographic keys used to verify signatures, authenticate messages, or establish encrypted communication.
• Other Verification Material: Methods specific to particular use cases or cryptographic systems.

Each verification method has:

• A unique identifier
• A type (indicating the cryptographic algorithm)
• The actual verification material (e.g., public key)
• A controller reference

#Verification Relationships

Verification relationships express how specific verification methods can be used for different purposes:

• Authentication: Methods for proving identity
• Assertion: Methods for issuing verifiable claims
• Key Agreement: Methods for establishing encrypted communications
• Capability Invocation: Methods for invoking capabilities
• Capability Delegation: Methods for delegating authority to others

These relationships allow precise control over which keys can be used for which operations.

#Services

Services define endpoints for interacting with the subject beyond cryptographic verification:

• Each service has a unique identifier
• Services have specific types that define their purpose
• Service endpoints provide the network location for accessing the service

Services might include verification credential issuers, messaging endpoints, or data storage locations.

#Controller Document Structure

Controller Documents follow a structured data model with standardized properties:

{
    "@context": "https://www.w3.org/ns/cid/v1",
    "id": "https://controller.example",
    "controller": "https://controller.example",
    "verificationMethod": [
        {
            "id": "https://controller.example#key-1",
            "type": "Multikey",
            "controller": "https://controller.example",
            "publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
        }
    ],
    "authentication": ["https://controller.example#key-1"],
    "assertionMethod": ["https://controller.example#key-1"],
    "service": [
        {
            "id": "https://controller.example#messaging",
            "type": "MessagingService",
            "serviceEndpoint": "https://example.com/messages"
        }
    ]
}

The Controller Document can be represented in different formats, with JSON and JSON-LD being the most common. Each format must preserve the complete data model.

#How Controller Documents Function in Vidos

Within the Vidos ecosystem, Controller Documents play a crucial role in the verification workflow:

#Resolution Process

When a verification operation is initiated, the system first needs to access the Controller Document associated with the relevant identifier:

1. A resolver service takes an identifier as input
2. The resolver retrieves the associated Controller Document
3. The document provides the verification methods needed for cryptographic validation
4. Other services can then use these methods for authentication, verification, or encryption

This process establishes trust without requiring centralized identity providers. The resolution process follows patterns similar to DID Resolution but is generalized to work with various identifier types.

#Integration with Vidos Services

Controller Documents interact with several core Vidos services:

#Resolver Service

The Resolver Service translates identifiers into their associated Controller Documents, making them available for verification operations. It supports multiple methods for resolving different types of identifiers, similar to how DID resolvers work with DID Methods.

#Verifier Service

The Verifier Service uses the cryptographic material in Controller Documents to verify digital signatures, credentials, and other claims. It relies on the Resolver to access the appropriate verification methods.

#Validator Service

The Validator Service ensures that Controller Documents and associated credentials conform to expected schemas and business rules before they're processed by other services.

#Authorizer Service

The Authorizer Service uses verification methods from Controller Documents to authenticate entities and authorize access to protected resources.

#Library Service

The Library Service provides reusable components for working with Controller Documents across different applications and services.

#Use Cases for Controller Documents

Controller Documents enable several key verification scenarios:

#Identity Verification

By providing cryptographic proof of control over an identifier, Controller Documents allow secure authentication without passwords or centralized identity providers. This aligns with the authentication verification relationship defined in the specification.

#Credential Verification

When verifying credentials, systems use the verification methods in Controller Documents to validate that signatures were created with the corresponding private keys.

#Secure Communication

Controller Documents provide the public keys needed for establishing encrypted communication channels with the subject or controller.

#Service Discovery

Through service endpoints, Controller Documents offer a standardized way to discover how to interact with an identifier beyond cryptographic operations. This functions similarly to service endpoints in DID Documents.

#Capability Authorization

Verification relationships in Controller Documents define which keys can be used for specific operations, enabling precise access control.

#Benefits of Controller Documents

Controller Documents provide several advantages for verification systems:

#Decentralized Control

By separating cryptographic material from centralized authorities, Controller Documents enable self-sovereign control over digital identifiers.

#Cryptographic Trust

Controller Documents establish a foundation for cryptographically verifiable digital relationships without relying on trusted intermediaries.

#Interoperability

The standardized structure of Controller Documents enables interoperability across different systems, networks, and applications.

#Enhanced Privacy

Controller Documents contain no personal data, only the cryptographic and service information needed for secure interaction.

#Future-Proof Security

Controller Documents can be updated to incorporate new cryptographic methods as technology evolves, providing long-term security.

#Summary

Controller Documents are foundational elements of decentralized verification systems. They provide the cryptographic material and service information needed for secure, verifiable interactions while maintaining privacy and decentralized control.

In the Vidos ecosystem, Controller Documents facilitate the connections between identifiers and verification methods, enabling a comprehensive trust framework built on open standards. By implementing the W3C Controlled Identifier specification, Vidos ensures interoperability with the broader ecosystem of verifiable credentials and decentralized identifiers.

#Related Resources

#W3C Specifications

• W3C Controlled Identifier (CID) Specification
• W3C Decentralized Identifiers (DIDs) Specification
• W3C Verifiable Credentials Data Model

#Vidos Documentation

• Understanding DID Documents
• Decentralized Identifiers Overview
• DID Resolution
• DID Methods
• DID URL Dereferencing
• Resolver Service