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.YY2 Retrieve Trust List with DID

Note on Transaction Optionality: This transaction is REQUIRED (R) for Trust Anchor actors and OPTIONAL (O) for VHL Sharer and VHL Receiver actors. Implementations that do not support this transaction must use alternative mechanisms (out of scope for this profile) to retrieve PKI material from the Trust Anchor. Only implementations that claim support for this transaction can participate in IHE Connectathon testing for trust material retrieval. See Volume 1 Section XX.2.1 for details on trust establishment approaches.

2:3.YY2.1 Scope

The Retrieve Trust List with DID transaction allows both VHL Sharers and VHL Receivers to retrieve trusted public key material from the Trust Anchor using Decentralized Identifiers (DIDs).

Retrieved material SHALL be used to determine the trustworthiness of VHL artifacts in accordance with the governing trust framework.

2:3.YY2.2 Actor Roles

2:3.YY2.3 Referenced Standards

• W3C DID Core 1.0: Decentralized Identifiers (DIDs) v1.0
• RFC 7517: JSON Web Key (JWK)
• IHE mCSD: Mobile Care Services Discovery

2:3.YY2.4 Messages

2:3.YY2.4.1 Retrieve Trust List Request Message

2:3.YY2.4.1.1 Trigger Events

A VHL Sharer or VHL Receiver, as a participant in the trust network, SHALL be capable of retrieving public key infrastructure (PKI) material from a designated Trust Anchor.

The retrieved material MAY include:

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

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

Preconditions:

• The requesting participant knows in advance the endpoint from which to retrieve PKI material, as published or distributed by the Trust Anchor.

The Trust Anchor SHALL have made available at least one endpoint (such as an mCSD-compliant endpoint) that is accessible to all participants in the trust network. The requesting participant (VHL Receiver or VHL Sharer) knows in advance the endpoint from which to retrieve DID Documents and PKI material.

The Trust Anchor MAY additionally provide individual endpoints per participant, in addition to the common endpoint.

2:3.YY2.4.1.2 Message Semantics

The Retrieve Trust List Request retrieves DID Documents from the Trust Anchor.

Request Methods:

The mechanism used to retrieve a DID Document is determined by the DID method of the DID being resolved. Implementations SHALL resolve DID Documents according to the resolution rules defined by the applicable DID method specification.

2:3.YY2.4.1.3 Expected Actions

VHL Sharer / VHL Receiver (Requester):

The requesting actor SHALL:

1. Determine Retrieval Endpoint: Identify the Trust Anchor endpoint for DID Document retrieval
2. Construct Request: Build an HTTP GET request for retrieval of DID Document
3. Submit Request: Send the request over a secure connection

2:3.YY2.4.2 Retrieve Trust List Response Message

2:3.YY2.4.2.1 Trigger Events

Upon receipt of Retrieve Trust List Request from a VHL Sharer or VHL Receiver, the Trust Anchor SHALL organize, sign, and expose the PKI material as part of a trusted, canonical trust list.

This MAY include:

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

The Trust Anchor SHALL only respond with validated and trustworthy material in accordance with the governance policies of the VHL trust framework. This signed trust list enables all participants in the VHL trust network to verify digital signatures and establish secure connections in accordance with the governance policies of the Trust Anchor.

Upon receipt of this response, participants SHALL process the trust list as described in Receive Trust List.

2:3.YY2.4.2.2 Message Semantics

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:trust-anchor.example.org:v1:trustlist",
  "controller": "did:web:trust-anchor.example.org:v1:trustlist",
  "verificationMethod": [
    {
      "id": "did:web:trust-anchor.example.org:v1:trustlist#signing-key-1",
      "type": "JsonWebKey2020",
      "controller": "did:web:trust-anchor.example.org:v1:trustlist",
      "publicKeyJwk": {
        "kty": "EC",
        "kid": "signing-key-1",
        "crv": "P-256",
        "x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8",
        "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4"
      }
    },
    {
      "id": "did:example:vhl-sharer-123456#signing-key-2",
      "type": "JsonWebKey2020",
      "controller": "did:web:trust-anchor.example.org:v1:trustlist",
      "publicKeyJwk": {
        "kty": "EC",
        "kid": "signing-key-2",
        "crv": "P-256",
        "x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8-Q",
        "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4-"
      }
    }
  ],
  "proof": {
    "type": "JsonWebSignature2020",
    "created": "2025-01-15T12:00:00Z",
    "verificationMethod": "did:web:trust-anchor.example.org:v1:trustlist#signing-DID",
    "proofPurpose": "assertionMethod",
    "nonce": "a3f8c2d1-9b4e-4f7a-b6e2-1c5d8f3a9e2b",
    "jws": "eyJhbGciOiJFUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..example_signature_value"
  }
}

Error Responses:

Response Elements:

The response SHALL include one or more DID Documents, each containing:

The proof element SHALL contain:

2:3.YY2.4.2.3 Expected Actions

Upon receiving a Retrieve Trust List Request, the Trust Anchor SHALL:

1. Authenticate Request: Validate the requesting entity is authorized to retrieve trust material
2. Process Query: Identify the requested DID Document(s) based on query parameters
3. Filter Results: Return only active, non-revoked DID Documents
4. Construct Response: Format the response according to the requested representation, ensure returned DID Documents conform to W3C DID Core specification and include sufficient verification methods for signature validation
5. Sign Response (optional): Digitally sign the response to ensure integrity

VHL Receiver / VHL Sharer:

A VHL Sharer or VHL Receiver, after receiving PKI material from a Trust Anchor, SHALL validate and process the trust information for subsequent cryptographic operations.

Participants SHOULD:

• Cache the received trust list or certificate material to reduce network and server load
• Validate digital signatures or trust paths before use in VHL validation or secure channel sessions
• Monitor certificate expiration or revocation status where applicable

Upon receiving the Trust List response, the VHL Receiver or VHL Sharer SHALL:

1. Validate Response: Verify the integrity of the response (signature if present)
2. Parse DID Documents: Extract each DID Document from the response
3. Extract Public Keys: Retrieve public key material from verification methods
4. Map to Usage: Associate each verification method with its intended use (authentication, assertion, etc.)
5. Cache: Store the DID Documents according to caching policy
6. Monitor Expiry: Track any expiration times and refresh cached material as needed
7. Handle Response: Process the returned DID Document(s) and extract public key material

2:3.YY2.5 Security Considerations

2:3.YY2.5.1 Secure Retrieval

All Retrieve Trust List interactions MUST occur over a secure connection. The Trust Anchor SHOULD authenticate requesting entities before serving trust material.

2:3.YY2.5.2 DID Document Validation

Clients (VHL Receivers and VHL Sharers) SHALL:

• Verify DID Documents conform to W3C DID Core specification
• Validate that verification methods contain well-formed public keys
• Check that key types and algorithms are acceptable per trust framework policy
• Verify any signatures or integrity proofs on the response payload

2:3.YY2.5.3 Caching and Freshness

Implementations SHOULD:

• Cache retrieved DID Documents to reduce load on Trust Anchor
• Respect any cache-control headers or expiration times
• Implement periodic refresh of cached material
• Immediately invalidate cached DID Documents upon revocation notification

2:3.YY2.5.4 Revocation Checking

The Trust Anchor SHALL:

• Only serve active, non-revoked DID Documents
• Provide mechanisms for distributing revocation information
• Support timely updates when DID Documents are revoked

Clients SHOULD:

• Check revocation status before trusting retrieved material
• Implement appropriate revocation checking mechanisms (e.g., periodic polling, push notifications)

2:3.YY2.5.5 Endpoint Security

The Trust Anchor's DID retrieval endpoint SHOULD:

• Implement rate limiting to prevent abuse
• Log all retrieval attempts for audit purposes
• Use authentication to restrict access to authorized participants
• Be publicly resolvable and tamper-resistant

Content profiles MAY define additional constraints, such as:

• Minimum key lengths (e.g., EC P-256 or stronger)
• Permitted cryptographic algorithms
• Retry and timeout behavior
• Maximum cache lifetimes