Skip to content

Interop Stack

Jump to bottom
Josh Mandel edited this page Feb 1, 2021 · 10 revisions

The end-to-end job of building a "Health Card" ecosystem requires several key components. There are diverse standards for each, and for any given standard there a number of implementation decision to lock down if we expect to see interoperability. Here's a quick list:

  1. Trust Framework (e.g., how to tell who is/was a valid issuer)
  2. Protocols for obtaining credentials (e.g., how to retrieve and store a VC)
  3. Protocols for requesting and presenting VCs
  4. Data models for claims within a VC (e.g., what lab test was performed, or what immunization was administered)
  5. Protocols for signing and verifying VCs (e.g., discovery methods for keys; binding keys to domains; cryptographic algorithms; revocation)

The Health Cards spec makes the following choices:

  1. Trust framework decisions are left out of band; initial deployments will include a registry of trusted issuers hosted by The Commons Project that will allow verifying parties to learn which issuers are participating (and to discover metadata about these issuers suitable for showing to end-users, such as organization names or logos). Anyone can host a similar registry, and it's up to verifiers to choose one or more registries, or create their own. The goal is to avoid placing limits on who can participate in the ecosystem, allowing different trust communities to evolve as needed.

  2. We define two mechanisms for obtaining credentials:

  • downloading a .fhir-backed-vc file (e.g., from a a health care provider portal; e-mail attachment; deep link in an SMS, etc)
  • calling $HealthWallet.issueVc as a FHIR Operation, on servers that support FHIR-based issuance
  • in both cases, the issuer can optionally bind a Health Card to a holder's DID by following the OpenID "DID-SIOP" protocol
  1. We support these mechanisms for requesting/presenting credentials:
  • For communicating between a holder app and an off-device verifying party: DID-SIOP flow using a QR code scanner in the wallet as the entry-point for the request
  • For communicating between a holder app and a mobile website verifying party: DID-SIOP flow using a openid:// link (though we should note that support for custom app schemes on iOS is limited; this is an issue for any attempt at a standardized redirection scheme, so we're exploring alternatives like file-download to trigger a better "app picker" UX)
  • For communicating between an wallet app and an on-device third-party verifier app, we expect that wallet apps may offer tailored mobile SDKs; the payloads are consistent with DID-SIOP requests and responses

  1. For claims within a VC, we use FHIR's standard JSON Bundle data structures as a general framework for conveying demographic and clinical data. We define detailed FHIR Profiles for specific domains (e.g., https://github.com/dvci/vaccine-credential-ig for Vaccination Credentials).

  2. For signing, encrypting, and verifying statements, we wanted to pick algorithms and resolution protocols as specifically as feasible, for consistent implementations. We support:

  • Signatures: JWS compact serialization ("alg": "ES256")

  • Encryption: JWE compact serialization ("alg": "ECDH-ES" and "enc": "A256GCM")

  • DID methods for key discovery: did:ion method with long-form DIDs only. We require issuers to be identified by a long-form ION DID for discovery, but we do not require this DID to be anchored to a distributed ledger at this point (i.e., we use ION's long-form constructs only). This leaves open the possibility of allowing updates in the future, but keeps the resolution process static for now.

  • Binding Issuer DIDs to Domains:

    • service endpoints inside of long-form DID allowing DID -> domain discovery
    • hosted .well-known/did-configuration allowing domain->DID discovery and confirmation

    Note that many of the choice above follow from the use DID-SIOP: in DID-SIOP, the response is a Verifiable Presentation, encoded as an id_token JWS with compact serialization, optionally wrapped in a JWE when the verifier wants that. We use the same signature format for VCs inside the id_token as for the outer VP.

    Goals here include: choose a fixed set of algorithms and DID methods to ensure that all parties can ensure interop with others; limit the total number of DID, signature, and encryption methods to limit implementation effort (ideally picking just one, when possible, since all participants must support all choices); choose a DID method suitable for 1..* conversations to support issuers; ensure that DIDs can work in an "offline" fashion; provide a forward path for updating DIDs in the future, without requiring participants to support updates in v1.

Clone this wiki locally