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 both the VHL Receiver (Initiator) and the VHL Sharer (Responder). Optional behaviors within this transaction, such as the Sign Manifest Request Options, the Include DocumentReference Option and the Verify Document Signature Option, are defined as actor options for this transaction.
The Retrieve Manifest transaction enables a VHL Receiver to retrieve a manifest (searchset Bundle) of available health documents from a VHL Sharer using a previously obtained and validated Verifiable Health Link (VHL).
This transaction occurs after the VHL Receiver has received a VHL from a VHL Holder (via ITI-YY4 Provide VHL) and validated the VHL signature.
FHIR Search Transaction: This transaction uses a standard FHIR search on the List resource, following the same pattern as MHD ITI-66 Find Document Lists. The manifest URL from the VHL payload contains all necessary FHIR search parameters. No custom operation is required.
Authentication: Authentication of the VHL Receiver to the VHL Sharer is provided by the three Sign Manifest Request Options, each named for the mechanism it uses. Each is optional for both the VHL Receiver and the VHL Sharer (Volume 1 Table 1:XX.2-1), and each is complementary between them. Nothing in this transaction obliges either actor to support any of them.
Sign Manifest Request Option (HTTP Message Signatures): the VHL Receiver signs selected components of the outgoing HTTP manifest request (e.g., @method, @target-uri, content-digest, date) using its trust-network key, and the VHL Sharer verifies the signature against the VHL Receiver's public key from the trust network. This option requires no additional token endpoint or credential exchange — authentication is carried entirely within the HTTP request itself. See 2:3.YY5.4.1.4.
Sign Manifest Request Option (OAuth with SSRAA): OAuth 2.0 access tokens as defined in the HL7 Security for Scalable Registration, Authentication, and Authorization IG (SSRAA), using OAuth Backend Services with JWT client assertions for system-to-system authentication. See 2:3.YY5.4.1.5.
Sign Manifest Request Option (Verifiable Credential): the VHL Receiver self-issues a JSON-LD Verifiable Credential (LDP-VC) whose subject is the manifest decoded from the VHL (received as a QR code or as a Verifiable Credential per ITI-YY4). The VC carries an embedded DataIntegrityProof signed with the VHL Receiver's trust-network key and is sent directly as the HTTP POST body (Content-Type: application/vc). No additional HTTP-level signing is needed; the embedded proof is sufficient. See 2:3.YY5.4.1.6.
Where both actors claim the same option, the VHL Sharer authenticates the requesting VHL Receiver and confirms its authorization within the trust network before returning a manifest. Where none of the three is in use the VHL Sharer does not establish who is asking, and access to the manifest follows from possession of the VHL, together with the passcode where the P flag is set. A deployment that requires the identity of the requester to be established — by jurisdictional policy, by regulation, or under a data sharing agreement — therefore requires one of these options of both actors.
Include DocumentReference Option: A VHL Sharer that supports the Include DocumentReference Option SHALL process the _include=List:item parameter to retrieve both the List and the referenced DocumentReference resources in a single response. This optimization reduces the number of round trips required by the VHL Receiver. If a VHL Sharer does not support this option, it SHALL ignore the _include parameter, and the VHL Receiver SHALL retrieve each DocumentReference individually using separate read requests.
Independently of those options, the VHL Receiver SHALL have verified the VHL signature against the trust list before making this request (see ITI-YY4), and the VHL Sharer SHALL validate the VHL presented to it — folder ID, whether the VHL is still active, revocation status, and the passcode where the P flag is set — before returning a manifest. Verification of the VHL is what the VHL Sharer always relies on; authentication of the VHL Receiver is the additional control that the Sign Manifest Request Options provide.
Capability Statements:
Table 2:3.YY5.2-1: Actor Roles
| Actor | Role |
|---|---|
| VHL Receiver | Request VHL Documents |
| VHL Sharer | Respond to Request VHL Documents |
Core Standards:
FHIR Specifications:
IHE Profiles:
DocumentReference.content.attachment.urlOAuth with SSRAA (Optional):
SHL Specifications:
dir + A256GCM convention used to encrypt document binariesEncryption Standards:
dir key management and A256GCM content encryptionFigure 2:3.YY5.4-1: Retrieve Manifest Interaction Diagram
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:
A VHL Receiver initiates the Retrieve Manifest Request when:
Before sending the request, the VHL Receiver SHALL:
application/x-www-form-urlencodedprivate_key_jwt) signed with the receiver's trust-network private key — the X.509 cert (or chain) goes in the x5c header; iss and sub are the registered client ID; aud is the authorization server token endpoint; include jti and the hl7-b2b extension per SSRAA Section 5.2.1grant_type=client_credentials) with appropriate scopesAuthorization header of the manifest requestcredentialSubject.id = manifest URL and the SHL manifest parameters (recipient, passcode, embeddedLengthMax) as members of credentialSubject, declaring every term used in @context. The VHL payload encryption key SHALL NOT appear anywhere in the VCproof.proofValue (DataIntegrityProof) over the VC document using trust network private keyproof.verificationMethod to the DID URL of the receiver's trust network keyContent-Type: application/vc body to /List/_search; the FHIR search parameters travel inside credentialSubject.id and SHALL NOT be repeated in the request line/List/_search endpoint at VHL Sharer's base URLapplication/fhir+jsonapplication/x-www-form-urlencoded, send the parameters prepared in step 2 as the request body, and carry the credential from step 3 in the Content-Digest/Signature-Input/Signature headers or in the Authorization header respectivelyapplication/vc and send the credential constructed in step 3 as the request body. The parameters prepared in step 2 travel inside the credential and SHALL NOT also be sent as a form bodyThe VHL Receiver MAY:
The VHL Sharer's response is processed as described in 2:3.YY5.4.2.3 Expected Actions.
This transaction uses a standard FHIR search on the List resource. The request is sent to the manifest URL decoded from the VHL (from ITI-YY4). The manifest URL contains all necessary FHIR search parameters.
Manifest URL Structure
The VHL Receiver performs an HTTP POST to the _search endpoint with the manifest URL parameters from the VHL payload:
Example Manifest URL from VHL:
https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item
FHIR Search Parameters
The FHIR search parameters listed in Table 2:3.YY5.4.1.2-1 are extracted from the manifest URL.
Table 2:3.YY5.4.1.2-1: FHIR Search Parameters of the Manifest URL
| Parameter | Type | Cardinality | Description | Example |
|---|---|---|---|---|
| _id | token | [1..1] | The folder ID (with 256-bit entropy) from the VHL - primary authorization mechanism | _id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT |
| code | token | [1..1] | The type of List (typically "folder") | code=folder |
| status | token | [1..1] | The status of the List (typically "current") | status=current |
| patient.identifier | token (chained) | [1..1] | FHIR chained search on the patient reference parameter; resolves the patient by business identifier (system|value) without requiring a direct Patient resource reference. |
patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123 |
| _include | special | [0..1] | Include referenced DocumentReference resources; SHALL be "List:item" if used. Only processed if VHL Sharer supports Include DocumentReference Option | _include=List:item |
SHL Manifest Request Parameters
In addition to the FHIR search parameters in the URL, the following SHL-defined manifest parameters (per the SMART Health Links specification) SHALL be included in the request body, as listed in Table 2:3.YY5.4.1.2-2:
Table 2:3.YY5.4.1.2-2: SHL Manifest Request Parameters
| Parameter | Type | Cardinality | Description |
|---|---|---|---|
| recipient | string | [1..1] | Identifier of the requesting organization or person (e.g., "Dr. Smith Hospital", "Emergency Department - General Hospital") |
| passcode | string | [0..1] | User-provided passcode if the VHL is passcode-protected (P flag present in VHL) |
| embeddedLengthMax | integer | [0..1] | Integer upper bound on the length of embedded payloads (optional optimization hint) |
Parameter Placement
The manifest URL decoded from the VHL is a FHIR search URL in GET form — [base]/List?…. The VHL Receiver issues the request as an HTTP POST to [base]/List/_search, carrying the parameters from that URL. POST is used rather than GET so that the passcode and the other SHL manifest parameters travel in the request body rather than the request line.
Each parameter SHALL be conveyed exactly once. FHIR permits search parameters to appear in the query string of a _search request as well as in the body, and treats a parameter appearing in both places as a repeat of that parameter — which for _id would change the meaning of the search. Implementations SHALL therefore place the parameters in one location only, as listed in Table 2:3.YY5.4.1.2-3:
Table 2:3.YY5.4.1.2-3: Parameter Placement by Sign Manifest Request Mechanism
| Sign Manifest Request Option | Parameters conveyed in |
|---|---|
| HTTP Message Signatures | the application/x-www-form-urlencoded request body |
| OAuth with SSRAA | the application/x-www-form-urlencoded request body |
| Verifiable Credential | credentialSubject.id within the credential (see 2:3.YY5.4.1.6) |
Keeping the parameters out of the request line also keeps the patient business identifier out of server, proxy and content-distribution logs, where request lines are commonly recorded by default. See Security Considerations.
Upon receiving a Retrieve Manifest Request, the VHL Sharer SHALL:
401 Unauthorized); a VHL Sharer claiming none proceeds to step 3:
keyid from Signature-Input headerkeyidcreated timestamp is within acceptable range (±2 minutes)application/vc request body as JSON-LD VC documentproof.verificationMethod DID URL to retrieve VHL Receiver's public key from the trust networkproof.proofValue (DataIntegrityProof) over the VC document using the retrieved trust network keyproof.proofPurpose is assertionMethodvalidUntil has not passed and validFrom is not in the future; verify proof.created freshness (±2 minutes recommended)credentialSubject.id, which is the manifest URLcredentialSubject (recipient, passcode, embeddedLengthMax)termsOfUse or credentialSubject.purposeOfUse is present, record what was claimed; the VHL Sharer MAY check either against its own policy and against the purpose recorded at ITI-YY3, and reject an unacceptable or inconsistent claim at step 3 (403 Forbidden)404 Not Found, following SMART Health Links. The VHL payload exp is a hint to the VHL Receiver and is not by itself the condition checked hereOperationOutcome (see Error Responses)_include=List:item parameter present:
_include parameter_include used:
The VHL Sharer MAY:
Supported Search Parameters:
Per the VHL Sharer Server Capability Statement, the VHL Sharer SHALL support:
_id (token) - Requiredcode (token) - Requiredstatus (token) - Requiredpatient.identifier (chained search on the patient reference parameter, token — system|value) - required. This is the same business identifier the VHL Holder supplied as sourceIdentifier at ITI-YY3. The direct patient reference parameter is not used in VHL manifest URLs.The VHL Sharer that supports the Include DocumentReference Option SHALL additionally support:
_include=List:item (special)Error Responses:
Table 2:3.YY5.4.1.7-1: Retrieve Manifest Error Responses
| HTTP Status | Condition | OperationOutcome.issue.code |
|---|---|---|
| 400 Bad Request | Malformed request or missing required parameters | invalid |
| 401 Unauthorized | Signature verification failed, token invalid, receiver not in trust list, or invalid/missing passcode | security |
| 403 Forbidden | VHL does not authorize the requested documents, or the VHL Receiver's stated terms of use or purpose of use are not accepted | forbidden |
| 404 Not Found | List resource with specified _id not found, or the VHL is no longer active — deactivated, expired or revoked | not-found |
| 429 Too Many Requests | Rate limit exceeded | throttled |
| 500 Internal Server Error | Server-side error during processing | exception |
Invalid passcode. Following the SMART Health Links manifest request, an invalid or missing passcode SHALL return 401 Unauthorized, and the OperationOutcome SHALL carry the number of attempts remaining before the VHL is disabled in the Remaining Passcode Attempts extension. That count is a total for the lifetime of the VHL rather than per session; once it is exhausted the VHL stops resolving and later requests return 404 Not Found.
Example Error Response:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "security",
"diagnostics": "HTTP signature verification failed: signature does not match"
}
]
}
Example Error Response — invalid passcode (401):
{
"resourceType": "OperationOutcome",
"issue": [
{
"extension": [
{
"url": "https://profiles.ihe.net/ITI/VHL/StructureDefinition/remaining-passcode-attempts",
"valueInteger": 2
}
],
"severity": "error",
"code": "security",
"diagnostics": "Invalid passcode"
}
]
}
A VHL Receiver and a VHL Sharer that claim the Sign Manifest Request Option (HTTP Message Signatures) authenticate the manifest request using HTTP Message Signatures per RFC 9421, which provide cryptographic proof of the receiver's identity, request integrity, and non-repudiation.
Request Structure:
POST /List/_search HTTP/1.1
Host: vhl-sharer.example.org
Content-Type: application/x-www-form-urlencoded
Content-Length: 234
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Input: sig1=("@method" "@path" "@authority" "content-type" "content-digest");created=1735689600;keyid="7pQvN3xT9Kc=";alg="ecdsa-p256-sha256"
Signature: sig1=:K2qGT5srn2OGbOIDzQ6kYT+ruaycnDAAUpKv+ePFfD6...:
Accept: application/fhir+json
_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn%3Aoid%3A2.16.840.1.113883.2.4.6.3%7CPASSPORT123&_include=List%3Aitem&recipient=Dr.+Smith+Hospital&passcode=user-pin&embeddedLengthMax=10000
HTTP Signature Components:
sha-256=<base64-encoded-hash>@method, @path, @authority, content-type, content-digestcreated: Unix timestamp when signature was createdkeyid: Identifier of the VHL Receiver's public key. It resolves the same way as the COSE kid on a VHL: the value is the fragment of a verification method in the receiver's DID Document, and equally the kid of that method's publicKeyJwk, so the VHL Sharer dereferences it against the trust list retrieved through ITI-YY2.alg: Signature algorithm — selected per Cryptographic Algorithm Selectionsig1=:<base64-encoded-signature>:Signature Base Construction:
The signature base is constructed per RFC 9421 from the signed components:
"@method": POST
"@path": /List/_search
"@authority": vhl-sharer.example.org
"content-type": application/x-www-form-urlencoded
"content-digest": sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=
"@signature-params": ("@method" "@path" "@authority" "content-type" "content-digest");created=1735689600;keyid="7pQvN3xT9Kc=";alg="ecdsa-p256-sha256"
Signature Algorithms:
Signature algorithms are selected per Cryptographic Algorithm Selection.
The VHL Receiver signing steps are described in Trigger Events. The VHL Sharer verification steps are described in Expected Actions. Security requirements are in Security Considerations Section 2:3.YY5.5.2.
Implementations that claim the Sign Manifest Request Option (OAuth with SSRAA) use OAuth 2.0 access tokens for authentication in place of HTTP message signing. This option provides interoperability with systems implementing the HL7 Security for Scalable Registration, Authentication, and Authorization IG (SSRAA). The following workflow description is informative only, and does not take precedence over underlying requirements from the HL7 Security for Scalable Registration, Authentication, and Authorization IG.
Preconditions: SSRAA Discovery and Registration
Before an access token can be obtained, the VHL Receiver and VHL Sharer SHALL have completed SSRAA Discovery and Dynamic Client Registration (per SSRAA Sections 2 and 3) at least once per VHL Receiver / VHL Sharer pair — the FHIR Base URL of the VHL Sharer comes from the VHL payload. These steps MAY take place in advance or just in time; the VHL Receiver steps are described in Trigger Events.
Option Requirements:
When both VHL Receiver and VHL Sharer claim this option:
Step 1: Obtain Access Token
POST /oauth/token HTTP/1.1
Host: authorization-server.example.org
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&scope=system/List.s system/DocumentReference.r system/Binary.r
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1YyI6WyJNSUkuLi4iLCJNSUkuLi4iXX0.eyJpc3MiOiI2QjlFRkQ3NDg4MkM0RTZDQjVFNTYxOUU4MjFDNTBGQSIsInN1YiI6IjZCOUVGRDc0ODgyQzRFNkNCNUU1NjE5RTgyMUM1MEZBIiwiYXVkIjoiaHR0cHM6Ly9hdXRob3JpemF0aW9uLXNlcnZlci5leGFtcGxlLm9yZy90b2tlbiIsImlhdCI6MTczNTY4OTYwMCwiZXhwIjoxNzM1Njg5OTAwLCJqdGkiOiJyYW5kb20tdW5pcXVlLWlkIiwiZXh0ZW5zaW9ucyI6eyJobDctYjJiIjp7InZlcnNpb24iOiIxIiwib3JnYW5pemF0aW9uX2lkIjoiaHR0cHM6Ly9kaXJlY3RvcnkuZXhhbXBsZS5vcmcvT3JnYW5pemF0aW9uL3ZobC1yZWNlaXZlci1pZCIsInB1cnBvc2Vfb2ZfdXNlIjoidXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjE4LjcuMSNTWVNERVYifX19.signature-here
JWT Client Assertion:
{"alg":"RS256","typ":"JWT","x5c":["<base64-encoded-client-cert>","<base64-encoded-intermediate>"]}
x5c: The receiver's X.509 certificate (and optionally the full chain) from the trust community PKI, per the HL7 Security for Scalable Registration, Authentication, and Authorization IGiss: Client ID assigned to the VHL Receiver during SSRAA Registration (same as sub)sub: Client ID assigned to the VHL Receiver during SSRAA Registration (same as iss)aud: Authorization server token endpointexp: Expiration time (typically 5 minutes from iat)iat: Issued at timejti: Unique identifier for this JWT (prevents replay)extensions: An object containing an hl7-b2b member with the business-to-business identity context, per Section 5.2.1 of the HL7 Security for Scalable Registration, Authentication, and Authorization IGx5c headerToken Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsIng1YyI6WyJNSUkuLi4iLCJNSUkuLi4iXX0.eyJpc3MiOiI2QjlFRkQ3NDg4MkM0RTZDQjVFNTYxOUU4MjFDNTBGQSIsInN1YiI6IjZCOUVGRDc0ODgyQzRFNkNCNUU1NjE5RTgyMUM1MEZBIiwiYXVkIjoiaHR0cHM6Ly9hdXRob3JpemF0aW9uLXNlcnZlci5leGFtcGxlLm9yZy90b2tlbiIsImlhdCI6MTczNTY4OTYwMCwiZXhwIjoxNzM1Njg5OTAwLCJqdGkiOiJyYW5kb20tdW5pcXVlLWlkIiwiZXh0ZW5zaW9ucyI6eyJobDctYjJiIjp7InZlcnNpb24iOiIxIiwib3JnYW5pemF0aW9uX2lkIjoiaHR0cHM6Ly9kaXJlY3RvcnkuZXhhbXBsZS5vcmcvT3JnYW5pemF0aW9uL3ZobC1yZWNlaXZlci1pZCIsInB1cnBvc2Vfb2ZfdXNlIjoidXJuOm9pZDoyLjE2Ljg0MC4xLjExMzg4My4zLjE4LjcuMSNTWVNERVYifX19.signature-here",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "system/List.s system/DocumentReference.r system/Binary.r"
}
Step 2: Retrieve Manifest with Token
POST /List/_search HTTP/1.1
Host: vhl-sharer.example.org
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Accept: application/fhir+json
_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn%3Aoid%3A2.16.840.1.113883.2.4.6.3%7CPASSPORT123&_include=List%3Aitem&recipient=Dr.+Smith+Hospital&passcode=user-pin&embeddedLengthMax=10000
OAuth Token Requirements:
client_credentialsprivate_key_jwt (JWT client assertion)system/List.s - Search for List resourcessystem/DocumentReference.r - Read DocumentReference resourcessystem/Binary.r - Read Binary resources (document content)The VHL Receiver side (SSRAA Discovery/Registration, JWT client assertion creation, access token acquisition, and Authorization-header inclusion) is described in Trigger Events. The VHL Sharer side (Bearer token validation) is in Expected Actions.
Implementations that claim the Sign Manifest Request Option (Verifiable Credential) use a self-issued JSON-LD Verifiable Credential (LDP-VC) for authentication. Under this option the VHL Receiver constructs a VC whose credentialSubject is the manifest decoded from the VHL (received as a QR code or as a Verifiable Credential per ITI-YY4), and whose embedded DataIntegrityProof is signed with the VHL Receiver's key from the trust network. The VC is sent directly as the HTTP POST body with Content-Type: application/vc. No additional HTTP-level signing is required; the DataIntegrityProof inside the VC document is the cryptographic proof of the receiver's identity and QR possession.
Preconditions:
Before using this option, the VHL Receiver SHALL:
Self-Issued VC Construction:
The VHL Receiver SHALL construct the VC as a JSON-LD document per the W3C Verifiable Credentials Data Model v2 with an embedded proof of type DataIntegrityProof per the W3C Verifiable Credential Data Integrity 1.0 specification:
The credential carries the three SHL-defined manifest parameters inside credentialSubject, which
places them within the signature. Because those parameters are defined by the SMART Health Links
specification rather than by the VC Data Model, the credential declares them in an inline
@context — this keeps the credential self-contained and avoids a dependency on any externally
hosted context document.
Agreements and purpose of use. The proof establishes who the VHL Receiver is and that it holds the VHL. It does not say under which agreement the VHL Receiver is asking, or for what purpose. The credential MAY state both, and because both sit inside the proof they are verifiable and auditable rather than asserted out of band:
termsOfUse, defined by the W3C Verifiable Credentials Data Model v2, names the policy or agreement the VHL Receiver acts under — the trust domain's terms of use, a data sharing agreement, or a Consent.policyRule recorded by an IHE PCF Consent Recorder. Each value SHALL carry a type, as that specification requires; VHLAccessPolicy is the type this profile defines for a policy identified by URL. The VHL Sharer is not required to dereference the policy, and SHOULD NOT dereference it at request time — the value identifies a policy the VHL Sharer already holds.credentialSubject.purposeOfUse carries the purpose the VHL Receiver asserts, in FHIR token form (system|code), bound (extensible) to PurposeOfUse. This is the Verifiable Credential counterpart to the purpose claim an OAuth access token or the SSRAA hl7-b2b extension carries, and the claim that $generate-vhl anticipates at Purpose of Use Handling.Both are assertions the VHL Receiver makes about itself. Neither is an authorization granted by the
VHL Sharer or by the VHL Holder, and neither substitutes for consent. What they give the
VHL Sharer is a stated basis to check its own policy against, and a signed record of what was
claimed: a VHL Sharer MAY reject a request whose stated terms or purpose it does not accept, or
which is inconsistent with the purposeOfUse recorded at ITI-YY3, with
403 Forbidden.
The other two Sign Manifest Request Options have no equivalent carrier. Under OAuth with SSRAA the
purpose travels in the access token or in the hl7-b2b extension; under HTTP Message Signatures
there is no defined place for either claim. A deployment that requires the VHL Receiver to state
the agreement it acts under therefore uses one of the two options that can carry it.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
{
"@vocab": null,
"recipient": "https://profiles.ihe.net/ITI/VHL/ns#recipient",
"passcode": "https://profiles.ihe.net/ITI/VHL/ns#passcode",
"embeddedLengthMax": "https://profiles.ihe.net/ITI/VHL/ns#embeddedLengthMax",
"purposeOfUse": "https://profiles.ihe.net/ITI/VHL/ns#purposeOfUse",
"VHLAccessPolicy": "https://profiles.ihe.net/ITI/VHL/ns#VHLAccessPolicy"
}
],
"type": ["VerifiableCredential"],
"issuer": "did:web:vhl-receiver.example.org",
"validFrom": "2024-01-15T10:00:00Z",
"validUntil": "2024-01-15T10:05:00Z",
"credentialSubject": {
"id": "https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item",
"recipient": "Dr. Smith Hospital",
"passcode": "user-pin",
"embeddedLengthMax": 10000,
"purposeOfUse": "http://terminology.hl7.org/CodeSystem/v3-ActReason|TREAT"
},
"termsOfUse": [
{
"type": "VHLAccessPolicy",
"id": "https://trust.example.int/policies/vhl-access/2026-01"
}
],
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-rdfc-2019",
"created": "2024-01-15T10:00:00Z",
"verificationMethod": "did:web:vhl-receiver.example.org#7pQvN3xT9Kc=",
"proofPurpose": "assertionMethod",
"proofValue": "z3FD9sJ8kL2m9pQ7rT4vW5xY6zAb3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ"
}
}
VC Fields:
| Field | Description |
|---|---|
@context |
SHALL begin with https://www.w3.org/ns/credentials/v2, followed by definitions for the SHL manifest parameters. Every term used in the credential SHALL be defined, so that no member is discarded during JSON-LD processing and left outside the signature |
issuer |
The VHL Receiver's DID or identifier corresponding to its trust network key |
validFrom |
Timestamp from which the credential is valid |
validUntil |
Expiration (SHALL be short-lived; recommended: 5 minutes from validFrom) |
credentialSubject.id |
The manifest URL — binds the VC to the specific manifest decoded from the VHL. It contains the folder ID, so a valid signature over this credential is proof that the VHL Receiver holds that VHL |
credentialSubject.recipient |
Identifier of the requesting organization or person (replaces SHL recipient body parameter) |
credentialSubject.passcode |
User-provided passcode if the VHL is passcode-protected (replaces SHL passcode body parameter) |
credentialSubject.embeddedLengthMax |
Optional size hint for embedded content (replaces SHL embeddedLengthMax body parameter) |
credentialSubject.purposeOfUse |
Optional. Purpose of use the VHL Receiver asserts for this request, in FHIR token form (system|code), bound (extensible) to PurposeOfUse. Self-asserted, and MAY repeat |
termsOfUse |
Optional. The policy or agreement the VHL Receiver acts under. Each value SHALL carry a type and MAY carry an id identifying the policy instance. Self-asserted |
proof |
Embedded DataIntegrityProof — the cryptographic proof of the VHL Receiver's identity |
proof.type |
DataIntegrityProof — W3C Data Integrity proof |
proof.cryptosuite |
Cryptosuite used — selected per Cryptographic Algorithm Selection |
proof.created |
Timestamp when the proof was created (SHALL match validFrom) |
proof.verificationMethod |
DID URL resolving to the VHL Receiver's public key in the trust network (e.g., did:web:receiver.example.org#key-id) |
proof.proofPurpose |
assertionMethod — the VHL Receiver is asserting this credential |
proof.proofValue |
Multibase-encoded cryptographic signature over the VC document (computed with the VHL Receiver's private key from the trust network) |
Note: The
proof.proofValueis the sole cryptographic proof of the VHL Receiver's identity. No outer JWT or HTTP Message Signature is needed. TheverificationMethodresolves to the receiver's public key in the trust network (obtainable via ITI-YY2). The VHL Sharer MUST verify this proof. The VHL payload encryption key (keyfield from the VHL payload) SHALL NOT appear anywhere in the VC.
Request Structure:
The VHL Receiver sends the VC as the POST body. The FHIR search parameters and the SHL manifest parameters are both carried inside the credential — the search parameters within credentialSubject.id, which is the manifest URL, and the SHL parameters as members of credentialSubject. The request line therefore carries no parameters:
POST /List/_search HTTP/1.1
Host: vhl-sharer.example.org
Content-Type: application/vc
Accept: application/fhir+json
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
{
"@vocab": null,
"recipient": "https://profiles.ihe.net/ITI/VHL/ns#recipient",
"passcode": "https://profiles.ihe.net/ITI/VHL/ns#passcode",
"embeddedLengthMax": "https://profiles.ihe.net/ITI/VHL/ns#embeddedLengthMax",
"purposeOfUse": "https://profiles.ihe.net/ITI/VHL/ns#purposeOfUse",
"VHLAccessPolicy": "https://profiles.ihe.net/ITI/VHL/ns#VHLAccessPolicy"
}
],
"type": ["VerifiableCredential"],
"issuer": "did:web:vhl-receiver.example.org",
"validFrom": "2024-01-15T10:00:00Z",
"validUntil": "2024-01-15T10:05:00Z",
"credentialSubject": {
"id": "https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item",
"recipient": "Dr. Smith Hospital",
"passcode": "user-pin",
"embeddedLengthMax": 10000,
"purposeOfUse": "http://terminology.hl7.org/CodeSystem/v3-ActReason|TREAT"
},
"termsOfUse": [
{
"type": "VHLAccessPolicy",
"id": "https://trust.example.int/policies/vhl-access/2026-01"
}
],
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-rdfc-2019",
"created": "2024-01-15T10:00:00Z",
"verificationMethod": "did:web:vhl-receiver.example.org#7pQvN3xT9Kc=",
"proofPurpose": "assertionMethod",
"proofValue": "z3FD9sJ8kL2m9pQ7rT4vW5xY6zA..."
}
}
The VHL Sharer takes the FHIR search parameters from credentialSubject.id rather than from the request line. Two consequences are worth noting: the parameters are inside the signature, so they cannot be altered in transit; and the patient business identifier does not appear in the request line, where it would otherwise be recorded by default in server, proxy and content-distribution logs.
The VHL Receiver VC issuance steps are described in Trigger Events. The VHL Sharer VC verification steps are in Expected Actions.
This message is sent when the VHL Sharer has successfully authenticated the VHL Receiver, authorized the VHL, and retrieved the requested document manifest.
Because the VHL manifest URL constructed at ITI-YY3 is a FHIR search on List using the search parameters required by the Document Responder in IHE MHD ITI-66 Find Document Lists, the Retrieve Manifest response is — at the FHIR level — an MHD ITI-66 response message: a FHIR searchset Bundle. The shape of the Bundle depends on whether the VHL Sharer supports the Include DocumentReference Option AND the VHL Receiver included _include=List:item in the request, as listed in Table 2:3.YY5.4.2.2-1:
Table 2:3.YY5.4.2.2-1: Retrieve Manifest Response Cases
| Case | Bundle contents | Receiver follow-up |
|---|---|---|
A. Include DocumentReference Option NOT used (option unsupported, or _include not requested) |
Standard MHD ITI-66 response: only List resource(s) with search.mode="match". List.entry[].item.reference points to a DocumentReference on the VHL Sharer. |
Receiver SHALL FHIR-read each referenced DocumentReference (GET /DocumentReference/<id>) before retrieving binaries. |
| B. Include DocumentReference Option used | List resource(s) with search.mode="match" PLUS the referenced DocumentReference resources with search.mode="include". |
Receiver proceeds directly to binary retrieval; no extra metadata round-trip. |
In both cases the Receiver subsequently retrieves each binary via Retrieve Document [ITI-68] and decrypts it as described in Document Encryption.
Case A — Bundle without Include DocumentReference Option
The Bundle conforms to the standard MHD ITI-66 response. For Bundle structure, element semantics, and a worked example, see ITI-66 Message Semantics. The VHL Receiver SHALL resolve each List.entry[].item.reference via a separate FHIR read on the VHL Sharer before retrieving binaries.
Case B — Bundle with Include DocumentReference Option
The Bundle extends the ITI-66 response by including each referenced DocumentReference resource (search.mode="include") — this _include=List:item behavior is not defined by ITI-66. The VHL Receiver can move directly to binary retrieval.
{
"resourceType": "Bundle",
"type": "searchset",
"total": 5,
"link": [
{
"relation": "self",
"url": "https://vhl-sharer.example.org/List?_id=lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item"
}
],
"entry": [
{
"fullUrl": "https://vhl-sharer.example.org/List/lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT",
"resource": {
"resourceType": "List",
"id": "lHBSyhoJRJiO7zU0pxJLPA3traJm0sx2CsO9m6ABOAT",
"status": "current",
"mode": "working",
"code": {
"coding": [
{
"system": "https://profiles.ihe.net/ITI/MHD/CodeSystem/MHDlistTypes",
"code": "folder"
}
]
},
"subject": {
"identifier": {
"system": "urn:oid:2.16.840.1.113883.2.4.6.3",
"value": "PASSPORT123"
}
},
"date": "2024-01-15T10:30:00Z",
"entry": [
{
"item": {
"reference": "DocumentReference/doc001"
}
},
{
"item": {
"reference": "DocumentReference/doc002"
}
},
{
"item": {
"reference": "DocumentReference/doc003"
}
},
{
"item": {
"reference": "DocumentReference/doc004"
}
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://vhl-sharer.example.org/DocumentReference/doc001",
"resource": {
"resourceType": "DocumentReference",
"id": "doc001",
"status": "current",
"type": {
"coding": [
{
"system": "http://loinc.org",
"code": "34133-9",
"display": "Summarization of Episode Note"
}
]
},
"subject": {
"identifier": {
"system": "urn:oid:2.16.840.1.113883.2.4.6.3",
"value": "PASSPORT123"
}
},
"date": "2024-01-15T09:00:00Z",
"content": [
{
"attachment": {
"contentType": "application/pdf",
"url": "https://vhl-sharer.example.org/Binary/doc001-content"
}
}
]
},
"search": {
"mode": "include"
}
},
{
"fullUrl": "https://vhl-sharer.example.org/DocumentReference/doc002",
"resource": {
"resourceType": "DocumentReference",
"id": "doc002"
},
"search": {
"mode": "include"
}
},
{
"fullUrl": "https://vhl-sharer.example.org/DocumentReference/doc003",
"resource": {
"resourceType": "DocumentReference",
"id": "doc003"
},
"search": {
"mode": "include"
}
},
{
"fullUrl": "https://vhl-sharer.example.org/DocumentReference/doc004",
"resource": {
"resourceType": "DocumentReference",
"id": "doc004"
},
"search": {
"mode": "include"
}
}
]
}
Key Elements:
Bundle.type: Always "searchset"Bundle.total: Total number of matching resources (List + included DocumentReferences)Bundle.entry[].search.mode:
_include parameterList.entry[].item: References to DocumentReference resources on the VHL SharerDocumentReference.content.attachment.url: Absolute URL the VHL Receiver dereferences via Retrieve Document [ITI-68] to obtain the (encrypted) binaryDocumentReference.content.attachment.contentType: The decrypted content type (e.g. application/fhir+json, application/pdf). The transport content type observed during ITI-68 retrieval is application/jose whenever the binary is encrypted (see Document Encryption)The VHL Receiver SHALL:
search.mode.List.entry[].item.reference, perform a FHIR read against the VHL Sharer to obtain the DocumentReference metadata.content.attachment.url per Retrieve Document [ITI-68], reusing the same authentication option chosen for this ITI-YY5 session.key from the VHL payload cached from ITI-YY4, per Document Encryption.DocumentReference.content.attachment.contentType.The VHL Receiver MAY:
The VHL Sharer returns FHIR DocumentReference metadata as part of, or referenced from, the manifest Bundle. The document binary is not returned by this transaction. It is retrieved separately by dereferencing DocumentReference.content.attachment.url, and that retrieval SHALL conform to the IHE MHD Retrieve Document [ITI-68] transaction, which governs the exchange. The actor groupings that make it available are required in Volume 1 Section XX.3 Required Actor Groupings.
Where the VHL payload carries a key, the binary so retrieved is encrypted; see Document Encryption.
VHL document binaries are encrypted following the SMART Health Links — Encrypting and Decrypting Files convention.
Algorithm:
alg) and content encryption (enc): the VHL Sharer SHALL use alg=dir with enc=A256GCM, as required by the SMART Health Links encryption convention. These are fixed rather than selected per Cryptographic Algorithm Selection: the key in the VHL payload is a raw 256-bit symmetric key, which is what dir consumes directly, and a VHL Receiver that could not assume the pair would have to negotiate it with no channel in which to do so.key in the VHL payload generated by ITI-YY3 and decoded by the VHL Receiver in ITI-YY4. The receiver caches this key for the duration of the VHL session.key covers every document in the folder and is retained when a document is updated, so an IV repeated under that key would break both the confidentiality and the authenticity guarantees of AES-GCM.Scope:
DocumentReference.content.attachment.url. It is independent of the Include DocumentReference Option — the option only controls whether DocumentReference metadata is bundled into the manifest response.DocumentReference.content.attachment.contentType SHALL describe the decrypted payload (e.g. application/fhir+json, application/pdf). The encrypted transport representation is signaled by the application/jose Content-Type on the ITI-68 response.key (matching SHL payload format semantics). VHL flows generated per ITI-YY3 always include a key and therefore always encrypt.Example — JWE Compact Serialization (illustrative, truncated):
eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0
.
.
48V1_ALb6US04U3b
.
5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6jiSdiwkIr3ajwQzaBtQD_A
.
XFBoMYUZodetZdvTiFvSkQ
The five dot-separated segments are the JWE Compact Serialization (RFC 7516): protected header, encrypted key, initialization vector, ciphertext, and authentication tag. The protected header decodes to {"alg":"dir","enc":"A256GCM"}, and the second segment is empty because alg=dir carries no encrypted key.
Decryption (informative): The VHL Receiver base64url-decodes the IV, ciphertext, and authentication tag, then applies AES-256-GCM with the cached VHL payload key and the protected header as Additional Authenticated Data (per RFC 7516 Section 5.1). The plaintext is the original document body whose media type is DocumentReference.content.attachment.contentType. See the SHL spec for full algorithmic detail.
Secure transport is required for all communications in this transaction. See Volume 1 Section 1:XX.5.2 Secure Channel Requirements for the applicable ATNA baseline.
Implementations that support HTTP Message Signatures per RFC 9421:
A signature that covers content-digest commits to the exact bytes of the request body. Any intermediary that alters those bytes — a gateway that re-encodes form parameters, a proxy that re-chunks or re-serializes content, a security appliance that normalizes the payload — will cause verification to fail, and the failure is indistinguishable at the VHL Sharer from a forged request. Deployments that place such intermediaries between the VHL Receiver and the VHL Sharer SHOULD confirm that the request body is conveyed unmodified, or select one of the other authentication options, whose credentials are not bound to the body encoding.
Both VHL Receiver and VHL Sharer SHOULD log:
The VHL Sharer SHOULD implement rate limiting:
When the VHL is passcode-protected (P flag):
The passcode is carried in the request body, or inside the credential under the Verifiable Credential mechanism, over the ATNA secure channel — so it stays out of request lines, proxy logs and content-distribution logs. It is not otherwise protected in transit, which is inherited from the SMART Health Links manifest request. The defense against a weak passcode is therefore limiting how many guesses an attacker gets, not the transport.
Two measures from the SMART Health Links specification are worth carrying into a VHL deployment:
The manifest URL contains the patient business identifier that the VHL Holder supplied at ITI-YY3 — for example a passport or national identifier. While this is not clinical data, it is personal data under data protection regimes such as the European Health Data Space, and it is durable and highly identifying.
label field is free text carried in the clear inside the VHL, readable by anyone who scans the QR code or opens the credential. It SHOULD identify the share to the VHL Holder without disclosing clinical information — "Patient Health Summary" rather than a diagnosis, service or department name.