Standardizing a cert to DID verificationMethod mapping

[swcurran]

This is an interesting effort. I'm interested in a slightly different spin on a PKI-DID relationship, but one that has overlap with this spec, so I thought I would ask about.

I'm interested in a publicly specified ("standardized") way to deterministically publish multiple x.509 certs as verificationMethod objects in a single DIDDoc. Notably, my use case is a Domain Owner that wants to publish each of their relevant certs as a verificationMethod in their DIDDoc. "Relevant" is any that are used to generate long-lasting signatures -- signing documents, VCs, code, etc. In our use case, we assume the DID Method being used has DID history as a first class capability (such as with did:webvh). As certs expire they are dropped from the "active" DIDDoc, but can still be accessed historically (for example, using the DID URL "?versionTime=#"). The versionTime parameter gets the DIDDoc that was active at the time, the keyId is the x5t thumbprint to find the right key.

Your spec is doing that mapping already, but in a larger "cert to DIDDoc" context vs. just the verificationMethod. My question is to whether there is interest in collaborating on a common "cert-to-verificationMethod" specification that could be used for any use case where there is a need to express a cert as a verificationMethod within a DIDDoc?

I note that there are differences already in what you are doing and what I'm proposing, so may not work out -- such as the you are using (key-2026) vs. our preference for using the x5t thumbprint.

[chongkan]

@swcurran Thanks so much for taking the time to review the spec, provide feedback, and propose collaboration.

1. Publishing multiple certs in a single DIDDoc — <3 earlier today I was working through how to handle federated brand groups that use multiple domains and SSL certs across their platform. Your framing fits perfectly and is a performance win too.
2. Collaboration on a common cert-to-verificationMethod spec — yes, really interested.
3. #key-2026 vs x5t#S256 — thanks for pointing this out. Agree, and I'll detail the rationale in a follow-up comment below.

I've worked through the impact/effort on our side (small set of changes — spec, tests, reference resolver) and the use case overlap + differences with did:webvh. Posting the full analysis as a follow-up so this thread stays readable.

Note, the below comments are done by Claude after we reviewed the repos etc.

[chongkan]

On point 1 — publishing multiple certs in a single DIDDoc, and the federated-brand situation.

Looking at where each method fits, the use case overlap between did:pki and did:webvh is significant but not total. Both aim at the institutional side of the trust stack, but they reach institutions from different directions.

Use cases for did:pki:

• A national CA's existing certs become resolvable as DIDs with no action from the CA. Anyone holding one of their issued certs can derive the corresponding DID.
• Internal corporate CAs (intermediates under an enterprise root) appear in DID-aware verifier flows without operating any new infrastructure.
• A long-life signature made today verifies later by mapping the cert that signed it back to its derived DID — even if the signing entity has since rotated.
• A verifier matching a presented cert against a trusted-issuer list can do it through DID resolution, without scraping the issuer's website.

The common thread: did:pki bridges existing PKI hierarchies into DID-aware tooling without asking the underlying CAs to do anything new.

Use cases for did:webvh:

• An organization controlling a domain wants a stable DID with key rotation history.
• Long-lived signatures on documents, code, or VCs need to verify even after signing keys have rotated — history lookup via ?versionTime= resolves this.
• A regulated entity needs an audit trail of every change to its identity (key custodian changes, service endpoint updates, controller changes).
• A government agency wants stable identity that survives administrative turnover.

The common thread: did:webvh gives an entity that controls a domain a way to author and evolve a DID Document over time with cryptographic continuity.

Where they overlap — and the federated-brand case:

Consider a regional banking group operating across multiple jurisdictions as a federation of separately-incorporated legal entities — call it Example Bank Group, with country entities Example Bank CR, Example Bank GT, Example Bank SV, etc. Each entity has its own legal name, its own X.509 certs (often from different CAs per jurisdiction), and its own customer-facing domains, but all present a unified brand to consumers.

Without a published DID structure, each verifier ends up curating a private mapping: "this brand name corresponds to these N legal entities, which use these M certs, across these K domains." Curated mappings have well-known drawbacks — stale entries, opacity, and the curator becomes a bottleneck.

With the cert→verificationMethod sub-spec, the brand can publish its own DID document — for example, a did:webvh:example-bank-group — listing each country entity's cert as a verificationMethod with id = #<x5t#S256(cert)>. Each country cert also independently resolves under did:pki. Verifiers receiving a signed credential from any country entity can:

1. Resolve the presented cert's x5t#S256 against either the brand's group DID document or the cert-derived DID — same algorithm, both paths valid
2. Confirm the brand-federation relationship by following alsoKnownAs or service-endpoint cross-references between the group DID and individual country DIDs
3. Skip the curation step entirely — the federation is publicly verifiable from the brand's own publication

Concrete win: brand-federation handling moves from per-verifier curated config into a publishable, standards-compliant artifact controlled by the brand itself. That's the "performance win" mentioned in the warm reply — one verifier code path, no per-brand curation logic.

[chongkan]

On point 2 — collaboration on a common cert-to-verificationMethod spec.

Fully in agreement that this is the right factoring. Before getting into the venue question, one architectural note worth flagging early so we're aligned on framing:

I think did:pki and did:webvh should stay as distinct methods, even with a shared sub-spec. They answer different questions:

• did:pki answers: "Given an X.509 cert that already exists, what's its canonical DID form?" The cert is the source of truth. The DID is computed from it. Nobody authors the DID Document.
• did:webvh answers: "Given a domain I control, how do I publish and evolve a DID Document with audit history?" The domain controller authors the document. The signed history is the source of truth.

These are different setups, even though they share the cert-encoding piece.

The most important practical reason to keep both: did:pki requires zero cooperation from the CA. The whole reason it works as a bridge to existing PKI hierarchies is that the CA doesn't need to know it exists. Anyone holding a cert can derive and resolve the corresponding DID independently. If we folded did:pki into did:webvh, we'd be implicitly asking national CAs to operate /.well-known/ infrastructure, publish every cert they issue in a signed history log, and maintain it forever. Most national CAs and regulated certificate authorities will (correctly) decline — it's outside their mandate.

In HAVID (trustoverip/high-assurance-verifiable-identifiers#16) terms (where one of the open spec questions on read-only vs authored methods becomes useful), did:pki and did:webvh sit on opposite sides of the "is the DIDDoc authored?" axis. Treating them as one method loses that distinction, which verifier rules and threat models care about.

So the clean framing I'd suggest:

• The cert-to-verificationMethod sub-spec is the shared primitive
• did:pki uses it in a deterministic, no-action-required projection
• did:webvh uses it in an authored, history-preserving document
• Future cert-bearing methods can adopt the same primitive on equal footing
• Neither method "hosts" the sub-spec; both cite it as a peer

On the collaboration venue — two options:

1. A section in this repo (cert-to-verificationmethod.md), cited normatively by did:webvh + did:pki, with you as co-editor.
2. A standalone joint spec in a neutral location — happy to defer to your preference on which org/repo would suit best.

Either works. Once we agree on venue, I can put up a 100-150-line skeleton within a week — scope, the cert-to-keyId algorithm using x5t#S256, worked examples for did:pki and did:webvh, and a section explicitly noting the sub-spec is method-agnostic so any future cert-bearing method can adopt it.

If useful, I'd suggest inviting folks working on adjacent pieces once we have a skeleton draft — particularly anyone working on HAVID @tweeddalex validation states for cert-bearing methods, and Universal Resolver driver coverage. Their early review would catch any architectural issues before we get too far.

One open question worth flagging: if we go with option 2 (standalone), I'd lean toward independent semver for the sub-spec, with citing methods pinning a version. No strong prior

— happy to discuss whichever way feels right to you.

[chongkan]

On point 3 — #key-2026 vs x5t#S256, with detail.

Adopting x5t#S256 (RFC 7515 §4.1.8 — SHA-256 cert thumbprint) as the canonical verificationMethod identifier is strictly better than the current #key-N naming, for four reasons:

• The keyId comes from the cert itself, not from a naming choice we make. Anyone holding the cert can compute the same keyId — no need to consult the spec or the DIDDoc to know what to expect.
• A verifier with a presented cert can compute the keyId directly and look up that exact verificationMethod in one step — no scanning, no name-matching.
• It matches what JWS/JWK libraries already do, so cert-bearing DIDs slot into existing toolchains without custom handling.
• For DIDDocs with multiple certs (an entity issuing code-signing, document-signing, and TLS certs from the same root), each cert gets a unique, predictable keyId without us inventing names.

I'd also recommend emitting x5t#S256 as a property on the VM object so consumers don't have to recompute it.

Concrete change in the DIDDoc:

// Before
{
  "id": "did:pki:abc…xyz#key-1",
  "type": "X509Certificate2020",
  "publicKeyJwk": { "...": "..." }
}

// After
{
  "id": "did:pki:abc…xyz#FfwAi9wKVeMRT0XK3Q0PFsR_kbbqI4skbBbHBzlRfp4",
  "type": "X509Certificate2020",
  "x5t#S256": "FfwAi9wKVeMRT0XK3Q0PFsR_kbbqI4skbBbHBzlRfp4",
  "publicKeyJwk": { "...": "..." }
}

The DID itself doesn't change (still derived from the cert's SubjectPublicKeyInfo). Only the fragment moves. Migration cost for existing implementers is essentially zero since did:pki isn't broadly deployed yet — a clean cut works for this version.

On SHA-256 specifically: I'd recommend x5t#S256 (SHA-256) and excluding plain x5t (SHA-1) from the new spec. No reason to inherit SHA-1's deprecation pain into a 2026-era spec — and x5t#S256 is defined alongside x5t in the same RFC, so the convention/family alignment is preserved without the cryptographic baggage.

Net effect for verifier authors:

// Compute keyId from the cert directly, no spec-specific lookup logic
const expectedKid = "#" + base64url(sha256(presentedCertDER));
const vm = didDoc.verificationMethod.find(v => v.id.endsWith(expectedKid));
verify(payload, signature, vm.publicKeyJwk);

Same four lines work across did:pki, did:webvh, and any future cert-bearing method that cites the shared sub-spec.

[chongkan]

Quick clarifying note — re-reading my own comments above, I want to scope the conversation more cleanly, since I conflated two distinct cert worlds in places (the federated-brand example uses "customer-facing domains" framing that implies TLS-cert territory).

did:pki's primary target: digital signature / electronic identity certs — QTSP-issued (eIDAS), national CA-issued (Firma Digital and equivalents), professional and legal-entity signing certs. The "regulated cert already carries an entity identity; just needs to be DID-resolvable" use case. The spec is X.509-type agnostic, but the institutional bridge problem is most acute on the signing-cert side, where the cert is the source of truth for entity identity and we're just making it resolvable.

TLS / web server cert side: we have separate work there (institutional registry derived from EV/OV cert SAN entries, used for anti-phishing / origin verification on a browser extension). Architecturally adjacent to did:pki, but a different pipeline with different verifier rules — not the same problem.

The federated-brand example lands cleaner if read as a signing-cert federation (Example Bank Group's country entities each hold legally-distinct signing certs, all published under one group DID for verifier discovery). The same cert→verificationMethod encoding works for TLS certs too, but the institutional bridge story I had in mind is the signing one.

Doesn't change the cert→verificationMethod sub-spec discussion (the encoding is type-agnostic) — but flagging in case it shaped how you read the use case sections.

[chongkan]

@swcurran

I am currently working on a "product/solution" that was leveraging did:web for validating IDs on websites. I wasn't aware of what the benefits of did:webvh posed on top of did:web. Specifically, the grouped domains as part of a single Entity Web Surface.

I am/will be integrating did:webvh in our software, and will be in touch by email soon to show you how we do so and a demo.

[swcurran]

Sorry for the slow response to your previous notes.

On the branding question. Have you looked that the /whois part of did:webvh? It might be very valuable in the branding you are doing. <tl;dr> /whois is intended to be a DID independent resource that when dereferenced returns a verifiable presentation containing verifiable credentials about the DID and it's "alsoKnownAs" identifiers. That would be a good mechanism for allowing each sub-entity having its own DID, and the top-level entity from issuing a credential that conveys that they are part of the same organization. The value of the VP is that VC from the parent can be combined with other VCs from other entities -- GLEIF, a jurisdictional registry of legal entities, certifications held, etc. A verifier resolving a DID can recursively resolve the DIDs and /whois bundles of the issuers of VCs about that DID, until they recognize an authority in the hierarchy they trust. BTW -- we are also thinking about <did>/whois-vh -- where not only can you get the authorizations of a legal entity, but you can get them historically -- at the time the signature was generated. Happy to talk more about /whois and /whois-vh. They are being discussed in the VCWG Recognized Entities working group.

On the collaboration -- definitely not purposing merging the two Methods. What I would like to see is a common way to express a PKI cert as a DID verificationMethod. I would suggest that we do that work via a spec in the did-extensions registry -- perhaps as a side effort of the DID Resolution Working Group. I think we are close with what we have and just have to iron out the differences -- and your expertise in PKI would certainly help a lot -- such as your point 3 and the best way to represent the hash.

Happy to help with any did:webvh questions you have and connect you with the larger community. As I hope you know -- there are now 6 implementations available, all tested for interop. We're also starting to talk about the "next version" and what features to use. Most likely -- adding a PQC algorithm, making pre-rotation required and perhaps -- making the web component optional to open up some non-legal entity use cases such as did:plc like.

[chongkan]

@swcurran I need to finish bringing some few things to a stable point and will be contacting you to work on this hopefully in the next 2 weeks.

I am currently reviewing and testing the last changes we discussed btw. Will also have specific questions on webvh.

Will be in touch soon.