did Class

namespace keychainclass did

Overview

The did class implements W3C Decentralized Identifiers (DIDs), providing a standardized way to identify and authenticate digital entities without relying on centralized authorities.

Class Hierarchy

namespace keychain {
    class did : public serializable {
        // W3C Decentralized Identifier implementation
    };
}

Constructor

did();
did(const std::string& did_string);
did(const std::string& method, const std::string& identifier);
did(const did& other);

Properties

DID Components

std::string get_method() const;
std::string get_identifier() const;
std::string get_method_specific_id() const;

Core components of the DID structure.

DID String Representation

std::string to_string() const;
std::string get_uri() const;  // Same as to_string()

Complete DID string in standard format.

Status and Metadata

did_status get_status() const;
void set_status(did_status status);

bool is_active() const;
bool is_revoked() const;
bool is_expired() const;

DID lifecycle status management.

Timestamps

std::chrono::system_clock::time_point get_created_time() const;
std::chrono::system_clock::time_point get_updated_time() const;
std::chrono::system_clock::time_point get_expires_time() const;

void set_expires_time(const std::chrono::system_clock::time_point& time);

DID lifecycle timestamps.

Methods

DID Document Operations

std::string resolve_document() const;
bool update_document(const std::string& document_json);
std::string get_public_key(const std::string& key_id = "") const;

Interact with the DID document containing public keys and service endpoints.

Verification Methods

std::vector<std::string> get_verification_methods() const;
bool has_verification_method(const std::string& method_id) const;
std::string get_verification_key(const std::string& method_id) const;

Access cryptographic verification methods.

Service Endpoints

std::vector<std::string> get_service_endpoints() const;
std::string get_service_endpoint(const std::string& service_id) const;
bool add_service_endpoint(const std::string& service_id, const std::string& endpoint);

Manage service endpoints associated with the DID.

Validation

bool is_valid() const;
bool validate_format() const;
std::vector<std::string> get_validation_errors() const;

Validate DID format and structure.

Serialization

std::string to_json() const;
std::string to_xml() const;

static did from_string(const std::string& did_string);
static did from_json(const std::string& json);
static did from_xml(const std::string& xml);

Usage Examples

Creating and Using DIDs

#include <keychain/keychain.h>

// Create DID from string
keychain::did alice_did("did:keychain:alice.personal");

// Validate DID format
if (!alice_did.is_valid()) {
    auto errors = alice_did.get_validation_errors();
    for (const auto& error : errors) {
        std::cerr << "DID validation error: " << error << std::endl;
    }
    return;
}

// Get DID components
std::cout << "Method: " << alice_did.get_method() << std::endl;           // "keychain"
std::cout << "Identifier: " << alice_did.get_identifier() << std::endl;   // "alice.personal"
std::cout << "Full DID: " << alice_did.to_string() << std::endl;          // "did:keychain:alice.personal"

// Check status
if (alice_did.is_active()) {
    std::cout << "DID is active and usable" << std::endl;
}

DID Document Resolution

// Resolve DID document
keychain::did identity_did("did:keychain:bob.work");
std::string document_json = identity_did.resolve_document();

// Parse document JSON to extract keys
// (This would typically use a JSON library)
std::cout << "DID Document:" << std::endl << document_json << std::endl;

// Get specific verification method
std::string signing_key = identity_did.get_verification_key("signing-key-1");
if (!signing_key.empty()) {
    std::cout << "Signing key: " << signing_key << std::endl;
}

// List all verification methods
auto methods = identity_did.get_verification_methods();
for (const auto& method : methods) {
    std::cout << "Verification method: " << method << std::endl;
}

Service Endpoint Management

// Add service endpoints
keychain::did service_did("did:keychain:service.api");

service_did.add_service_endpoint("messaging", "https://service.example.com/messaging");
service_did.add_service_endpoint("storage", "https://service.example.com/storage");

// Retrieve service endpoints
auto endpoints = service_did.get_service_endpoints();
for (const auto& endpoint_id : endpoints) {
    std::string url = service_did.get_service_endpoint(endpoint_id);
    std::cout << endpoint_id << ": " << url << std::endl;
}

// Use specific service
std::string messaging_endpoint = service_did.get_service_endpoint("messaging");
if (!messaging_endpoint.empty()) {
    // Connect to messaging service
    std::cout << "Connecting to: " << messaging_endpoint << std::endl;
}

DID Lifecycle Management

// Create new DID with expiration
keychain::did temporary_did("did:keychain:temp.session");
auto expiry = std::chrono::system_clock::now() + std::chrono::hours(24);
temporary_did.set_expires_time(expiry);

// Monitor DID status
void monitor_did_status(keychain::did& did) {
    while (true) {
        auto status = did.get_status();

        switch (status) {
            case keychain::did_status::ACTIVE:
                std::cout << "DID is active" << std::endl;
                break;

            case keychain::did_status::EXPIRED:
                std::cout << "DID has expired!" << std::endl;
                return;

            case keychain::did_status::REVOKED:
                std::cout << "DID has been revoked!" << std::endl;
                return;

            case keychain::did_status::SUSPENDED:
                std::cout << "DID is suspended" << std::endl;
                break;

            default:
                std::cout << "DID status: " << static_cast<int>(status) << std::endl;
                break;
        }

        std::this_thread::sleep_for(std::chrono::minutes(5));
    }
}

DID Comparison and Equality

// Compare DIDs
keychain::did did1("did:keychain:alice.personal");
keychain::did did2("did:keychain:alice.personal");
keychain::did did3("did:keychain:bob.work");

if (did1 == did2) {
    std::cout << "DIDs are identical" << std::endl;
}

if (did1 != did3) {
    std::cout << "DIDs are different" << std::endl;
}

// Use DIDs as map keys
std::map<keychain::did, std::string> did_names;
did_names[did1] = "Alice Personal";
did_names[did3] = "Bob Work";

// Lookup by DID
auto it = did_names.find(did1);
if (it != did_names.end()) {
    std::cout << "Found: " << it->second << std::endl;
}

DID Document Structure

A typical DID document contains:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:keychain:alice.personal",
  "verificationMethod": [{
    "id": "did:keychain:alice.personal#signing-key-1",
    "type": "EcdsaSecp256k1VerificationKey2019",
    "controller": "did:keychain:alice.personal",
    "publicKeyHex": "04a1b2c3d4e5f6..."
  }],
  "authentication": ["did:keychain:alice.personal#signing-key-1"],
  "keyAgreement": ["did:keychain:alice.personal#encryption-key-1"],
  "service": [{
    "id": "did:keychain:alice.personal#messaging",
    "type": "MessagingService",
    "serviceEndpoint": "https://alice.example.com/messaging"
  }],
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z",
  "expires": "2025-01-15T10:00:00Z"
}

DID Format Specification

DIDs follow the format: did:method:method-specific-id

Keychain Method

  • Method Name: keychain

  • Method-Specific ID: {persona_name}.{subname}

  • Example: did:keychain:alice.personal

Validation Rules

  • Method must be "keychain"

  • Method-specific ID must match persona name pattern

  • Total length must not exceed 2048 characters

  • Must follow RFC 3986 URI syntax

Security Considerations

Key Management

  • Public keys in DID documents must be current

  • Revoked keys should be removed from documents

  • Key rotation requires document updates

Privacy

  • DID documents are typically public

  • Avoid including sensitive information

  • Use pairwise DIDs for privacy-sensitive interactions

Availability

  • DID resolution depends on network availability

  • Consider caching mechanisms for offline scenarios

  • Implement fallback resolution methods

See Also

  • gateway - DID operations

  • contact - External identities with DIDs

  • {w3c-did-spec}[W3C DID Specification]

  • {did-method-registry}[DID Method Registry]

  • {keychain-did-method}[Keychain DID Method Specification]