Per-SHC Revocation

[christianpaquin]

SHC revocation discussion

We are starting to hear interest in revocation schemes from jurisdictions that are detecting fraud in their own issuance history. In order to promote interoperability, the framework should specify an optional mechanism to enable this.

PR #198 proposes a mechanism to achieve this. This page is to discuss the design, constraints, and different proposed ideas.

Requirements

• The goal is to revoke already issued SHCs, we therefore cannot modify the content of SHCs.
• Keep things as simple as possible for issuers: fraudulent cards are already in circulation, so we want something easy to build and deploy, and something that works for most of the issuers.
• Keep things efficient for verifiers: we don't want to add extra connections and lengthy downloads for each SHC validations; solution should work for offline verifiers.
• No action from users: seems like a no-brainer (people still need to be able to present paper SHCs), but this rules out interesting revocation methods where clients can prove non-revoked status.

Executive summary

The proposed solution is quite simple: issuers create and update Card Revocation Lists (CRL, a useful backcronym) containing unique fingerprints of revoked SHCs. Verifiers reject a SHC if its fingerprint is listed on the issuer's CRL.

Revocation value

The first question is what can be used to recognized SHCs to revoke. The suggestion is to use the cryptographic digest of a card's JWS. This acts as a unique fingerprint of the SHC.

Some comments:

• Technically, we propose using the first 128 bits of the SHA-256 digest to reduce the size of the CRLs. SHA-256 is the recommended hash algorithm, and it is infeasible to find collisions in half-digests. It could be possible to reduce the output further, but would require more analysis.
• Other revocation handles have been proposed, such as:
  • unique elements in the FHIR data, combined with the SHC's nbf field: this requires extra logic on the verifier
  • unique values in the ECDSA signature: could be susceptible to DoS attacks (by issuing colliding values) and ties the design of the revocation mechanism to the specific SHC sig alg.

Card Revocation List

The proposed solution is to associate CRLs with individual issuer keys (identified by their kid), rather than with an issuer itself. This gives control to the issuer to cap the size of the CRLs by rotating keys, and wiping the slate clean if they revoke the key itself.

The proposal is as follows:

• Issuers maintain https://"<<Issuer URL>>"/.well-known/crl/kid/"<<kid>>".json CRL file, for each of its keys
• Each CRL contains:
  • The kid
  • A counter counting the updates to the file
  • An array of revoked SHCs digest fragment (RDF)
• To revoke a SHC, the issuer calculates the RDF and adds it to the corresponding array. When ready to update the file (the frequency is up to the issuer), the counter is incremented and published at the location.
• The revocation support is advertised by adding a crl#ctr field with the CRL's counter value to the corresponding JWK object in the issuer's jwks.json file.
• Verifiers rejects a SHC if its RDF is listed in the issuer's CRL. CRL retrieval depends on the counter value:
  • Online-only verifiers download the issuer JWK set and CRL everytime
  • Online with caching verifiers fetch the new CRL if its counter (in the JWK) is higher than the cached one
  • Offline verifiers obtain the latest JWK set and CRL when they update.

Trust frameworks (such as the VCI) could help package, distribute, aggregate these CRLs, and provide further capabilities to help verifiers determining the revocation status of a SHC.

Some comments:

• A counter was proposed vs. a timestamp. Counter are simple, and allow verifiers to determine how many updates they missed. Timestamps are also easy to use, but have some issues (drawing from implementation mistakes we've seen for the SHC's nbf values).

Open questions

The above could be called a v1: easy to build and deploy. Some open questions remain.

Support for dynamic update

For online-with-caching verifiers, it would be desirable to only download the CRL updates. One question is: do we really want this? This only saves bandwidth at verification time, as the aggregated CRL still needs to be stored on the verifier side after the update(s). Does it make such a big difference for verifiers to download thousand 16-byte fingerprints (~1k file) vs a dozen?

This section describes different proposals for dynamic updates. Many of these refer to a CRL update, which is a CRL files only listing the revoked value since a particular version.

Dynamic response from issuer

The verifier could request a specific CRL update using the counter (or timestamp) in a query parameters. This requires dynamic handling on the issuer side, who would generate the require CRL or pick from a set of files.

Etags

HTTP ETags could be used on the CRL request. Sending cached ETag headers allow verifiers to only get an updated CRL if it has changed (If-None-Match, If-Modified-Since). Hosting and CDN services (including GH Pages) should support out of the box.

Static CRL update files

Every time the CRL is updated, the issuer updates the kid.json file, but also creates a sibling kid-ctr.json file with the counter value, containing only the newly revoked digests. This way, a verifier could either request the full CRL, or only the deltas since the last ctr it saw.

Append-only CRLs

HTTP range requests could be used to only retrieved updates from append-only CRLs (e.g., a list of kids separated by newlines). Many static hosting services support out of the box. The JWK could advertise the current file length + hash, and clients could request a range to catch up. See these PR comments for details: 1, 2, 3.

[pvillela]

Issuers maintain https://"<<Issuer URL>>"/.well-known/crl/kid/"<<kid>>".json CRL file, for each of its keys

I suggest the above text be modified as follows:

• Issuers maintain an https://"<<Issuer URL>>"/.well-known/crl/kid/"<<kid>>".json CRL file for each of its keys that has an associated revocation list. Such a URL is not required for a key that does not have an associated revocation list.

Verifiers rejects a SHC if its RDF is listed in the issuer's CRL. CRL retrieval depends on the counter value:

I suggest that the above bullet and sub-bullets be modified as follows:

• Verifiers reject a SHC if its RDF is listed in the issuer's CRL. CRL retrieval depends on the counter value:

  • Online-only verifiers download the issuer JWK each time an SHC is presented. If the SHC's kid has an associated CRL (i.e., there is a "crl" field associated with the kid), then the verifier also downloads the corresponding CRL.
  • Online with caching verifiers fetch the new CRL if its counter (in the JWK) is higher than the cached one.
  • Offline verifiers obtain the latest JWK set when they update. For each kid with an associated CRL, they also download the corresponding CRL if the "crl" counter value in the JWK is higher than that of the currently stored CRL for that kid.

Support for dynamic update

I feel the base proposal adequately addresses the needs of both online and offline validator apps and I don't see much value in the support for dynamic update.

[christianpaquin]

We are converging on a design. I'd like to have a discussion next week with those interested, to mark PR #198 as "ready for review". Those who can't make it will have the opportunity to comment on the final proposal before it is merged. Please let me know of your availability here: https://www.when2meet.com/?13543272-5VH8Z

[christianpaquin]

Tuesday Nov 9th at 2:30pm Eastern Time is the only availability that everyone can make; let's meet then. Teams meeting link sent to those with known email addresses; for others (@pvillela), use this link.

[christianpaquin]

We had a productive meeting with many folks from across the board. In order to inform the next steps and propose an update, we’d like to get more information regarding the capabilities of issuers wrt the proposed options. I'd invite issuers to answer this questionnaire.

[pvillela]

Alternative Proposal for Individual SHC Revocation: FHIR Bundle Revocation (Tentative Outline)

Following is a tentative outline of an alternative revocation scheme for individual SHCs roughly based on what was discussed during the 2021-11-09 meeting.

This scheme is comparable to the hash-fhir method of the official legacy revocation proposal, but it groups revocation items into CRLs (card revocation lists) differently than the official proposal. The different grouping approach is advantageous for caching verifiers but requires all verifiers to maintain a cache (which is a disadvantage for some online verifiers).

With this scheme, what is specifically revoked is a FHIR bundle, with the consequence that an SHC containing that FHIR bundle gets revoked.

An important feature of this revocation approach (shared by its official proposal counterpart) is that it enables the effective revocation of SHCs even when the issuer does not keep track of previously issued SHCs. Although this scheme does not require issuers to keep track of previously issued SHCs, it supports a simpler and more efficient revocation process for issuers that do keep track of previously issued SHCs. The checking of revoked SHCs by verifiers is the same in either case and can be performed in an efficient manner.

Issuer Components

An issuer that has revoked individual SHCs needs to implement the following to make the revoked SHCs known:

• In addition to the existing URL for publication of public keys:

  https://<Issuer URL>/.well-known/jwks.json
  

  the issuer will need to establish another URL:

    https://<Issuer URL>/.well-known/revocation-groups.json
  

  that publishes a file with a list (which may be empty) of revocation group identifiers, and another set of URLs:

    https://<Issuer URL>/.well-known/crl/group/<gid>.json
  

  one for each revocation group identifier (gid) in revocation-groups.json and each of which publishes a file with the list of identifiers of revoked FHIR bundles in a given revocation group. This is called the Card Revocation List (CRL) for the gid.
• The intent is to organize the revocations into groups such that:
  • The number of revocations in each group is manageable.
  • The number of revocation groups is manageable.
  • There is an indication as to whether a group of revocations has changed (i.e., has had revocations added to it), so that a verifier does not need to download again the revocations list for a group that has not changed.
• Example revocation-groups.json:

  {
      "gids": [
          {
              "gid": "abc",
              "ctr": 200
          },
          {
              "gid": "xyz",
              "ctr": 3
          }
      ]
  }

• Example <gid>.json, for gid=”xyz”, i.e., xyz.json:

  {
      “gid”: “xyz”,
      "method": "hash-fhir-groups",
      “ctr”: 3,
      "rids": [
          “ZeD_6x_KU0q.1636546545",
          “8DJBTjvQ-pW.2636546545",
          “VeSJe1rgHmr.3636546545",
          “f6PjunL8mu7.4636546545",
          “Je_FAq9Qzpq.6636546545"
      ]
  }

• The revocation group identifiers (gids) can be any alphanumeric ASCII strings. They could, for example, be “1”, “2”, “3”, etc., or “vBx7y0a”.
• An issuer can set a target maximum number of items for each revocation group and stop adding SHC identifiers to a group once the target maximum is reached. Having at most one revocation group that may change at any point in time makes it easier and more efficient for offline verifiers to update their cached revocation lists.
• The CRL for a given revocation group is a list (rids) of revocation IDs.
• A rid is computed as the concatenation of:
  • The base64url encoding of the first 64 bits of the SHA-256 digest of the base64url encoding of the UTF-8 encoding of the minified FHIR bundle of the revoked SHC. This is the rid prefix.
  • “.”
  • The effective time of the revocation, in seconds, in RFC 7519 format.

Issuer Actions

Whenever a FHIR bundle is to be revoked by the issuer, the following steps are taken:

• The FHIR bundle identifier is computed as described above.
• The issuer decides whether to create a new revocation group or reuse an existing one.
• If a new revocation group is created:
  • A unique identifier (gid) is defined for the revocation group.
  • The URL https://<Issuer URL>/.well-known/crl/group/<gid>.json is established.
  • The file <gid>.json is created and the rid for the FHIR bundle is added to it.
  • An object for <gid> is added to revocation-groups.json. That object has a “ctr” field with a value (version number) of 1.
• If an existing revocation group is reused:
  • The file <gid>.json is updated with the addition of the rid for the FHIR bundle.
  • The object for <gid> in the revocation-groups.json file is updated by having its “ctr” field value (version number) incremented by 1.

Verifier Actions

The process followed by all verifiers is similar.

• Regardless of whether it is an online or offline verifier, any verifier will need to have a local data store that contains and supports efficient identification of revoked SHCs, for each supported issuer, indexed by the first component (prefix) of the FHIR bundle rid.
• Online verifiers download the issuer’s jwks.json and revocation-groups.json upon scanning each SHC. If the stored version of any revocation group is lower than the version indicated in revocation-groups.json then the verifier would also download that revocation group’s <gid>.json and update the local revocation information.
• Caching/offline verifiers download each supported issuer’s jwks.json and revocation-groups.json from time to time, but not upon scanning each SHC. Following that download, If the stored version of any of the issuer’s revocation groups is lower than the version indicated in revocation-groups.json then the verifier would also download that revocation group’s <gid>.json and update the local revocation information.
• After scanning an SHC and asserting its integrity, the verifier performs the following steps to check whether the SHC has been revoked:
  • The SHC’s FHIR revocation identifier prefix is computed as described earlier in the Issuer Components section.
  • The SHC’s FHIR revocation identifier prefix is looked-up on the local revocation store. If found and if the SHC’s nbf is less than the rid's nbf component, then the SHC is considered to be revoked; otherwise it is considered to be valid.

Revocation without Tracking Issued SHCs

Following is a use case that has been brought-up by multiple issuers and the revocation procedure to be followed:

• An individual has a history of clinical events on their record – ce1, ce2, ce3, …, ceN – and a specific one of these events, say ce3, is considered to be erroneous or fraudulent. The clinical events are ordered by the time of insertion into the individual's record.
• Issuer doesn’t know what SHCs have been issued for this individual, but it must revoke any SHCs that may have been issued with the faulty clinical event.
• Issuer computes revocation identifiers for hypothetical FHIR bundles assembled with the following contents, where p0 is the FHIR entry containing patient information and fe1, fe2, etc. are the FHIR entries corresponding to the clinical events in the patient's history:
  • fb1: p0, e1, fe2, fe3
  • fb2: p0, fe1, fe2, fe3, fe4
  • …
  • fbN-2: p0, fe1, fe2, fe3, fe4, …, feN
• Issuer uses the computed revocation identifiers and the previously described process to revoke each of the above hypothetical FHIR bundles.
• Even though the issuer doesn’t know which of the hypothetical FHIR bundles are present in issued SHCs, the revocation lists surely contain any bad FHIR bundles for SHCs that may have been issued to that individual.
• Issuer should then set aside the faulty event from the individual’s clinical event list so that future SHCs issued for the individual have proper content.

Revocation with Tracking of Issued SHC Timestamps

When the issuer keeps track of the issue timestamp for each issued SHC then the revocation process for the above use case is simplified as follows:

• An individual has a history of clinical events on their record – ce1, ce2, ce3, …, ceN – and a specific one of these events, say ce3, is considered to be erroneous or fraudulent. The clinical events are ordered by the time of insertion into the individual's record.
• Issuer knows the timestamps of all SHCs that have been issued for this individual.
• Based on the SHC issuance timestamps, the issuer can precisely reconstruct the actual FHIR bundles included in the issued SHCs. Consider, for example, the scenario where two SHCs had been issued for the patient and, based on the timestamps of the issued SHCs, the issuer was able to determine that one SHC contained clinical events ce1 to ce4 and the other one contained clinical events ce1 to ce7. In that case, the issuer would be able to reconstruct the following two FHIR bundles, where p0 is the FHIR entry containing patient information and fe1, fe2, etc. are the FHIR entries corresponding to the clinical events in the patient's history:
  • fb1: p0, e1, fe2, fe3, fe4
  • fb2: p0, e1, fe2, fe3, fe4, fe5, fe6, fe7
• Issuer uses the computed revocation identifiers and the previously described process to revoke each of the above specific FHIR bundles.
• Issuer should then set aside the faulty event from the individual’s clinical event list so that future SHCs issued for the individual have proper content.

[pvillela]

One question I have @pvillela is what are the benefits of creating revocation groups vs a counter on the revocation file?

@christianpaquin, if I understand your question correctly, the point of defining groups is to be able to partition the revocation information into smaller files, each of which stops changing after a while, rather than one potentially large revocation file that keeps growing forever. The group ID and its version number (ver) in this revocation scheme play a similar role to the one played by the kid version number (crl) advertised in the jwks.json file in the other revocation scheme, to the extent that they both allow verifiers to avoid downloading unchanged files of revocation IDs.

[christianpaquin]

I see. Yes, one goal is to have a controllable cap on the size of the CRL files. One built-in control that exist is the key rotation, so linking the CRL to a key seems natural. Are there really that many issuers who wouldn't know under which key a card issued? General guidance is that issuers rotate their keys annually, so if you can't narrow down revocation timeframe to a couple of year (if you uncertain, you can add the revocation id to multiple keys' CRL), then you really don't have great opsec. Since CRL need to be kept essentially forever, linking them to keys naturally reduce which CRL a verifier will need to obtain. Presumably, older expired keys will only have signed old SHCs, which will likely be replaced by more recent ones (as people get new immunizations); so verifiers won't have to download old CRLs very often. If you create per-issuer groups, you don't know which one a particular SHC belongs to, so you'd have to obtain all of them, always.

[jfhamme-cccs]

Ah, yes. Thanks for that clarification, @pvillela. While the group ID does allow a verifier to skip unnecessary downloads, I'm more concerned about the processing time for verifying individual SHCs since the number of FHIR revocation digests needed to check for a match just grows with time regardless of key rotation.

[christianpaquin]

@pvillela, we can continue the discussion of per-kid vs. per-group revocation on discussion #207. The new vision is that future cards will have a simple revocation id, so existing JWK sets probably don't have too many keys (kids) since launch, perhaps addressing some of your concerns.

[pvillela]

@christianpaquin and @jfhamme-cccs, your points above are well taken. Grouping by kid is indeed feasible with the recognition that a given computed rid may have to be listed under a small number of kids (typically no more than two) for the backward-compatible use case (i.e., no tracking of SHCs issued).

[christianpaquin]

Please see the updated forward-looking proposal in PR #205, superseding the original #198. Also see the new discussion #207 where we can continue discussing the backward-compatible scheme needed for currently issued cards.

[pvillela]

@christianpaquin, #207 describes the FHIR bundle digest legacy revocation scheme at a very high level. Where will additional details and decisions be described, e.g., use of kid (or <group id>) for publishing of revocation files?