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

Significant Changes and Issues

Significant Changes

Significant Changes from Revision x.x

  • NA, initial public comment release

Issues

Submit an Issue

IHE welcomes New Issues from the GitHub community. For those without GitHub access, issues may be submitted to the ITI Public Comment form.

As issues are submitted they will be managed at ITI.VHL GitHub Issues, where discussion and workarounds may be found. These issues, when critical, will be processed using the normal IHE Change Proposal management and balloting. It is important to note that as soon as a Change Proposal is approved, it carries the same weight as a published Implementation Guide (i.e., it is testable at an IHE Connectathon from the time it is approved, even if it will not be integrated until a later date).

Open Issues

  • ToDo_001: Should we introduce a Trust Network Participant (TNP) actor that does the retrieve and publish of keys and then make the VHL Sharer and VHL Receiver grouped actor with the TNP?

  • ToDo_004: Some of the language has the QR code as synonymous with the VHL. Should be careful in Vol 1 that QR is only an example of a type of a VHL that is used for low-bandwidth/contactless/access. Other access mechanisms, such as Bluetooth or NFC, modalities are used in the future for the providing of a VHL by a VHL Holder to a VHL Receiver.

  • ToDo_007: ITI-YY5 Retrieve Manifest Message Semantics alignment with SHL — The current message semantics in ITI-YY5 (Section 2:3.YY5.4.1.2) may diverge from the SMART Health Links retrieve manifest specification. Liaise with the SHL team to identify gaps and request updates to the SHL Manifest logical model

Closed Issues

  • ToDo_002: Can we use the same transaction to retrieve a single doc VHL as well as retrieve the docs in a folder VHL?
    • Resolution: The specification defines a _include option in the ITI-YY5 transaction that supports both single document and folder-based VHL retrieval using the same transaction.
  • ToDo_003: Do we want to talk about the general notion of a health link, and then both the verifiable and shared health links? The SHL model has a different trust network assumption (no pre-coordination of sharer and receiver) so it may be cumbersome to take on in the first pass as the workflow is different?
    • Resolution: The current scope focuses exclusively on Verifiable Health Links (VHL), deferring SMART Health Links (SHL) to a future revision due to the differing trust network assumptions and workflow complexity. This approach allows the specification to establish a solid foundation for pre-coordinated trust models before addressing the more open trust model of SHL.
  • ToDo_005: Should we specify an API mechanism for the Publish PKI Material transaction? It may be enough to treat them as Content Creator/Consumer pairs where the content is the location of a trustlist (as a DID).
    • Resolution: The specification treats the Publish PKI Material transaction as a Content Creator/Consumer interaction where the published content is a DID-referenced trustlist, rather than defining a separate API mechanism. This approach leverages existing IHE content sharing patterns and avoids introducing unnecessary complexity for PKI material distribution.
  • ToDo_006: ITI-YY5 Receiver Authentication for Sharer using Embedded JWS/VC as an option.
    • Resolution: Addressed by the addition of the Sign Manifest Request Option (Verifiable Credential) in ITI-YY5 (Section 2:3.YY5.4.1.6). In this option the VHL Receiver self-issues a JSON-LD LDP-VC (W3C Verifiable Credentials Data Model v2) whose credentialSubject contains the manifest decoded from the QR code. An embedded DataIntegrityProof is computed with the VHL Receiver's key from the trust network. The signed VC is sent directly as the HTTP POST body (Content-Type: application/vc) with the FHIR search parameters carried inside the credential at credentialSubject.id. The VHL Sharer verifies proof.proofValue using the receiver's public key retrieved from the trust network. The option is also reflected in the Actor Options table (Volume 1 Section XX.2.3), the sequence diagram (ITI-YY5.plantuml), and the test plan (testplan.md).
  • GitHub #39: Not clear how to carry PKI based key materials in ITI-YY1 — the transaction addressed only self-generated key pairs, while the GDHCN use case has participating jurisdictions submitting Certificate Authority-issued material (Signing Certificate Authority and Document Signer Certificates) with a certificate chain.
    • Resolution: Addressed at the content level, consistent with the resolution of ToDo_005 (no API mechanism is defined; the transactions constrain the content of the DID Document). ITI-YY1 Trigger Events now describe two paths for obtaining key material, self-generated and Certificate Authority-issued, and state that a participant enrolled under a Signing Certificate Authority does not generate its own trust network signing key. Message Semantics now specify that a certificate chain is carried in the x5c member of the publicKeyJwk (RFC 7517 §4.7), leaf certificate first, and include a worked example carrying a chain. Trust Anchor Expected Actions now include validating the chain to a recognized certificate authority, checking revocation status, and confirming that the certificate subject corresponds to the authenticated submitting participant. ITI-YY2 Expected Actions require the same chain validation by the recipient before a key is used, and state that a key is not trusted merely by appearing in a trust list. The policies governing that validation — recognized authorities, path construction, permitted algorithms, and revocation distribution — remain delegated to the governing trust framework, so no certificate policy is introduced into this profile.
  • ToDo_008: ITI-YY5 — clarify document retrieval transaction and document encryption convention.
    • Resolution: ITI-YY5 now explicitly binds binary document retrieval to the IHE MHD Retrieve Document [ITI-68] transaction, which governs that exchange, and aligns document encryption with the SMART Health Links convention: each binary is a JWE Compact Serialization using alg=dir and enc=A256GCM with the 32-byte SHL key carried in the SHL payload (generated in ITI-YY3, decoded in ITI-YY4). Two response examples were added (with and without the Include DocumentReference Option), and Required Actor Groupings in Volume 1 now requires VHL Sharer ↔ MHD Document Responder and VHL Receiver ↔ MHD Document Consumer groupings. See ITI-YY5 sections 2:3.YY5.4.2.4 (Document Content Retrieval) and 2:3.YY5.4.2.5 (Document Encryption).