Skip to content
Vidos Logo Vidos

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?

Section titled “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

Section titled “Core Components”

A Controller Document consists of several key components:

Identifiers

Section titled “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

Section titled “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

Section titled “Verification Relationships”

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

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

Services

Section titled “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

Section titled “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

Section titled “How Controller Documents Function in Vidos”

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

Resolution Process

Section titled “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

Section titled “Integration with Vidos Services”

Controller Documents interact with several core Vidos services:

Resolver Service

Section titled “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

Section titled “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

Section titled “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

Section titled “Authorizer Service”

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

Library Service

Section titled “Library Service”

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

Use Cases for Controller Documents

Section titled “Use Cases for Controller Documents”

Controller Documents enable several key verification scenarios:

Identity Verification

Section titled “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

Section titled “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

Section titled “Secure Communication”

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

Service Discovery

Section titled “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

Section titled “Capability Authorization”

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

Benefits of Controller Documents

Section titled “Benefits of Controller Documents”

Controller Documents provide several advantages for verification systems:

Decentralized Control

Section titled “Decentralized Control”

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

Cryptographic Trust

Section titled “Cryptographic Trust”

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

Interoperability

Section titled “Interoperability”

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

Enhanced Privacy

Section titled “Enhanced Privacy”

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

Future-Proof Security

Section titled “Future-Proof Security”

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

Summary

Section titled “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.

Section titled “Related Resources”

W3C Specifications

Section titled “W3C Specifications”

Vidos Documentation

Section titled “Vidos Documentation”