DID Method Specification: did:git

Introduction

Decentralized Identifiers (DIDs) are a type of identifier that enables verifiable, decentralized digital identities, as defined by the W3C DID Core Specification. The did:git method leverages Git, a distributed version control system, to serve as the source of truth for DID documents. Git's decentralized nature, combined with its robust history tracking and cryptographic signing capabilities, makes it a suitable platform for managing DIDs without relying on a centralized authority.

This specification defines the structure, resolution, and management of did:git identifiers. It addresses the use of cryptographic mechanisms such as Pretty Good Privacy (PGP, implemented as GPG) and Secure Shell (SSH) for signing and verifying commits, ensuring the integrity and authenticity of DID documents stored in a Git repository. The method is designed to be platform-agnostic, applicable to any Git repository, and independent of specific hosting services like GitHub.

DID Syntax

The did:git DID syntax follows the generic DID syntax defined in the W3C DID Core Specification. The ABNF (Augmented Backus-Naur Form) for a did:git identifier is:

      did-git = "did:git:" commit-hash
      commit-hash = 40*40HEXDIG

The commit-hash is a 40-character hexadecimal SHA-1 hash of a Git commit. This hash serves as a content-addressable identifier that ensures the integrity of the DID document and its associated repository state.

Example:

did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2

DID Document Structure

The DID document for a did:git identifier is stored as a JSON or JSON-LD file within a Git repository, typically at a predefined path such as .dids/<did>.json. The document conforms to the W3C DID Core Specification and includes standard properties such as id, verificationMethod, and service.

Example DID document:

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2",
  "verificationMethod": [{
    "id": "did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2#key-1",
    "type": "OpenPgpVerificationKey2019",
    "controller": "did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2",
    "publicKeyPem": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"
  }],
  "service": [{
    "id": "did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2#service-1",
    "type": "GitRepository",
    "serviceEndpoint": "https://example.com/repo.git"
  }]
}

The DID document is committed to the Git repository, and its associated commit hash becomes the DID identifier.

Operations

Create

To create a did:git identifier:

Create a DID document as a JSON or JSON-LD file.
Commit the DID document to a Git repository at a path such as .dids/<did>.json.
Sign the commit using GPG or SSH to ensure authenticity (see Security Considerations).
The resulting commit hash becomes the DID identifier, e.g., did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2.

Resolve

To resolve a did:git identifier:

Access the Git repository containing the DID document (via the serviceEndpoint or a known repository URL).
Retrieve the commit specified by the commit-hash in the DID.
Extract the DID document from the commit, typically from .dids/<did>.json.
Verify the commit signature using GPG or SSH to ensure integrity and authenticity.
Return the DID document to the requester.

Update

To update a did:git identifier:

Modify the DID document in the Git repository.
Commit the changes with a GPG or SSH signature.
The new commit hash becomes the updated DID identifier.
Update any references to the DID to use the new commit hash.

Note: Updating a DID creates a new identifier, as the commit hash changes. Applications must handle this immutability by tracking the latest commit hash.

Deactivate

To deactivate a did:git identifier:

Remove the DID document from the Git repository or mark it as deactivated (e.g., by adding a deactivated property).
Commit the change with a GPG or SSH signature.
The new commit hash reflects the deactivated state.

Security Considerations

The did:git method relies on Git's cryptographic signing mechanisms to ensure the integrity and authenticity of DID documents. The following considerations apply:

GPG Signing

GPG (GNU Privacy Guard) is used to sign Git commits and tags, providing cryptographic assurance of the committer's identity. Key considerations include:

Key Management: GPG keys must be securely generated, stored, and managed. Private keys should be protected with strong passphrases and stored in secure environments (e.g., using hardware security modules like YubiKey).
Key Expiration: GPG keys can be configured to expire, requiring periodic renewal. This enhances security but requires users to update their public keys on platforms or keyservers.
Verification: Resolvers must verify GPG signatures using the committer’s public key, which may be retrieved from a public keyserver or included in the DID document.
Platform Support: GPG has robust support on Linux and macOS but may require additional configuration on Windows (e.g., using Gpg4win).
Limitations: GPG is less user-friendly and has limited adoption on non-Linux platforms, which may hinder its use in some environments.

SSH Signing

Since Git 2.34, SSH keys can be used to sign commits, offering an alternative to GPG. Key considerations include:

Simplicity: SSH keys are easier to generate and manage for users already familiar with SSH authentication. Existing SSH keys can be reused for signing.
Limitations: Unlike GPG, SSH keys do not support expiration or revocation, which may reduce their suitability for long-term identity management. If an SSH key is marked as expired, all commits signed with it may appear unverified.
Verification: Resolvers must verify SSH signatures using the committer’s public SSH key, which may be stored in the DID document or a trusted repository.
Dependencies: SSH signing requires Git 2.34 or later and OpenSSH 8.2p1 or later, which may not be available on older systems (e.g., Ubuntu 18.04).

Trust Model

The did:git method adopts a Trust-Over-First-Use (TOFU) model, similar to SSH, where the first import of a public key is assumed valid. Subsequent changes to the key trigger validation checks. A combined TOFU+PGP trust model, as recommended by the Linux Kernel documentation, is suggested for enhanced security.

[](https://www.kernel.org/doc/html/next/process/maintainer-pgp-guide.html)

Implementers should maintain a local keyring or repository of trusted public keys to verify signatures, as public keyservers may be unreliable.

[](https://www.kernel.org/doc/html/next/process/maintainer-pgp-guide.html)

Repository Access

Access to the Git repository must be secured to prevent unauthorized modifications. SSH is recommended for secure repository access, with keys managed via an SSH agent or hardware-backed solutions like YubiKey.

[](https://developers.yubico.com/PGP/SSH_authentication/Windows.html)

Public repositories must be protected against tampering by requiring signed commits and restricting push access to trusted contributors.

Implementation Details

The did:git method organizes DID documents in a Git repository under a designated directory, such as .dids/. Each DID document is stored as a file named after the DID or a related identifier. The repository may include additional metadata, such as a DID-REGISTRY file listing all DIDs managed in the repository.

Example repository structure:

/repo
  /.dids/
    /did:git:5c3386cf54bba0a33a32da706aa52bc0155503c2.json
    /did:git:ca82a6dff817ec66f44342007202690a93763949.json
  /DID-REGISTRY

The DID-REGISTRY file may contain a JSON array of DIDs and their corresponding commit hashes for easy lookup.

Implementers should ensure that commits modifying DID documents are signed using either GPG or SSH. Verification scripts can be integrated into the resolution process to check signatures automatically.

Introduction

Terminology

DID Method Name