Skip to content

Interop Stack

Jump to bottom
Josh Mandel edited this page Apr 27, 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 decisions 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:

  • print or download a QR code (e.g., from a health care provider portal; e-mail attachment; deep link in an SMS, etc)
  • download .smart-health-card file (e.g., from a health care provider portal; e-mail attachment; deep link in an SMS, etc)
  • calling $health-cards-issue as a FHIR Operation, on servers that support FHIR-based issuance
  1. We support these mechanisms for requesting/presenting credentials:
  • For communicating between a holder app and an off-device verifying party: present the credential JWS directly embedded in a QR code
  • For communicating between a holder app and a mobile website verifying party: upload a QR or .smart-health-card file to the verifying party
  • For communicating between a 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 the options above

  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 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")
  • Public key discovery: append /.well-known/jwks.json to the issuer URL to retrieve an issuer's keyset
  • Binding Issuer keys to domains:
    • via /.well-known/jwks.json

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 signature and key discovery methods to limit implementation effort (ideally picking just one, when possible, since all participants must support all choices); ensure that verifications can work in an "offline" fashion.

Clone this wiki locally