This design covers the exposure notification key server’s ability to verify diagnosis certifications from public health authorities.
The actual process of issuing these certificates is not covered in this document, but will be at a later date. A simple example of certificate signing is available in tools/example-verification-signing
The current exposure notifications publication protocol only has the ability to authenticate that a request came from a mobile device via the vendor specific device attestation protocols. This doesn’t provide a way to certify that the diagnosis came from a trusted (by the server) public health authority in the jurisdiction.
The exposure notification key server will accept this JWT in the current
verificationPayload field in the exposure reporting API. When this is present,
device attestations should be disabled. In addition, the exposure publishing
API will also accept a new field
hmackey to be used as the key for
re-calculating the HMAC that was signed by the PHA verification server. The
hmackey field must be base64 encoded.
The JWT itself will be unpacked and the following validations will be performed. First, using the standard claims.
iss: The issuer will be used to determine which public key(s) are valid for verification. This is to allow for key rotation.
aud: The audience must be as configured for this installation of the exposure notification key server. The operator of the exposure notification key server is the one to define this value and should be shared to all participating health authorities.
iat: The unix timestamp at which the token was issued.
exp: The unix timestamp at which the token will expire.
nbf: If present, the “not before” timestamp will be honored.
We also prescribe a set of private claims to transmit data from the PHA verification server to the exposure notification key server.
tekmac: REQUIRED The HMAC of the TEKs that was presented to the PHA verification server. This must be calculated in a specific way (see below). This is REQUIRED. Base64 encoded string property.
reportType: REQUIRED One of ‘confirmed’, ‘likely’, or ‘negative’ to indicate the diagnosis report type that the verification server is attesting to. At the key server, if no transmission risk values are set, the report type is used to assign transmission risk for compatibility with older apps/clients. This is the only way set reportType on TEKs is through a verification certificate.
symptomOnsetInterval: OPTIONAL uses the same 10 minute interval timing as TEKs use. If an interval is provided that is not the start of a UTC day, then it will be rounded down to the beginning of that UTC day. And from there the days +/- symptom onset will be calculated. Int property.
Standard JWT headers must be provided.
alg: REQUIRED and must be set to
kid: REQUIRED and indicate a specific key ID to use for verification
typ: REQUIRED and must be set to
In order to calculate the HMAC, the application needs to combine all the relevant data from the publish request.
To calculate the HMAC, the device must create the following cleartext string:
key segment contains the following data, period separated:
rolling period start,
rolling period count,
key segments are sorted lexicographically based on the base64 encoding.
As an example:
For newer clients that are not assigning transmission risk values, the 4th segment of the per-TEK segment can be omitted. If this is done, then a value of 0 (zero) must be passed on the publish request at the key server, or the transmission risk must be omitted entirely. That would make the clear text portion look like: