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

2:3.YY5 Retrieve Manifest

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.

2:3.YY5.1 Scope

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.

  1. 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.

  2. 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.

  3. 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:

2:3.YY5.2 Actor Roles

Table 2:3.YY5.2-1: Actor Roles

Actor Role
VHL Receiver Request VHL Documents
VHL Sharer Respond to Request VHL Documents

2:3.YY5.3 Referenced Standards

Core Standards:

FHIR Specifications:

IHE Profiles:

  • ITI TF-2: Mobile Health Document Sharing (MHD): ITI-66 Find Document Lists
  • ITI TF-2: Mobile Health Document Sharing (MHD): ITI-68 Retrieve Document - used to retrieve the binary content referenced from DocumentReference.content.attachment.url
  • ITI TF-1: Section 9: ATNA Profile
  • ITI TF-2: 3.19: Authenticate Node transaction

OAuth with SSRAA (Optional):

  • RFC 7515: JSON Web Signature (JWS) - for the OAuth with SSRAA option
  • RFC 7519: JSON Web Token (JWT) - for the OAuth with SSRAA option
  • SMART App Launch Backend Services: Backend Services
  • HL7 Security for Scalable Registration, Authentication, and Authorization IG: SSRAA
  • ITI Internet User Authorization (IUA): IUA Profile

SHL Specifications:

Encryption Standards:

  • RFC 7516: JSON Web Encryption (JWE) - compact serialization used for document encryption
  • RFC 7518: JSON Web Algorithms (JWA) - dir key management and A256GCM content encryption

2:3.YY5.4 Messages

VHL ReceiverVHL SharerVHL ReceiverVHL SharerRetrieve Manifest Request [ITI-YY5]POST /List/_search(authenticated)Retrieve Manifest ResponseFHIR Bundle (searchset)

Figure 2:3.YY5.4-1: Retrieve Manifest Interaction Diagram

2:3.YY5.4.1 Retrieve Manifest Request Message

2:3.YY5.4.1.1 Trigger Events

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:

  • The VHL Receiver has received and validated a VHL containing a manifest URL
  • The VHL Receiver needs to discover available documents before retrieving specific content

Before sending the request, the VHL Receiver SHALL:

  1. Extract Manifest URL from VHL:
    • Obtain manifest URL from VHL payload (ITI-YY4)
    • URL contains all FHIR search parameters (_id, code, status, and the patient identifier via chained search as patient.identifier, plus optional _include)
    • Parse URL to extract search parameters
  2. Prepare Request Parameters:
    • Construct request body with FHIR search parameters from URL
    • Add SHL parameters:
      • recipient (required) - identifier of requesting organization/person
      • passcode (if P flag in VHL) - user-provided passcode
      • embeddedLengthMax (optional) - size hint for embedded content
    • Encode parameters as application/x-www-form-urlencoded
  3. Authenticate Request — applies only where the VHL Receiver claims one of the Sign Manifest Request Options, using the one agreed with the VHL Sharer:
    • HTTP Message Signatures:
      • Compute Content-Digest (SHA-256 of request body)
      • Construct signature base from HTTP components
      • Sign using receiver's private key
      • Include Content-Digest, Signature-Input, and Signature headers
    • OAuth with SSRAA:
      • One-time setup: if not already registered with this VHL Sharer, perform UDAP Discovery and Dynamic Client Registration (per SSRAA Sections 2 and 3) using the FHIR Base URL from the VHL payload to obtain a client ID.
      • Create a JWT client assertion (private_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.1
      • Request an access token from the authorization server (grant_type=client_credentials) with appropriate scopes
      • Include the returned Bearer access token in the Authorization header of the manifest request
      • Reuse the access token across requests until expiration
    • Verifiable Credential:
      • Extract VHL payload fields from the decoded QR code (manifest URL, flags, label, expiration)
      • Construct LDP-VC with credentialSubject.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 VC
      • Compute proof.proofValue (DataIntegrityProof) over the VC document using trust network private key
      • Set proof.verificationMethod to the DID URL of the receiver's trust network key
      • POST the complete VC as Content-Type: application/vc body to /List/_search; the FHIR search parameters travel inside credentialSubject.id and SHALL NOT be repeated in the request line
  4. Send Request:
    • POST to /List/_search endpoint at VHL Sharer's base URL
    • Set Accept: application/fhir+json
    • Under the HTTP Message Signatures and OAuth with SSRAA options, and where no Sign Manifest Request Option is in use: set Content-Type application/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 respectively
    • Under the Verifiable Credential option: set Content-Type application/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 body

The VHL Receiver MAY:

  • Cache OAuth access tokens for reuse (OAuth with SSRAA option)
  • Implement retry logic for transient failures
  • Claim more than one Sign Manifest Request Option, agreeing with the VHL Sharer which to use

The VHL Sharer's response is processed as described in 2:3.YY5.4.2.3 Expected Actions.

2:3.YY5.4.1.2 Message Semantics

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.

2:3.YY5.4.1.3 Expected Actions

Upon receiving a Retrieve Manifest Request, the VHL Sharer SHALL:

  1. Parse Request:
    • Extract FHIR search parameters from request body
    • Extract SHL parameters (recipient, passcode, embeddedLengthMax)
    • Identify which Sign Manifest Request Option the request uses, if any (HTTP Message Signatures, OAuth token, or Verifiable Credential)
  2. Authenticate Receiver — applies only where the VHL Sharer claims one of the Sign Manifest Request Options. A VHL Sharer claiming one rejects a request that carries no credential under the agreed option (401 Unauthorized); a VHL Sharer claiming none proceeds to step 3:
    • HTTP Message Signatures:
      • Extract keyid from Signature-Input header
      • Retrieve receiver's public key from trust list using keyid
      • Reconstruct signature base from request components
      • Verify signature using receiver's public key
      • Verify Content-Digest matches request body
      • Verify created timestamp is within acceptable range (±2 minutes)
      • Reject if signature invalid or receiver not in trust list (401 Unauthorized)
    • OAuth with SSRAA:
      • Extract Bearer token from Authorization header
      • Validate that the token was issued by the authorization server
      • Verify token expiration
      • Verify token scope authorizes access to the VHL
      • Reject if token invalid or expired (401 Unauthorized)
    • Verifiable Credential:
      • Parse application/vc request body as JSON-LD VC document
      • Resolve proof.verificationMethod DID URL to retrieve VHL Receiver's public key from the trust network
      • Verify the proof.proofValue (DataIntegrityProof) over the VC document using the retrieved trust network key
      • Verify proof.proofPurpose is assertionMethod
      • Verify VC validUntil has not passed and validFrom is not in the future; verify proof.created freshness (±2 minutes recommended)
      • Take the FHIR search parameters from credentialSubject.id, which is the manifest URL
      • Extract SHL params from credentialSubject (recipient, passcode, embeddedLengthMax)
      • Where 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)
      • Reject if any verification fails (401 Unauthorized)
  3. Authorize Request:
    • Validate folder ID (_id parameter) corresponds to valid VHL
    • Verify VHL signature matches original issuance
    • Confirm the VHL is still active. Deactivation — whether from an expiry the VHL Sharer applies, exhausted passcode attempts, or withdrawal by the VHL Holder — SHALL be reported as 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 here
    • Verify VHL not revoked (check revocation list if maintained)
    • If passcode provided:
      • Verify VHL requires passcode (P flag present)
      • Validate passcode against stored hash (secure comparison)
      • Reject if passcode incorrect (401 Unauthorized), decrementing the lifetime attempt count for the folder ID and returning the remaining count in the OperationOutcome (see Error Responses)
    • Confirm VHL authorizes requested documents
    • Reject if authorization fails (403 Forbidden)
  4. Execute Search:
    • Query for List resource matching FHIR search parameters:
      • _id (folder ID - required)
      • code (typically "folder" - required)
      • status (typically "current" - required)
      • patient.identifier (chained search on the patient reference parameter - required)
    • Validate List exists and is accessible
    • Apply VHL scope filters (only include documents authorized by VHL)
    • Apply consent filters if applicable
    • If _include=List:item parameter present:
      • If VHL Sharer supports Include DocumentReference Option:
        • Retrieve DocumentReference resources referenced by List.entry.item
        • Apply VHL scope and consent filters to DocumentReferences
        • Include DocumentReferences in response Bundle with search.mode="include"
      • If VHL Sharer does NOT support Include DocumentReference Option:
        • Ignore _include parameter
        • Return only List resource in response
        • VHL Receiver will retrieve DocumentReferences separately
  5. Prepare Response:
    • Construct FHIR Bundle with type="searchset"
    • Add List resource with search.mode="match"
    • If Include DocumentReference Option supported and _include used:
      • Add DocumentReference resources with search.mode="include"
    • Set Bundle.total to count of matching resources
    • Include only documents authorized by VHL
  6. Return Response:
    • Send HTTP 200 OK with FHIR Bundle (application/fhir+json)
    • Handle errors with appropriate HTTP status codes

The VHL Sharer MAY:

  • Record audit event per Audit Event – Accessed Health Data
  • Implement rate limiting per receiver or per folder ID
  • Log failed authentication/authorization attempts
  • Provide OperationOutcome with error details

Supported Search Parameters:

Per the VHL Sharer Server Capability Statement, the VHL Sharer SHALL support:

  • _id (token) - Required
  • code (token) - Required
  • status (token) - Required
  • patient.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"
    }
  ]
}
2:3.YY5.4.1.4 Sign Manifest Request Option (HTTP Message Signatures)

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:

  1. Content-Digest Header:
    • SHA-256 hash of the request body
    • Format: sha-256=<base64-encoded-hash>
    • SHALL be included for POST requests with body
  2. Signature-Input Header:
    • Metadata about the signature
    • Components signed: @method, @path, @authority, content-type, content-digest
    • created: Unix timestamp when signature was created
    • keyid: 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 Selection
  3. Signature Header:
    • Contains the actual cryptographic signature
    • Format: sig1=:<base64-encoded-signature>:
    • Signature is computed over the signature base constructed from the signed components

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.

2:3.YY5.4.1.5 Sign Manifest Request Option (OAuth with SSRAA)

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:

  • SSRAA Discovery and Registration SHALL be completed before requesting access tokens
  • OAuth 2.0 Backend Services authentication MAY be used
  • JWT client assertions SHALL be used for client authentication
  • Access token scope vocabulary is determined by trust community policies per the HL7 Security for Scalable Registration, Authentication, and Authorization IG

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:

  • Algorithm: determined by the HL7 Security for Scalable Registration, Authentication, and Authorization IG, which governs this option. The client assertion is signed with the X.509 credential registered through that IG rather than with trust network key material, so its algorithm is independent of the baseline in Cryptographic Algorithm Selection
  • Header: {"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 IG
  • Payload:
    • iss: 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 endpoint
    • exp: Expiration time (typically 5 minutes from iat)
    • iat: Issued at time
    • jti: 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 IG
  • Signature: Signed with receiver's private key associated with the X.509 certificate in the x5c header

Token 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:

  • Grant Type: client_credentials
  • Client Authentication: private_key_jwt (JWT client assertion)
  • Required Scopes (SMART v2 vocabulary use is illustrative; specific scope requirements are determined by trust community policies per the HL7 Security for Scalable Registration, Authentication, and Authorization IG):
    • system/List.s - Search for List resources
    • system/DocumentReference.r - Read DocumentReference resources
    • system/Binary.r - Read Binary resources (document content)
  • Token Lifetime: Typically 1 hour (3600 seconds)
  • Token Reuse: Access token MAY be reused for multiple requests until expiration, consistent with underlying requirements from the HL7 Security for Scalable Registration, Authentication, and Authorization IG.

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.

2:3.YY5.4.1.6 Sign Manifest Request Option (Verifiable Credential)

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:

  • Hold a key pair registered in the trust network (obtained via ITI-YY2 Retrieve Trust List with DID)
  • Have decoded the VHL (from QR code or from a Verifiable Credential per the VC Enveloped VHL) and extracted the VHL payload (manifest URL, flags, label, etc.) via ITI-YY4

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.proofValue is the sole cryptographic proof of the VHL Receiver's identity. No outer JWT or HTTP Message Signature is needed. The verificationMethod resolves 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 (key field 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.

2:3.YY5.4.2 Retrieve Manifest Response Message

2:3.YY5.4.2.1 Trigger Events

This message is sent when the VHL Sharer has successfully authenticated the VHL Receiver, authorized the VHL, and retrieved the requested document manifest.

2:3.YY5.4.2.2 Message Semantics

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:
    • "match" for List resource(s) matching search criteria
    • "include" for DocumentReference resources included via _include parameter
  • List.entry[].item: References to DocumentReference resources on the VHL Sharer
  • DocumentReference.content.attachment.url: Absolute URL the VHL Receiver dereferences via Retrieve Document [ITI-68] to obtain the (encrypted) binary
  • DocumentReference.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)
2:3.YY5.4.2.3 Expected Actions

The VHL Receiver SHALL:

  • Parse the Bundle and distinguish List vs. DocumentReference resources by search.mode.
  • If the Bundle does NOT contain DocumentReference resources (Case A): for each List.entry[].item.reference, perform a FHIR read against the VHL Sharer to obtain the DocumentReference metadata.
  • For each DocumentReference, retrieve the binary by dereferencing content.attachment.url per Retrieve Document [ITI-68], reusing the same authentication option chosen for this ITI-YY5 session.
  • Decrypt the retrieved binary using the key from the VHL payload cached from ITI-YY4, per Document Encryption.
  • Verify that the decrypted payload's media type matches DocumentReference.content.attachment.contentType.

The VHL Receiver MAY:

  • Display the document list to the user.
  • Filter or sort documents based on metadata.
  • Retrieve and decrypt document content on demand rather than eagerly.
2:3.YY5.4.2.4 Document Content Retrieval

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.

2:3.YY5.4.2.5 Document Encryption

VHL document binaries are encrypted following the SMART Health Links — Encrypting and Decrypting Files convention.

Algorithm:

  • Serialization: JWE Compact Serialization per RFC 7516.
  • Key management (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.
  • Symmetric key: The 32-byte (256-bit) value carried as 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.
  • Initialization vector: The VHL Sharer SHALL generate a fresh IV for every encryption, as required by the SMART Health Links encryption convention. A single 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:

  • Encryption SHALL be applied to the document binary at 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.
  • An unencrypted variant is permitted only when the originating VHL payload was generated without a 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.

2:3.YY5.5 Security Considerations

2:3.YY5.5.1 Transport Security

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.

2:3.YY5.5.2 HTTP Message Signatures

Implementations that support HTTP Message Signatures per RFC 9421:

  • Signature algorithm and key strength — see Cryptographic Algorithm Selection
  • Private keys SHOULD be stored securely (Hardware Security Module recommended)
  • Replay attacks are prevented by timestamp validation

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.

2:3.YY5.5.3 Audit Logging

Both VHL Receiver and VHL Sharer SHOULD log:

  • All document access requests (successful and failed)
  • Authentication method used (HTTP signatures, OAuth, or Verifiable Credential)
  • Receiver identity (from keyid or OAuth token)
  • VHL folder ID
  • Authorization decisions (approved/denied)
  • Timestamps
  • IP addresses
  • User identifiers (from recipient parameter)

2:3.YY5.5.4 Rate Limiting

The VHL Sharer SHOULD implement rate limiting:

  • Per receiver (identified by keyid or OAuth client_id)
  • Per folder ID (to prevent brute force on VHL tokens)
  • Per IP address
  • Return 429 Too Many Requests when limits exceeded

2:3.YY5.5.5 Passcode Security

When the VHL is passcode-protected (P flag):

  • Failed passcode attempts SHOULD be rate limited
  • Passcode SHOULD NOT be logged in audit trails
  • Consider lockout after repeated failed attempts

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:

  • A total lifetime count of incorrect attempts for a given folder ID, after which the VHL stops resolving. Rate limiting alone only slows an exhaustive search of a short numeric passcode; a lifetime count is what ends it. VHL Sharers SHOULD enforce such a count in addition to the per-receiver and per-folder limits in Rate Limiting.
  • Enforcement against concurrent requests, not only sequential ones. An attacker issuing many manifest requests in parallel can otherwise burn through far more guesses than the counter allows before any of them records a failure. Limiting in-flight requests per folder ID, or serializing their processing, closes that gap.

2:3.YY5.5.6 Privacy of Request Metadata

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.

  • The manifest request carries the patient business identifier. Parameter Placement is where this profile requires that identifier to travel in the request body, or within the credential, rather than in the request line. The reason is retention: request lines are recorded by default in web server, proxy and content-distribution logs, and those logs are typically kept far longer, and read by more people, than the health data itself.
  • The 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.
  • Both the VHL Receiver and the VHL Sharer SHOULD ensure that audit records capture the folder ID rather than the full manifest URL where the audit trail has a different retention period or a wider readership than the transaction logs.