Verifiable Health Links
1.0.0-comment - ballot
Verifiable Health Links, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.0.0-comment built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.VHL/ and changes regularly. See the Directory of published versions
Note on Transaction Optionality: This transaction is REQUIRED (R) for Trust Anchor actors and OPTIONAL (O) for VHL Sharer and VHL Receiver actors. Implementations that do not support this transaction must use alternative mechanisms (out of scope for this profile) to establish trust relationships with the Trust Anchor.
The Submit PKI Material with DID transaction enables entities within a trust network—specifically, VHL Sharers and VHL Receivers—to submit their PKI material to a designated Trust Anchor using Decentralized Identifiers (DIDs). PKI material is carried as a certificate chain: where the participant is enrolled under a Certificate Authority, the issued certificate together with the chain of certificates linking it to the issuing authority; where the participant generates its own key material, a single self-signed certificate. This transaction uses DID Documents conforming to the W3C DID Core specification to package and transmit that material. The Trust Anchor validates, catalogs, and makes this material available for retrieval, enabling participants to verify digital signatures and establish secure communications within the VHL ecosystem.
This transaction is specified as a content interaction rather than as an API: what this transaction constrains is the content of the DID Document. The mechanism by which that content reaches the Trust Anchor — the endpoint, protocol, and message envelope — is determined by the implementing jurisdiction and is out of scope for this profile.
Table 2:3.YY1.2-1: Actor Roles
| Actor | Role |
|---|---|
| VHL Receiver, VHL Sharer | Initiate Submit PKI Material Request |
| Trust Anchor | Respond to Submit PKI Material Request |
x5c header parameter used to carry certificate chainsx5cFigure 2:3.YY1.4-1: Submit PKI Material with DID Interaction Diagram
When a VHL Sharer or VHL Receiver obtains new key material for use within the VHL trust network, they SHALL submit the corresponding public key material to the Trust Anchor for validation and inclusion in the trust list.
Key material is obtained by one of two paths, as determined by the governing trust framework:
The submission MAY include metadata to support categorization of key usage (e.g., digital signatures, encryption, secure channels) and business or operational context.
Prior Onboarding
Initial onboarding — establishing that an organization is entitled to participate at all — precedes this transaction and is distinct from it. Onboarding is governed by the trust framework and is out of scope for this profile; this transaction addresses the operational publication of key material that follows.
Onboarding is nonetheless what anchors both directions of the trust relationship, and it establishes key material each way:
Neither key can be obtained over the channel it secures, so both are established through the verified, out-of-band process the trust framework defines for onboarding.
VHL Sharer / VHL Receiver (Submitter):
The submitting actor:
x5c member of the JWK (see Message Semantics)PKI material SHALL be submitted to the Trust Anchor using DID Documents formatted according to the W3C DID Core specification.
DID Method
Participants SHALL support the did:web method for the DIDs used in this transaction, resolved as defined in the did:web Method Specification. Other DID methods MAY be used where all parties to a trust network have agreed to them.
DID Document Structure
The DID Document SHALL be formatted as a JSON document containing:
The required DID Document elements are listed in Table 2:3.YY1.4.1.2-1.
Table 2:3.YY1.4.1.2-1: Required DID Document Elements
| Element | Cardinality | Description |
|---|---|---|
| @context | [1..*] | JSON-LD context, SHALL include "https://www.w3.org/ns/did/v1". MAY additionally include a context defined by the governing trust framework, where that framework defines additional members |
| id | [1..1] | The DID for the submitting entity (e.g., "did:web:example.org:participant") |
| controller | [0..1] | The DID authorized to make changes to this DID Document. Where present it is typically the same value as id |
| verificationMethod | [1..*] | Array of verification methods containing public key material |
Verification Method Structure:
Each verification method SHALL include the elements listed in Table 2:3.YY1.4.1.2-2.
Table 2:3.YY1.4.1.2-2: Verification Method Elements
| Element | Cardinality | Description |
|---|---|---|
| id | [1..1] | Unique identifier for this verification method, expressed as a DID URL with a fragment (e.g., "did:web:example.org:participant#signing-key-1"). Trust frameworks commonly use the key identifier as the fragment |
| type | [1..1] | Cryptographic suite type (e.g., "JsonWebKey2020") |
| controller | [1..1] | DID that controls this verification method |
| publicKeyJwk | [1..1] | Public key in JWK format (RFC 7517), carrying the certificate chain in x5c (see Carrying the Certificate Chain) |
Carrying the Certificate Chain
Key material SHALL be carried as a certificate chain in the x5c member of the publicKeyJwk, as defined by RFC 7517 Section 4.7 and RFC 7515 Section 4.1.6. The JWK members used are listed in Table 2:3.YY1.4.1.2-3.
This applies to both paths by which key material is obtained. Where the material is issued by a Certificate Authority, x5c carries the issued certificate followed by each issuing certificate. Where the material is self-generated, x5c carries a chain of one: the submitter's self-signed certificate, which is simultaneously the leaf and the terminus of its own chain. A chain of one is not exclusive to self-generated material: a trust list retrieved through ITI-YY2 Retrieve Trust List with DID may likewise carry a certificate authority's own certificate as a single entry.
Table 2:3.YY1.4.1.2-3: Certificate Chain Members of publicKeyJwk
| Element | Cardinality | Description |
|---|---|---|
| publicKeyJwk.kid | [1..1] | Key identifier. Where the trust framework derives the identifier from the certificate (for example, a truncated hash of the DER encoding), that derived value is used |
| publicKeyJwk.x5c | [1..1] | Certificate chain as an array of base64-encoded DER certificates (RFC 5280). The certificate containing the public key SHALL be the first entry, followed by each issuing certificate in order toward the certificate authority. Where the key material is self-generated the array contains a single self-signed certificate |
The public key expressed in the JWK members (for example crv, x, y) SHALL be the same key as that certified by the first certificate in x5c.
The x5c chain is what conveys the authority for a key, as distinct from the key material itself. The chain SHALL resolve back to a certificate that is verifiable against one of the public keys pre-shared with the trust network at the time of onboarding. That pre-shared material is what makes the chain meaningful: without it, a chain establishes only that some certificate authority issued the certificate, not that it is an authority this trust network recognizes.
This profile constrains where the chain terminates. It does not constrain how the chain is validated: path construction, acceptable certificate authorities beyond the onboarded set, permitted algorithms and key strengths, validity periods, and how revocation status is obtained are defined by the governing trust framework.
Example DID Document:
The following example carries Certificate Authority-issued material. It illustrates a did:web identifier, a certificate chain in x5c (the Document Signer Certificate holding the public key, followed by the Signing Certificate Authority that issued it), and a proof over the document. Certificate values are truncated for readability.
{
"@context":[
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/jws-2020/v1"
],
"id":"did:web:some.exampledomain.of.participant.int:customId",
"controller":"did:web:some.exampledomain.of.participant.int:customId",
"verificationMethod":[
{
"id":"did:web:some.exampledomain.of.participant.int:customId#XPjhL9Znd1M=",
"type":"JsonWebKey2020",
"controller":"did:web:some.exampledomain.of.participant.int:customId",
"publicKeyJwk":{
"kty":"EC",
"kid":"XPjhL9Znd1M=",
"x5c":[
"MIICuTCCAmCgAwIBAgIUD9k1Q64Eav5r07DQ4Gff/7h7r6QwCgYIKoZIzj0EAwIwdDELMAkGA1UEBhMCWEExFDASBgNVBAgMC1hYQSBDb3VudHJ5...",
"MIICMDCCAdWgAwIBAgIUFqWc0xbrcpAettDF8gEymTzDtSkwCgYIKoZIzj0EAwIwdDELMAkGA1UEBhMCWEExFDASBgNVBAgMC1hYQSBDb3VudHJ5..."
],
"crv":"P-256",
"x":"APdNVtZixJhhqsJS_yx--a_bLQaMMQj48CSb_3adr_MA",
"y":"AOoV8O2w7rov_Txk3wwz_jMoKvx-IgSfYoyygtGetYEd"
}
}
],
"proof":{
"type":"JsonWebSignature2020",
"created":"2026-07-06T06:00:12Z",
"nonce":"m9t8CCfNotLiE9OCqhxQfYrWq0xwYQhf",
"proofPurpose":"assertionMethod",
"verificationMethod":"did:web:trust-anchor.example.org:v2:signing#trust-anchor-key-1",
"jws":"eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFUzI1NiJ9..MEUCIQDVJHCENivQvdeQJcNFZoucpkrSK_ZlEvwcikhQRR7r8wIgfkaKfg8cYA6CUPbu2lJZEhEVGWpeMcYwDrdPBhPVinM"
}
}
Key Metadata
Submissions SHOULD include sufficient provenance metadata to support validation by the Trust Anchor:
Submission Pathways
The pathway by which the DID Document reaches the Trust Anchor is determined by the implementing jurisdiction, and the submission SHALL be conducted over a secure connection or an equivalently protected pathway.
The following pathways are informative examples of mechanisms in use:
Direct submission over a network connection: The DID Document is transferred to an endpoint designated by the Trust Anchor — for example, an HTTP PUT to a jurisdiction-defined endpoint, or an upload over a mutually authenticated connection with the submission itself signed by the submitting organization.
Indirect Publication: The DID Document is published at a well-known URL under the control of the submitting organization and the Trust Anchor is notified of the location. Where the DID is a did:web DID, that URL is already determined by the DID itself.
Offline Submission: The DID Document is submitted on secure physical media during a verified in-person encounter with formal identity attestation. Trust frameworks commonly use an out-of-band pathway of this kind for initial onboarding, before any network pathway is available to the participant.
Trust Anchor (Receiver):
Upon receipt of public key material from a VHL Sharer or VHL Receiver, the Trust Anchor SHALL validate, organize, sign, and expose the PKI material as part of a trusted, canonical trust list.
Upon receiving a DID Document submission, the Trust Anchor SHALL:
verificationMethod, validate its x5c chain:
The onboarded key material is what makes this check conclusive: a chain that validates only to an arbitrary certificate authority establishes nothing about membership of this trust network. How the path is constructed, which algorithms and key strengths are permitted, and how revocation status is obtained are defined by the governing trust framework. Trust frameworks commonly distribute revocation status as certificate revocation lists (CRLs); some frameworks discourage the use of the Online Certificate Status Protocol (OCSP) because a status request reveals which certificate is being verified, and by whom, at the time of use.
x5c corresponds to the authenticated identity of the submitting participant, so that a participant cannot publish key material on behalf of anotherRejection Criteria
The Trust Anchor SHALL reject submissions that:
x5c, or present a chain whose first certificate does not certify the public key expressed in the JWKLifecycle
The Trust Anchor SHALL support mechanisms for updating or revoking DID Documents once cataloged, so that participants can retrieve current status via ITI-YY2 Retrieve Trust List with DID.
The Trust Anchor sends a Submit PKI Material Response Message upon completing the processing of a Submit PKI Material Request Message. A response SHALL be returned regardless of whether the submission succeeded or failed.
The response message format is determined by the implementing jurisdiction of the Trust Anchor. The Trust Anchor SHALL indicate, by whatever means its submission pathway provides, whether the submission was accepted and — where it was not — the reason for rejection in sufficient detail for the submitter to take corrective action.
The following are informative examples of how that indication is conveyed where the submission pathway is an HTTP request:
Success Response:
Error Response:
Upon receiving the response, the submitting actor (VHL Sharer or VHL Receiver) SHALL:
The secure and verifiable exchange of PKI material via DID Documents is foundational to the operation of a Verifiable Health Link (VHL) trust network. Any compromise in the integrity, authenticity, or provenance of this material undermines the ability of network participants to verify digital signatures, authenticate service endpoints, or enforce trust relationships.
x5c and not from the presence of the key in a DID DocumentJurisdictions MAY define additional security controls, such as specific cryptographic algorithm requirements, certificate chaining policies, offline verification workflows, or restrictions on submission endpoints.