Verifiable Health Links
1.0.0-comment - ballot International flag

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

Artifacts Summary

This page provides a list of the FHIR artifacts defined as part of this implementation guide.

Requirements: Actor Definitions

The following artifacts define the types of individuals and/or systems that will interact as part of the use cases covered by this implementation guide.

Trust Anchor

An authorized organization in the trust framework that manages and distributes PKI material—such as public key certificates and revocation lists—to participants in the network.

VHL Holder

An individual—typically the patient or their delegate—who possesses a Verifiable Health Link (VHL) and presents it to a VHL Receiver.

VHL Receiver

A system or organization that receives a VHL from a VHL Holder and uses it to retrieve health documents from a VHL Sharer, after verifying the authenticity and integrity of the VHL.

VHL Sharer

A system that generates VHLs, provides them to a VHL Holder, and responds to requests from a VHL Receiver to retrieve document manifests authorized by the VHL.

Requirements: Formal Requirements

The following artifacts describe the specific requirements to be met by systems compliant with the implementation guide.

Audit Event - Accessed Health Data

Purpose:
Ensure that the VHL Sharer records audit events when health documents are accessed or retrieved using a Verifiable Health Link (VHL).

Description:
The VHL Sharer MAY record audit events for critical events involving document access. These MAY include:

  • A request from a VHL Holder to generate a VHL
  • A request from a VHL Receiver to retrieve one or more health documents using a valid VHL
  • Any access to protected health content triggered by the use of a VHL
Audit Event - Received Health Data

Purpose:
Ensure that the VHL Receiver generates audit records when receiving and using a Verifiable Health Link (VHL) to retrieve health information, in support of accountability and traceability.

Description:
The VHL Receiver MAY record audit events for critical events during its handling of a VHL. These MAY include:

  • Receipt of a VHL from a VHL Holder
  • Verification of the VHL's digital signature and trust chain
  • Use of the VHL to retrieve referenced health documents from a VHL Sharer
  • Access, rendering, or internal processing of the retrieved documents
Create Secure Channel

The VHL Sharer and VHL Receiver SHALL jointly establish a secure connection prior to executing any Verifiable Health Link (VHL) transactions involving the exchange of sensitive data.

This requirement is satisfied by implementing secure channel establishment as defined in the Audit Trail and Node Authentication (ATNA) Profile, specifically through the Authenticate Node [ITI-19] transaction.

This requirement entails:

  • The VHL Receiver initiating a secure connection as the client and presenting valid credentials
  • The VHL Sharer responding as the server, presenting its own credentials and validating the client's credentials against a trusted Certificate Authority or Trust Anchor

Establishing this secure channel ensures confidentiality, integrity, and bilateral authentication of all subsequent communications, and fulfills the trust obligations defined in the Establish Trust requirement.

Establish Trust

Before participating in any Verifiable Health Link (VHL) transactions, the VHL Sharer and VHL Receiver SHALL establish a trust relationship based on shared acceptance of a designated Trust Anchor.

Trust is established by referencing and accepting public key material published and distributed in accordance with this specification ( via Retrieve Trust List Response).

All participants SHALL validate digital signatures using keys that are anchored in the agreed trust framework.

Generate a VHL Authorization Mechanism Based on Query Parameters

The VHL Sharer SHALL generate a Verifiable Health Link (VHL) to be issued to a VHL Holder.

The Sharer SHALL conduct all necessary tasks to prepare the content referenced by the VHL. These tasks MAY be further defined by applicable content profiles or implementation guides, and MAY include:

  • Generation of new documents in real time;
  • Querying for existing documents (e.g., IPS, CDA, FHIR Bundles) associated with the VHL Holder; or
  • Creation of digital signatures on one or more documents.

Once content preparation is complete, the Sharer SHALL construct the VHL payload and sign it to produce a cryptographically verifiable authorization mechanism.

Optional behaviors:

Initiate Retrieve Trust List Request

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:

  • Public key certificates and associated trust lists
  • Certificate revocation data (e.g., CRLs, OCSP responses)
  • Metadata used to:
    • Validate digital signatures on VHLs and related resources
    • Establish secure connections
    • Decrypt content protected via asymmetric encryption

Participants SHOULD cache the received trust list to reduce network and server load.

Preconditions:

  • The Trust Anchor SHALL have made available at least one endpoint (such as an mCSD-compliant endpoint) that is accessible to all participants in the trust network.
  • The requesting participant knows in advance the endpoint from which to retrieve PKI material, as published or distributed by the Trust Anchor.
  • The requesting participant holds the Trust Anchor's public key, shared with the participant at the time of onboarding, with which to verify the cryptographic proof over the retrieved trust list.
  • The Trust Anchor MAY additionally provide individual endpoints per participant, in addition to the common endpoint.
Initiate Submit PKI Material Request

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:

  • Self-generated or
  • Certificate Authority (CA) issued

The submission MAY include metadata to support categorization of key usage (e.g., digital signatures, encryption, secure channels) and business or operational context.

Provide VHL

The Provide VHL transaction enables a VHL Holder to transmit a Verifiable Health Link (VHL) to a VHL Receiver. The VHL serves as a signed authorization mechanism that allows the Receiver to subsequently retrieve one or more health documents from a VHL Sharer.

Depending on the use case, the VHL MAY be rendered or transmitted using formats such as QR code or deep link (HTTPS URL).

Receive Trust List

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.

Receive VHL authorization mechanism

The VHL Receiver SHALL be capable of receiving a Verifiable Health Link (VHL) from a VHL Holder through a supported transport mechanism (e.g., QR code scan, direct URL, or digital message).

Upon receipt, the Receiver SHALL:

  • Parse the VHL
  • Validate its digital signature against a trusted key published by a recognized Trust Anchor
  • Prepare to retrieve the associated health documents

Receipt of the VHL may occur through direct user interaction (e.g., scanning a QR code) or automated channels, depending on the implementation context.

Record Access to Health Data

The VHL Sharer MAY record audit events when health data is accessed through a Verifiable Health Link (VHL). These events support accountability, traceability, and compliance with applicable security and privacy regulations.

Audit records MAY include the following metadata:

  • Timestamp of the access event
  • Identity of the accessing actor (e.g., person or system)
  • Type and identifier of the accessed resource (e.g., DocumentReference)
  • Purpose of access, where available (e.g., treatment, consent verification)
  • Outcome of the event (e.g., success, failure)

Audit events SHALL be represented using the FHIR AuditEvent resource, and SHOULD conform to applicable IHE profiles such as ATNA where appropriate. Implementers MAY define additional audit logging behavior to meet jurisdictional or organizational policies.

Record Consent

The VHL Sharer SHALL record the consent granted by a VHL Holder to authorize the sharing of their health data via a Verifiable Health Link (VHL). This consent confirms that the Holder agrees to the creation of a VHL and its use by authorized VHL Receivers to access specific health documents.

In this requirement, the VHL Sharer acts as a Consent Recorder, as defined in the Privacy Consent on FHIR (PCF) profile. Specifically, the Sharer SHALL initiate the Access Consent - ITI-108 transaction to formally capture the Holder's consent.

The ITI-108 transaction SHOULD be invoked as part of the actions triggered by a Generate VHL request, particularly when legal, jurisdictional, or organizational policy requires explicit, recorded consent prior to enabling document sharing.

This requirement enables lawful, transparent sharing of personal health information across organizations and trust domains.

Request VHL Document

Having obtained a manifest through Retrieve Manifest [ITI-YY5], the VHL Receiver SHALL retrieve each health document it needs from the location that manifest gives for it, using MHD ITI-68 Retrieve Document.

Document binaries are encrypted. The Receiver decrypts each one using the symmetric key carried in the key field of the VHL payload.

Optional behaviors:

  • The VHL Receiver MAY verify the digital signature of the returned health document to confirm its authenticity, integrity, and provenance, as defined in the Verify Document Signature requirement.
  • The VHL Sharer MAY record an audit event documenting the access request by the Receiver, in accordance with the Audit Event – Received Health Data requirement.
Request VHL Documents

The VHL Receiver SHALL initiate a request to retrieve a set of health documents from a VHL Sharer, using a previously received and validated Verifiable Health Link (VHL).

The Receiver SHALL have verified the VHL signature against PKI material published by the Trust Anchor before making the request. Validation in the other direction — the Sharer establishing the Receiver's participation in the trust network — applies where one of the Sign Manifest Request Options is in use, and is optional.

Optional behaviors:

Request that a VHL authorization mechanism be issued

A VHL Holder initiates a request to a VHL Sharer to generate a Verifiable Health Link (VHL) that references one or more health documents. The resulting VHL allows the Holder to subsequently share access to those documents with a VHL Receiver. The Holder MAY include optional parameters to constrain or protect the issued VHL-such as defining an expiration period, scoping which documents are included, or requiring a passcode for retrieval. These parameters guide the Sharer's issuance of the VHL and influence the conditions under which the associated documents may be accessed.

Preconditions:

  • The VHL Holder SHALL trust that the VHL Sharer has been authorized by its jurisdiction to generate VHLs and to provide access to the corresponding health documents.
  • Optionally, the VHL Holder has selected consent directives or selective disclosure preferences, as permitted by the applicable content profile.
Respond to Request VHL Documents

The VHL Sharer SHALL respond to a manifest request from a VHL Receiver that presents a previously issued Verifiable Health Link (VHL), returning only those documents the VHL authorizes.

Before any manifest content is released, the Sharer SHALL establish that the VHL presented is valid and authorizes what is being requested.

Authentication of the requesting Receiver is a separate and optional control, provided by the three Sign Manifest Request Options. Where the Sharer claims one of them it authenticates the Receiver against the trust network using PKI material published by the Trust Anchor before releasing any manifest content. Where it does not, release of the manifest follows from a valid VHL and, where the P flag is set, the correct passcode.

Optional behaviors:

  • The VHL Sharer MAY record an audit event documenting the access, in accordance with the Audit Event – Accessed Health Data requirement.
  • The VHL Sharer MAY apply rate limiting per Receiver or per folder ID, and log failed authentication and authorization attempts.
Respond to Submit PKI Material Request

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.

Retrieve Trust List Response

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:

  • Public key certificates, trust chains, or JWKS structures
  • Revocation data (CRL or OCSP)
  • Usage metadata (e.g., key type, scope, intended usage)

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.

Verify Document Signature

The VHL Receiver, upon receiving a digitally signed health document from a VHL Sharer, MAY verify the document's digital signature using previously retrieved PKI material.

This verification process confirms the authenticity, integrity, and provenance of the document independently of the Verifiable Health Link (VHL) itself.

The public key used for this verification MAY:

  • Originate from a different trust network than the one used to validate the VHL
  • Be unrelated to the key used to validate the VHL signature

Implementers SHOULD consult cross-profile guidance regarding interoperability with the IHE Document Digital Signature (DSG) profile, particularly in cases where additional attestation, long-term non-repudiation, or multi-party signatures are involved.

Behavior: Capability Statements

The following artifacts define the specific capabilities that different types of systems are expected to have in order to comply with this implementation guide. Systems conforming to this implementation guide are expected to declare conformance to one or more of the following capability statements.

Trust Anchor

CapabilityStatement for Trust Anchor Actor in the IHE IT Infrastructure Technical Framework Supplement IHE VHL. An authorized organization in the trust framework that manages and distributes PKI material—such as public key certificates and revocation lists—to participants in the network. It ensures that this material is trustworthy and available, enabling VHL Sharers and VHL Receivers to verify digital signatures and authenticate the origin of shared data.

VHL Receiver Client Capability Statement

Capability Statement for a VHL Receiver implementing the Retrieve Manifest [ITI-YY5] transaction as a client. This client searches for List resources using VHL-authorized manifest URLs and can request inclusion of DocumentReference resources via the _include parameter.

VHL Sharer Server Capability Statement

Capability Statement for a VHL Sharer implementing the Retrieve Manifest [ITI-YY5] transaction as a server. This server supports FHIR search on List resources with _include parameter to retrieve document manifests authorized by Verified Health Links.

Behavior: Operation Definitions

These are custom operations that can be supported by and/or invoked by systems conforming to this implementation guide.

Generate VHL

This operation generates a Verifiable Health Link (VHL) for transmission or display. The VHL MAY be returned as a QR code (HCERT/CWT) or, when the VHL Sharer supports the VC Envelope Option, as a signed W3C Verifiable Credential.

Input Parameters:

  • sourceIdentifier: Patient identifier (required)
  • exp: Expiration time in Epoch seconds (optional)
  • flag: Single-character flags in alphabetical order - L (long-term use), P (Passcode required) (optional)
  • label: Short description up to 80 characters (optional)
  • passcode: User-supplied passcode for passcode-protected VHLs (optional)
  • purposeOfUse: Purpose(s) of use the VHL Holder is authorizing for this share, bound to the HL7 v3 PurposeOfUse value set (optional). Populates Consent.provision.purpose when an IHE PCF Consent is bound to the generated folder.
  • format: Requested output carrier - 'qrcode' (default) or 'vc'. 'vc' requires the VHL Sharer to support the VC Envelope Option.

Output Generation:

  • When format=qrcode: Returns a Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.
  • When format=vc: Returns a Binary resource (media type application/vc) containing a JSON-LD Verifiable Credential whose credentialSubject.id carries the VHL, signed with the VHL Sharer's trust-network key using W3C Data Integrity (DataIntegrityProof).
  • Exactly one of qrcode or verifiableCredential SHALL be populated.

Structures: Logical Models

These define data models that represent the domain covered by this implementation guide in more business-friendly terms than the underlying FHIR resources.

VHL Payload

The payload carried by a Verifiable Health Link.

This model specializes the SMART Health Link Payload.

Two things distinguish this model from its parent: the U flag is not used, and extension.fhirBaseUrl is defined for the Sign Manifest Request Option (OAuth with SSRAA). See Generate VHL [ITI-YY3] for the construction steps.

Carriers. This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:

  • HCERT/CWT QR code — the payload is a CBOR map with text keys at HCERT claim key 5, with values in their CBOR-native types, so exp and v are integers. The map is the payload; it is neither base64url-encoded nor prefixed. Claim key 5 identifies the content as a VHL, so no type discriminator is carried in the payload. A vhlink:/ string at claim key 5, as earlier drafts specified, SHOULD still be accepted on decode.
  • VC Enveloped VHL Option — the payload is minified, base64url-encoded and prefixed with vhlink:/ to form the credentialSubject.id URI, because a JSON-LD id cannot be a map.

The WHO SMART Trust HCERT specification types claim key 5 against this model; see WorldHealthOrganization/smart-trust#130.

Structures: Extension Definitions

These define constraints on FHIR data types for systems conforming to this implementation guide.

Remaining Passcode Attempts

The number of incorrect passcode attempts remaining before the VHL is disabled.

The SMART Health Links manifest request requires the error response for an invalid passcode to carry remainingAttempts. A VHL manifest request returns an OperationOutcome rather than the plain JSON body SHL defines, so the count is carried in this extension to keep it machine-readable for the VHL Receiver.

Example: Example Scenarios

These define groups of interrelated examples that demonstrate one or more of the workflows supported by this implementation guide.

European Vaccination Card (EVC)

Use case describing the European Vaccination Card, a citizen-held portable vaccination record enabling bilateral verification across EU member states via an interoperable trust architecture.

Hajj Pilgrimage VHL Flow

Use case describing the sharing of pilgrim health records (International Patient Summary) during Hajj using VHL with WHO GDHCN trust infrastructure for cross-border verification.

Pan-American Highway for Health (PH4H)

Use case describing cross-border health record sharing in the Americas using VHL to support continuity of care for internal migrants across overlapping trust networks.

TEFCA Health Information Exchange

Use case describing how US TEFCA participants (QHINs, providers, payers) can act as VHL Sharers and Receivers using existing TEFCA certificate infrastructure as a trust anchor for VHL exchanges.

WHO GDHCN Trust Establishment

Use case describing how participating jurisdictions establish trust within the WHO Global Digital Health Certification Network (GDHCN) through PKI material submission and trust list distribution.

Example: Example Instances

These are example instances that show what data produced and consumed by systems conforming with this implementation guide might look like.

Invalid Passcode with Remaining Attempts

Response to a Retrieve Manifest request carrying an incorrect passcode. The 401 response reports how many attempts remain before the VHL is disabled.