Skip to main content
Version: Stage 5 - Deliverable Acceptance Check

GRID Pilot Cryptographic Key Use Pattern

1. Executive Overview: The Two Trust Planes​

In the UN/CEFACT Global Registry Information Directory (GRID), cryptographic keys serve two distinct functions:

  1. The Operational Plane (Git Repository History): Proves who edited and pushed the Registrar's configuration and metadata files.

  2. The Attestation Plane (Verifiable Identity & Credentials): Proves what legal registry assertions are made by the Registrar and the GRID Board using W3C Verifiable Credentials 2.0 and did:webvh (DID Web Verifiable History).


2. The Cast of Keys: Roles, Ownership, and Custody​

A fully functional GRID Sovereign Node interacts with five distinct cryptographic keys across the ecosystem:

#Key NameCustodian / OwnerAlgorithmPrimary PurposeWhere the Public Key is PublishedVerifier
1Git Commit Signing KeyRegister Operator (DevOps / Tech Lead)Ed25519 (SSH) or RSA/Ed25519 (GPG)Proves git commits containing registrars/*.json are authentic.GRID Harvester configuration (allowed_signers or GPG keyring)GRID Harvester during harvest run
2DID Authorization KeyAuthoritative Registrar (Security Officer)Ed25519 (Multikey)Governs state transitions, updates, and key rotations in did.jsonl.Declared in updateKeys parameter in did.jsonl Entry 0did:webvh Resolvers and GRID Harvester
3Registrar DIA Assertion KeyAuthoritative Registrar (Legal / Issuing Service)Ed25519 (Multikey)Digitally signs Tier 2 Entity DIAs (e.g., Company credentials).Declared under assertionMethod in the Registrar's DID DocumentRelying Parties (Banks, Customs, Border Agencies)
4GRID Manifest Signing KeyGRID Hub / UNICC OperationsEd25519Signs directory release manifests (release_manifest.json) for offline verification.GRID Hub Genesis record and public documentationRelying Parties verifying cached directory downloads
5GRID DIA Issuance KeyGRID Board / UNICC OperationsEd25519 (Multikey)Signs Tier 1 Registrar Recognition DIAs issued to compliant nodes.Published in GRID Hub's own DID DocumentRelying Parties verifying if a Registrar is GRID-recognized

3. End-to-End Cryptographic Lifecycle​

Phase 1: Authoring & Pushing Metadata (Participant Sovereign Boundary)​

When a jurisdiction publishes or updates registrar metadata:

  1. File Modification: The Register Operator creates or edits registrars/companies.json.

  2. Commit Signing: The operator commits changes locally using their private Git signing key. For example:

    git commit -S -m "feat(companies): update contact endpoint"

    This command causes Git to calculate the SHA-256 hash of the commit tree and encrypt it with the operator's private key, creating an immutable cryptographic signature in Git history.

  3. Push to Remote: The operator executes git push origin main targeting only their own repository (gitlab.com/group/repo). Participants never push directly to the GRID.

The sequence diagram below shows an example of a typical update for a GRID participant.


Phase 2: Establishing Verifiable Identity (did:webvh)​

Note: did:webvh replaces the reliance on DNS trust used by did:web with mathematical history chaining.

  1. Genesis Preimage (Entry 0): The participant's build script canonicalizes an initial DID document and parameter block using RFC 8785 (JCS).

  2. Self-Certifying Identifier (SCID) Derivation:

    SCID=MultihashSHA-256(JCS(Entry0))

    The resulting multihash (e.g., QmOriginSCID...) becomes the permanent root anchor of the DID:
    did:webvh:QmOriginSCID...:gtr-pilots.gitlab.io:genovia.

  3. Forward Pre-Rotation (nextKeyHashes):
    To protect against future key compromise, Entry 0 does not just declare the active key; it publishes a SHA-256 commitment of the next authorization key:

    {
    "versionId": "1",
    "scid": "QmOriginSCID...",
    "updateKeys": ["did:key:z6MknActiveAuthorizer..."],
    "nextKeyHashes": ["z6MkuPreRotatedCommitmentHash..."]
    }

    This means that, even if the active signing key is stolen, the attacker cannot pivot the DID document without the private key matching the pre-committed hash.


Phase 3: The GRID Harvest (Ingestion & Source Authentication)​

In the pilot instance, the GRID Harvester executes on UNICC infrastructure on an automated schedule. It pulls participant data and conducts local verification as shown in the diagram below.

  1. Verifying Git Provenance: The Harvester extracts the signature from the latest Git commit and checks it against its onboarding whitelist (allowed_signers or GPG keyring). If an unauthorized committer touched companies.json, ingestion halts.

  2. Verifying DID Continuity: The Harvester resolves /.well-known/did.jsonl, recalculates the genesis SCID from Entry 0, and iterates through all log entries to verify that each state transition is signed by an authorized updateKey.

  3. Accepted State: If both checks pass, companies.json is ingested into the GRID directory dataset.


Phase 4: Directory Publication & Manifest Chaining (GRID Boundary)​

Once metadata across all participating sovereign nodes is aggregated, the GRID Generator creates directory artifacts and binds them cryptographically:

  1. Aggregation: The directory dataset (CSV/JSON) is compiled.

  2. Snapshot Manifest: A manifest file (release_manifest.json) is generated containing:

    • The SHA-256 hash of the generated directory file.

    • previous_manifest_hash: The SHA-256 hash of the prior release manifest, forming an immutable append-only ledger across release cycles.

    • A validity window (validFrom / validUntil).

  3. GRID Manifest Signature: The GRID Hub signs the manifest using the GRID Manifest Private Key.

  4. Registrar Recognition DIA (Optional): If the Registrar controls an authenticated DID, the GRID Hub issues a Tier 1 Registrar Recognition DIA (a W3C VC 2.0 attesting that the Registrar is recognised by the GRID Board), signed with the GRID DIA Issuance Key.


Phase 5: Relying Party Verification (Verification at the Edge)​

A Relying Party (e.g., a commercial bank or customs officer in Australia) verifies transactions without querying the GRID in real time:


4. Architectural Analysis: Why Separate the Keys?​

A common question is: “Why can't the Register Operator use their GPG commit key to sign DIAs, or use the DID key to sign Git commits?”

Conflating these keys creates operational and cryptographic hazards:

The following principles are observed by the design.

1. Principle of Least Privilege and Segregation of Duties​

  • An IT administrator managing GitLab CI pipelines has the authority to update server endpoints, but must not have statutory authority to legally certify a corporate entity.

  • Placing the legal DIA signing key inside a Git repository or CI/CD runner allows a compromise of the developer environment to forge legal company registrations across the entire jurisdiction.

2. Differing Custody and Hardware Boundaries​

  • Git Signing Keys: Managed in developer SSH/GPG agents, developer smart cards (e.g., YubiKey), or temporary runner tokens.

  • DIA Issuance Keys: High-value statutory assets. In production, these reside inside an HSM (Hardware Security Module) or isolated KMS with strict multi-party access control (m-of-n approval).

3. Decoupling Lifecycles and Rotation​

  • Operational Staff Turnover: When a DevOps engineer leaves the Register Operator, their Git commit key must be revoked from allowed_signers. If the Git key were the DID key, employee departure would trigger an invalidation of the entire jurisdiction's DID Document and cast doubt on all previously issued DIAs.

  • Cryptographic Pre-Rotation: did:webvh provides pre-rotation (nextKeyHashes) to recover from compromised signing keys. This protocol belongs strictly to the identity layer and cannot be tied to Git commit histories.


5. Summary Reference Guide for Implementers​

5.1 Step-by-Step Implementation Checklist​

When establishing your Sovereign Node:

  1. For Git Commits (Operational Provenance): Generate a dedicated Ed25519 SSH or GPG key pair. Provide the public key to the GRID Harvester team during Gate G2 onboarding. Configure Git locally:

    git config user.signingkey ~/.ssh/id_ed25519.pub
    git config gpg.format ssh
    git config commit.gpgsign true
  2. For did:webvh (Verifiable Identity): Keep the authorization (updateKeys) and DIA assertion keys independent. Run the reference generator (scripts/generate-webvh.mjs) to canonicalize Entry 0, derive the SCID, forward-commit via nextKeyHashes, and write public/.well-known/did.jsonl.

  3. For DIA Issuance (Tier 2 Credentials): The private key corresponding to #dia-key-1 (declared under assertionMethod) must be held in an isolated environment (such as an HSM, vault, or encrypted local keystore). It is invoked strictly by the registry issuance software to sign W3C VC 2.0 / UNTP payloads. It must never be checked into Git or stored in CI/CD variables.

  4. For Static Web Publication (Gate G4): Deploy strictly via static Pages hosting (https://{group}.gitlab.io/{project}), ensuring public/_headers serves:

    /*
    Access-Control-Allow-Origin: *
    /.well-known/did.jsonl
    Content-Type: application/jsonl; charset=utf-8
    Access-Control-Allow-Origin: *

5.2 Key Rotation and Pre-Rotation Execution​

When rotating the active DIA assertion key or updating the DID state:

  1. Reveal Pre-Committed Key: Retrieve the private key corresponding to the multihash committed in nextKeyHashes of the preceding entry.

  2. Generate Forward Commitment: Generate the next candidate key pair (N+2) and compute its SHA-256 multihash.

  3. Emit Successor Log Line: Append Entry N+1 to .well-known/did.jsonl, signing the transition line with Key N+1.

  4. Historical Continuity: Because Entry N+1 proves knowledge of the secret pre-committed in Entry N, resolvers accept the transition as authorized without out-of-band coordination.

5.3 Incident Response: Key Compromise Playbook​

Compromised KeyImmediate ImpactContainment & Remediation Procedure
Git Commit KeyAttacker can sign malicious repository commits to registrars/*.json.1. Notify GRID Operations immediately.
2. Harvester operator revokes key fingerprint from allowed_signers.
3. Generate replacement SSH/GPG key pair.
4. Rebase and sign clean Git history.
Active DIA Assertion KeyAttacker can forge Tier 2 Entity DIAs (corporate credentials).1. Execute an emergency state transition in did.jsonl.
2. Activate the pre-rotated key via nextKeyHashes.
3. Remove the compromised key from assertionMethod.
4. Issue revocation/suspension credentials for affected DIAs.
DID Authorization KeyAttacker attempts to hijack the DID document.1. Attacker is blocked unless they also possess the pre-committed secret in nextKeyHashes.
2. Legitimate custodian immediately publishes the pre-rotated entry using the true pre-commitment private key.
3. If all pre-rotated keys are compromised, declare the DID revoked and coordinate out-of-band reissue with the GRID Board.

5.4 Diagnostic Verification Commands​

Before requesting Gate G5 (GRID Connected), verify all key aspects locally:

# 1. Verify Git commit signature locally
git log -1 --show-signature

# 2. Verify HTTP endpoint, MIME type, and CORS headers
curl -s -I https://{group}.gitlab.io/{project}/.well-known/did.jsonl | grep -Ei "(HTTP/|content-type|access-control)"

# 3. Verify SCID derivation and log continuity
node scripts/verify-webvh.mjs

# 4. Verify registrar metadata references the correct did:webvh identifier
curl -s https://{group}.gitlab.io/{project}/registrars/companies.json | grep "did:webvh"