Verifiable Health Link, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 0.0.2-current 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.YY4 Provide VHL

2:3.YY4 Provide VHL

2:3.YY4.1 Scope

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

The VHL is transmitted as a QR code containing an HCERT-encoded payload with the HC1: prefix. VHL Receivers scan the QR code to extract the VHL payload for subsequent document retrieval.

2:3.YY4.2 Actor Roles

2:3.YY4.3 Referenced Standards

• RFC 7515: JSON Web Signature (JWS)
• RFC 7519: JSON Web Token (JWT)
• RFC 4648: Base64url Encoding
• RFC 8392: CBOR Web Token (CWT)
• RFC 8152: CBOR Object Signing and Encryption (COSE)
• RFC 1950: ZLIB Compressed Data Format
• RFC 1951: DEFLATE Compressed Data Format
• ISO/IEC 18004:2015: QR Code specification
• SMART Health Links Specification: VHL Payload Structure
• WHO SMART Trust HCERT Specification: HCERT Structure

2:3.YY4.4 Messages

2:3.YY4.4.1 Provide VHL Request Message

2:3.YY4.4.1.1 Trigger Events

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

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

A VHL Holder initiates the Provide VHL transaction when:

• The VHL Holder wishes to grant access to their health documents to a VHL Receiver
• The VHL Holder has obtained a valid VHL from a VHL Sharer (via ITI-YY3 Generate VHL transaction)
• The VHL Holder encounters a VHL Receiver capable of processing VHLs in a relevant healthcare context

2:3.YY4.4.1.2 Message Semantics

The VHL payload structure is defined in ITI-YY3 and aligns with the SMART Health Links specification.

QR Code Transmission

The VHL is transmitted via QR code with the following characteristics:

• VHL encoded as HCERT QR code with HC1: prefix
• Suitable for in-person encounters, walk-in clinics, emergency departments
• QR code contains HCERT/CWT structure with embedded SHL payload
• Can be displayed on screen or printed on paper
• Minimum recommended diagonal size: 35-60mm

2:3.YY4.4.1.3 Expected Actions - VHL Holder

The VHL Holder SHALL:

1. Verify QR code validity (not expired, CWT signature valid)
2. Display QR code on device screen or provide printed copy
3. Provide passcode out-of-band if VHL is passcode-protected (P flag present)
4. Ensure QR code is displayed at appropriate size for reliable scanning

The VHL Holder MAY:

• Maintain record of QR code presentations
• Revoke VHL access if supported by VHL Sharer

2:3.YY4.4.1.4 Expected Actions - VHL Receiver

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

Upon receipt, the Receiver SHALL:

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

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

Upon receiving a VHL via QR code, the VHL Receiver SHALL perform the following 9-step decoding process:

1. Scan QR Code:
   • Use QR code scanner (camera, dedicated scanner, or software library)
   • Capture QR code image displayed on screen or printed on paper
   • Decode the QR code per ISO/IEC 18004:2015 in Alphanumeric mode
   • Provide visual feedback to user during scanning process
2. Verify Context Identifier:
   • Extract the complete string from the QR code
   • Verify the string begins with HC1: prefix (HCERT context identifier)
   • If prefix is missing or incorrect, reject and inform user
   • Remove the HC1: prefix from the string
3. Base45 Decode:
   • Decode the remaining string using Base45 decoding algorithm
   • Result is a compressed byte array
   • Handle any Base45 decoding errors appropriately
4. Decompress ZLIB/DEFLATE:
   • Decompress the byte array using ZLIB (RFC 1950) with DEFLATE (RFC 1951)
   • Result is a CBOR-encoded CWT structure
   • Handle decompression errors (corrupted data, invalid format)
5. Parse CBOR Web Token (CWT):
   • Parse the decompressed bytes as CBOR per RFC 8392
   • Extract the CWT structure containing protected header and claims
   • Protected header contains:
     • alg (algorithm): ES256 or PS256
     • kid (key identifier): 8-byte truncated SHA-256 of DSC
   • Handle CBOR parsing errors
6. Verify Digital Signature:
   • Extract kid from CWT protected header
   • Retrieve corresponding Document Signing Certificate (DSC) from trust list
   • Verify the COSE signature (RFC 8152) using DSC public key
   • Confirm signature is valid and CWT has not been tampered with
   • Reject if signature invalid or DSC not trusted
7. Extract and Validate CWT Claims:
   • Extract CWT claims:
     • iss (issuer, claim key 1): ISO 3166-1 alpha-2 country code (optional)
     • iat (issued at, claim key 6): timestamp in NumericDate format
     • exp (expiration, claim key 4): timestamp in NumericDate format
     • hcert (health certificate, claim key -260): HCERT payload object
   • Validate exp - reject if current time > expiration
   • Validate iat is not in the future
8. Extract SHL Payload from HCERT:
   • Within the hcert claim (claim key -260), locate claim key 5
   • Claim key 5 contains the SHL payload object with:
     • url: manifest URL (required) - includes all mandatory FHIR search parameters
     • key: base64url-encoded decryption key, 43 characters (required)
     • flag: flags such as "L" for long-term, "P" for passcode (optional)
     • label: human-readable description (optional)
     • exp: expiration timestamp in seconds since epoch (optional)
     • v: version number (optional)
   • Validate SHL payload structure conforms to SMART Health Links specification
9. Validate SHL Payload:
   • Verify url field is present and is a valid HTTPS URL
   • Verify key field is present and is 43 characters (base64url-encoded 32 bytes)
   • Check SHL exp (if present) - reject if current time > expiration
   • Note flag value:
     • "L" indicates long-term use
     • "P" indicates passcode required (obtain from VHL Holder)
     • "LP" indicates both long-term and passcode-protected
   • Validate url contains expected manifest endpoint format with mandatory parameters

Post-Decoding Actions:

After successfully decoding the VHL payload, the VHL Receiver SHALL:

1. Store Decryption Key Securely:
   • The key parameter from the SHL payload is required to decrypt documents
   • Store the key securely in memory for the session
   • The key will be used during document retrieval (ITI-YY6) to decrypt document contents
2. Parse Manifest URL:
   • Extract the manifest URL from the SHL payload
   • The URL format from ITI-YY3 includes mandatory FHIR search parameters:
     • _id: The folder ID
     • code: Typically "folder"
     • status: Typically "current"

     • patient.identifier: Patient identifier via FHIR chained search on the patient reference parameter, in system

       value format

     • _include=List:item: (if VHL Sharer supports Include DocumentReference Option)
   • Example: https://vhl-sharer.example.org/List?_id=abc123def456&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item
3. Prepare to Retrieve Manifest:
   • The VHL Receiver will use ITI-YY5 Retrieve Manifest with 3-part multipart request:
     • Part 1 (fhir-parameters): FHIR search parameters from the manifest URL
     • Part 2 (shl-parameters): JSON object with recipient, passcode (if P flag), embeddedLengthMax
     • Part 3 (signature): Optional digital signature over Parts 1 and 2
   • Store manifest URL and prepare SHL parameters for ITI-YY5 request

The VHL Receiver MAY:

• Prompt user for passcode if "P" flag is present (required for ITI-YY5)
• Display VHL label/description to user
• Record audit event per Audit Event – Received Health Data
• Cache VHL payload for subsequent access attempts

Decoding Example (QR Code with HCERT):

Input QR Code Content:
HC1:NCF3R0KLBBA...V8N8W.CE8WY

Step 1: Verify and remove HC1: prefix → NCF3R0KLBBA...V8N8W.CE8WY
Step 2: Base45 decode → [compressed bytes]
Step 3: ZLIB/DEFLATE decompress → [CBOR bytes]
Step 4: Parse CBOR as CWT → Extract protected header (alg: ES256, kid: 8-byte SHA-256)
Step 5: Verify COSE signature using DSC from trust list based on kid
Step 6: Extract CWT claims:
  - iss (claim 1): "US"
  - iat (claim 6): 1704067200
  - exp (claim 4): 1735689600
  - hcert (claim -260): {...}
Step 7: Within hcert (claim -260), extract claim key 5 (SHL payload):
  {
    "url": "https://vhl-sharer.example.org/List/_search?_id=abc123def456&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item",
    "key": "dGhpcyBpcyBhIHNlY3JldCBrZXkgdXNlZCBmb3IgZW5j",
    "flag": "LP",
    "exp": 1735689600,
    "label": "Patient Health Summary",
    "v": 1
  }
Step 8: Validate SHL payload fields
Step 9: Parse manifest URL to extract FHIR search parameters
Step 10: Prepare for ITI-YY5 Retrieve Manifest with 3-part multipart request

Manifest URL Parsing:

The manifest URL from the SHL payload contains all parameters needed for ITI-YY5 Part 1 (fhir-parameters):

URL: https://vhl-sharer.example.org/List?_id=abc123def456&code=folder&status=current&patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123&_include=List:item

Parsed FHIR Search Parameters (for ITI-YY5 Part 1):
- _id=abc123def456
- code=folder
- status=current
- patient.identifier=urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123
- _include=List:item (if present, indicates VHL Sharer supports Include DocumentReference Option)

Error Handling:

If QR code scanning or decoding fails:

• QR unreadable or damaged
• Invalid HC1: prefix
• Base45 decode error
• ZLIB decompression error
• CBOR parse error
• Invalid CWT structure
• Missing hcert claim or claim key 5
• Signature verification failure

VHL Receiver SHALL:

• Reject the VHL
• Inform user with specific error message
• Request user to rescan QR code
• NOT attempt to retrieve documents

If signature verification fails:

• VHL Receiver SHALL reject the VHL
• VHL Receiver SHALL NOT attempt to retrieve documents
• VHL Receiver SHOULD inform user/operator
• VHL Receiver MAY log failed verification

If VHL expired (either exp in CWT or SHL payload):

• VHL Receiver SHALL reject the VHL
• VHL Receiver SHOULD inform user/operator
• User may request new VHL from VHL Holder

2:3.YY4.4.2 Provide VHL Response Message

2:3.YY4.4.2.1 Trigger Events

The VHL Receiver MAY provide optional acknowledgment to VHL Holder confirming receipt and validation. This is transmission-mechanism dependent.

2:3.YY4.4.2.2 Message Semantics

For transmission mechanisms supporting bidirectional communication, response MAY include:

2:3.YY4.4.2.3 Expected Actions

VHL Receiver:

• MAY send acknowledgment if supported
• SHALL NOT include sensitive health information

VHL Holder:

• MAY receive and store receipts
• SHALL NOT rely on acknowledgment for security decisions

2:3.YY4.5 Security Considerations

2:3.YY4.5.1 VHL Integrity and Authenticity

• Digital signature ensures VHL issued by trusted VHL Sharer
• VHL Receivers MUST verify COSE signatures before trusting content
• CWT signature provides end-to-end trust verification

2:3.YY4.5.2 VHL Confidentiality

• VHL does NOT contain PHI
• VHL only contains reference (URL) to retrieve documents
• Actual documents retrieved over secure channel (ITI-YY5)
• Encryption key in VHL enables document decryption (ITI-YY6)

2:3.YY4.5.3 Replay Attacks

• VHL Sharers SHOULD include expiration timestamps in both CWT and SHL payload
• VHL Receivers SHOULD enforce expiration validation
• VHL Sharers MAY implement single-use VHLs
• Short expiration times reduce replay attack window

2:3.YY4.5.4 Passcode Protection

• Passcode communicated out-of-band (not in VHL)
• "P" flag indicates passcode required
• Passcode validated during manifest retrieval (ITI-YY5 Part 2)
• VHL Sharers SHOULD implement rate limiting on passcode attempts

2:3.YY4.5.5 Trust Network Validation

VHL Receivers MUST:

• Validate VHL Sharer is current participant in trust network
• Retrieve DSC from trust list using kid from CWT protected header
• Check certificate revocation status where applicable
• Reject VHLs from untrusted participants

2:3.YY4.5.6 QR Code Security

QR Code Characteristics:

• Can be photographed/copied - use time-limited expiration
• Suitable for supervised encounters (in-person, on-screen display)
• Digital signature provides authenticity verification
• Recommended for higher security scenarios

Best Practices:

• Include short expiration times in CWT exp claim
• Use passcode protection (P flag) for sensitive data
• Display QR codes in controlled environments
• Avoid printing QR codes for long-term use unless necessary
• Implement single-use VHLs where appropriate