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 retrieve PKI material from the Trust Anchor.
The Retrieve Trust List with DID transaction allows both VHL Sharers and VHL Receivers to retrieve trusted public key material from the Trust Anchor using Decentralized Identifiers (DIDs).
Retrieved material SHALL be used to determine the trustworthiness of VHL artifacts in accordance with the governing trust framework.
Table 2:3.YY2.2-1: Actor Roles
| Actor | Role |
|---|---|
| VHL Receiver, VHL Sharer | Initiate Retrieve Trust List Request |
| Trust Anchor | Retrieve Trust List Response |
x5c header parameter used to carry certificate chainsx5cFigure 2:3.YY2.4-1: Retrieve Trust List with DID Interaction Diagram
A VHL Sharer or VHL Receiver, as a participant in the trust network, SHALL be capable of retrieving public key infrastructure (PKI) material from a designated Trust Anchor.
The retrieved material MAY include:
Participants SHOULD cache the received trust list to reduce network and server load.
Preconditions:
VHL Sharer / VHL Receiver (Requester):
The requesting actor SHALL:
Request Methods:
Implementations SHALL support the did:web method, resolved as defined in the did:web Method Specification, where retrieval of the DID Document is an HTTP GET against the resolved HTTPS URL. Other DID methods MAY be used where all parties to a trust network have agreed to them.
Trust Anchor (Responder):
Upon receiving a Retrieve Trust List Request, the Trust Anchor SHALL:
Upon receipt of Retrieve Trust List Request from a VHL Sharer or VHL Receiver, the Trust Anchor SHALL organize, sign, and expose the PKI material as part of a trusted, canonical trust list.
This MAY include:
The Trust Anchor SHALL only respond with validated and trustworthy material in accordance with the governance policies of the VHL trust framework. This signed trust list enables all participants in the VHL trust network to verify digital signatures and establish secure connections in accordance with the governance policies of the Trust Anchor.
Success Response:
The following response returns a trust list DID Document holding Certificate Authority-issued key material for two participants. Certificate values are truncated for readability.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/jws-2020/v1"
],
"id": "did:web:trust-anchor.example.org:v2:trustlist",
"controller": "did:web:trust-anchor.example.org:v2:trustlist",
"verificationMethod": [
{
"id": "did:web:trust-anchor.example.org:v2:trustlist:DCC:XXA:DSC#XPjhL9Znd1M=",
"type": "JsonWebKey2020",
"controller": "did:web:trust-anchor.example.org:v2:trustlist",
"publicKeyJwk": {
"kty": "EC",
"kid": "XPjhL9Znd1M=",
"x5c": [
"MIICuTCCAmCgAwIBAgIUD9k1Q64Eav5r07DQ4Gff/7h7r6QwCgYIKoZIzj0EAwIwdDELMAkGA1UEBhMCWEEx...",
"MIICMDCCAdWgAwIBAgIUFqWc0xbrcpAettDF8gEymTzDtSkwCgYIKoZIzj0EAwIwdDELMAkGA1UEBhMCWEEx..."
],
"crv": "P-256",
"x": "APdNVtZixJhhqsJS_yx--a_bLQaMMQj48CSb_3adr_MA",
"y": "AOoV8O2w7rov_Txk3wwz_jMoKvx-IgSfYoyygtGetYEd"
}
},
{
"id": "did:web:trust-anchor.example.org:v2:trustlist:DCC:XXB:DSC#9tKmQ2ZbW4E=",
"type": "JsonWebKey2020",
"controller": "did:web:trust-anchor.example.org:v2:trustlist",
"publicKeyJwk": {
"kty": "EC",
"kid": "9tKmQ2ZbW4E=",
"x5c": [
"MIICtzCCAl6gAwIBAgIUYm5rM0hQeVJ2TkZmR2xoT2NrRXdDZ1lJS29aSXpqMEVBd0l3...",
"MIICLjCCAdSgAwIBAgIUS2xwZDNRbEVoTWpZd1JXNXBibVZ5TUI0WERUSTBNRGd3TWpB..."
],
"crv": "P-256",
"x": "AL1rXqTnDwUyVvKcHs3ZmJ4tRfQoNbGxWpYeAiKdM2Uc",
"y": "AJ7hTgVwPzXsRbNmKcYdQfLoEuHiVaWtZpXrBnMjSk9F"
}
}
],
"proof": {
"type": "JsonWebSignature2020",
"created": "2025-01-15T12:00:00Z",
"verificationMethod": "did:web:trust-anchor.example.org:v2:signing#trust-anchor-key-1",
"proofPurpose": "assertionMethod",
"nonce": "a3f8c2d1-9b4e-4f7a-b6e2-1c5d8f3a9e2b",
"jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..example_signature_value"
}
}
Error Responses:
Table 2:3.YY2.4.2.2-1: Retrieve Trust List Error Responses
| HTTP Status | Condition |
|---|---|
| 404 Not Found | Requested DID not found in Trust Anchor registry |
| 401 Unauthorized | Request not authenticated |
| 403 Forbidden | Requester not authorized to retrieve trust material |
Response Elements:
The response SHALL include one or more DID Documents. Their structure, and the key material carried in each verification method, are as defined in ITI-YY1 Message Semantics and are not restated here; the recipient's obligation to validate the certificate chain of each verification method is in Expected Actions.
In addition, each returned DID Document SHALL carry a proof over the document, enabling the recipient to establish that the document was published by the Trust Anchor and has not been altered.
The proof element SHALL contain the sub-elements listed in Table 2:3.YY2.4.2.2-2.
Table 2:3.YY2.4.2.2-2: Trust List proof Sub-elements
| Sub-element | Cardinality | Description |
|---|---|---|
| type | [1..1] | Proof type (e.g., JsonWebSignature2020) |
| created | [1..1] | ISO 8601 datetime the proof was created. Used by the recipient to establish the freshness of the trust list — see Expected Actions |
| verificationMethod | [1..1] | Reference to the key used to create the proof. This is the Trust Anchor's own signing key, identified by a DID distinct from the trust list it signs |
| proofPurpose | [1..1] | Purpose of the proof (e.g., assertionMethod) |
| nonce | [1..1] | A unique value included by the Trust Anchor |
| jws | [1..1] | The detached JSON Web Signature value |
VHL Receiver / VHL Sharer:
A VHL Sharer or VHL Receiver, after receiving PKI material from a Trust Anchor, SHALL validate and process the trust information for subsequent cryptographic operations.
A participant SHALL NOT treat a public key as trusted solely because it appears in a retrieved trust list. The certificate chain accompanying the key SHALL resolve back to a certificate verifiable against one of the public keys pre-shared with the trust network at the time of onboarding, before the key is used. Where the key material is self-generated, that chain is a single self-signed certificate, which is itself the material pre-shared at onboarding.
The participant verifies the cryptographic proof over a retrieved trust list using the Trust Anchor's public key, which is shared with the participant at the time of onboarding.
Upon receiving the Trust List response, the VHL Receiver or VHL Sharer SHALL:
proof over each returned DID Document before any of its content is relied upon. A DID Document whose proof cannot be verified SHALL NOT be used.proof.created against the recipient's freshness policy, and SHALL NOT accept a trust list older than one already held for the same DID. This prevents an older, validly signed trust list being substituted for the current one in order to reinstate withdrawn key material.Validate Certificate Chains: Where a verification method carries x5c, validate the chain to a certificate authority recognized by the governing trust framework, confirm that the public key expressed in the JWK is the key certified by the first certificate in the chain, and confirm that each certificate in the path is within its validity period and not revoked.
A public key SHALL NOT be treated as trusted merely because it appears in a retrieved trust list. Where the trust framework operates a certificate authority, the authority for a key derives from its certificate chain. The rules governing that validation — recognized certificate authorities, path construction, permitted algorithms and key strengths, and how revocation status is obtained — are defined by the governing trust framework and are out of scope for this profile.
authentication, assertionMethod, keyAgreement), or as the governing trust framework otherwise definesTrust list retrieval is subject to the secure channel requirements in Volume 1 Section 1:XX.5.2 Secure Channel Requirements. The Trust Anchor SHOULD authenticate requesting entities before serving trust material.
Clients (VHL Receivers and VHL Sharers) SHOULD check that key types and algorithms are acceptable per their trust framework policy.
Because a did:web DID Document is retrieved over HTTPS, and the identifier carries no inherent binding to the content returned, transport security alone does not establish that a trust list is authentic — whoever controls the host controls the content served. The proof over the document is what establishes authenticity, which is why verifying it before any of the document's content is relied upon is required at 2:3.YY2.4.2.3 Expected Actions.
Where key material is Certificate Authority-issued, clients SHALL validate the x5c chain to a recognized certificate authority before using a key. Extracting a public key from a retrieved DID Document without validating its chain reduces a certificate hierarchy to the assertion that a key was present in a document, discarding the authority the hierarchy exists to convey.
Implementations SHOULD:
The Trust Anchor SHOULD:
Clients SHOULD:
The Trust Anchor's DID retrieval endpoint SHOULD:
Content profiles MAY define additional constraints, such as: