Exposure Notifications verification server

This topic provides developer guidance for the Exposure Notifications verification server requirements provided by Apple and Google to build Android apps for notifying users of possible exposure to confirmed COVID-19 cases.

High-level verification flow

The following list shows the flow that a verification follows. The circled numbers correspond to points on the diagram in Verification certificate HMAC flow diagram.

  • The case investigation epidemiologist (epi) reaches out to the patient to report a positive test result.
  • The epi requests a Verification Code (VC) using the web interface provided by a verification server (①), which generates the VC and sets the time limit for it, and provides it to the epi (②). Optionally, the epi provides details about the diagnosis that will be associated with the requested VC. This information is stored by the verification server linked to the issued VC. The verification server can later include the diagnosis information in the certificate issued for the Temporary Exposure Keys (TEKs) of the corresponding user.
  • The epi provides the obtained VC to the user over the phone (③) and the user is instructed to enter it into the app. An alternative approach is to send an SMS with a deep link that handles this automatically when tapped; this method is preferred as it is also a verification of the phone number.
  • After the user enters their VC in the app, it contacts the verification server, providing the VC (④).
  • The verification server checks the validity of the VC and whether any diagnosis information was entered when the VC was requested. If the VC is valid, the verification server returns to the app a long-term authentication token, the type of the diagnosis, and a flag which indicates whether diagnosis information was provided with the VC (⑤).
  • When a user who tested positive decides to submit their TEKs to the key server, the user initiates the process in the app.
  • If the flag obtained with the long-term token indicates that no information about the diagnosis was provided, the app prompts the user to answer a series of questions related to onset of symptoms.
  • The user app generates a random HMAC key K and optionally user metadata U-metadata generated from the information gathered in the previous step, and sends the long-term authentication token together with HMAC(K; TEKs || U-metadata) to the verification server, where TEKs are the TEKs that are currently available (this may be all 14 last TEKs, or any number between 0 and 14) (⑥). It does not send the HMAC key K to the verification server. The hash-based message authentication code (HMAC) must be instantiated with HMAC-SHA256.
  • The verification server checks the long-term token, adds its own metadata VS-metadata, which contains information about the diagnosis and the TEK transmission risk scores (these could be computed using also the user metadata). The verification server computes a certificate by signing both HMAC(K; TEKs || U-metadata) and the VS-metadata using a traditional digital signature scheme, and sends back the metadata and the certificate to the user app (⑦). The verification server also sends a token for the next TEK that can be submitted.
  • The user app verifies the validity of the signature in the certificate, and the format of the metadata.
  • When the patient chooses to self-report, the app sends the patient TEKs, the user metadata, the verification server metadata, the HMAC key K, and the certificate to the key server (⑧).
  • The key server computes HMAC(K; TEKs || U-metadata), verifies the signature in the certificate, and then adds the TEKs to the database with a corresponding metadata, which is computed from U-metadata and VS-metadata according to the specific policy in place (⑨). The key server issues the user app a revision token for the submitted TEKs, which can be used to revise (change the report type of) the TEKs later. The revision token is a secret key authenticated encryption of the TEKs under a secret key held by the key server. This can be instantiated with Galois Counter Mode secret key authenticated encryption.
    • The revision token cannot be read outside of the key server and is used only to verify that when a specific TEK has a diagnosis change at a later date, we are ensured that only the same mobile device (that has the revision token) can initiate such a request.
  • For every following TEK that becomes available to the user app if the user consents to be submitted, the app repeats the same steps to submit that key:
    • Contacts the verification server using the next key token in order to obtain a certificate for the key.
    • Submits the last TEK and the certificate to the key server.
    • Obtains a revision token for that key.

Architecture

The ENVS is composed of several related systems. The following sections explain the components.

The verification server

The verification server authenticates the patient and their positive diagnosis and provides the type of diagnosis, timestamp, and other metadata. The app must check this metadata to ensure it does not contain identifiable information (that is, it needs to match one in a list of potential metadata values). Each region will have its own verification server. While it is not required for the functionality, in some settings the verification server will have access to medical databases that contain information about the diagnosis. In some settings, the Public Health Authority (PHA) and the verification server might be the same party.

The following is a list of requirements for the verification server. The server:

  • Issues VCs upon request from a user web portal. The VCs:
    • Must be 8 digits.
    • Must be valid for a limited period of time (such as one hour).
  • Validates that VCs have not been used, are within the time frame of issuance, and originate from the correct server. Users enter validated VCs into the PHA app and the VCs are then returned for verification by the app.
    • Note: The verification server validates only VCs issued by its own process.
  • Issues long-term tokens to partner apps for TEKs held in escrow.
  • Verifies long-term tokens + HMAC(TEKs) returned from mobile app.
  • Issue signed JSON Web Token (JWT) + HMAC(TEKs) + metadata. The metadata fields are:
    • Transmission Risk Level
    • Days since symptom onset
    • Date of test

The PHA mobile app

The PHA mobile app is responsible for providing the VC input user experience and submitting the VC to the verification server for validation. This flow can be started in two ways:

  • A PHA sends the user an SMS with a deep link into the verification flow.
  • The user enters the app to start the flow while speaking to a case manager.

Using the SMS link, the app can interpret if the PHA would like to allow the user to enter additional metadata during the verification flow, such as test date.

The mobile app is responsible for the following functions:

  • Accepting a deep link with additional parameters.
  • Providing a boolean parameter value to indicate whether or not to show a date picker.
  • Accepting an 8-digit VC for verification.
  • Submitting VCs for validation to verification server.
  • Displaying error message if VC does not validate.
  • Prompting user to report a test date, if allowed by PHA.
  • Prompting to share TEKs with app.

The key server

The key server is responsible for accepting, validating, and holding TEKs from positively diagnosed users for distribution to PHA mobile apps designed to use the Exposure Notifications API. Once the apps have received these keys, if there is a corresponding match on a user's device, the app sends a notification to the user to notify them that they have been exposed to a positive COVID-19 case.

The key server is responsible for the following functions:

  • Accepting the TEKs of affected users from mobile devices.
  • Verifying the signature included with the TEKs before accepting them.
  • Storing the metadata with each key.
  • Storing the TEKs in a database.
  • Periodically generating incremental files that will be downloaded by mobile devices to perform the key matching algorithm on the mobile device.
  • Sending a public key to devices and digitally signing the incremental files with a private key.
  • Periodically deleting old TEKs. After 14 days, or configured time period, the TEKs can no longer be matched to a device.

For more information on key servers, see the model app on GitHub and its corresponding documentation.

Verification certificate HMAC flow diagram

The following diagram shows the interaction between the PHA app, test verification server, and key server.

Shows the flow of data between the parts of the
server
Figure 1: Verification certificate HMAC flow diagram

Included metadata

Metadata is included on a per-key basis when the app uploads TEKs to the diagnosis key server. We recommend that the server be able to accept any version of the TEK message in the download format to ensure that clients and protos are forward- and backward-compatible. Refer to the latest exposure notifications server documentation.

The following code shows the per-key metadata supported in server v1.4.1, along with the default value of each field:

message TemporaryExposureKey {
  // Key of infected user
  optional bytes key_data = 1;

  // Varying risk associated with a key depending on diagnosis method
  optional int32 transmission_risk_level = 2;

  // The interval number since epoch for which a key starts
  optional int32 rolling_start_interval_number = 3;

  // Increments of 10 minutes describing how long a key is valid
  optional int32 rolling_period = 4 [default = 144];
}

Verification server design

There are several possibilities for the verification server design and how it interacts with the mobile exposure notification app. For reference, we provide one possible solution.

The diagnosis verification certificates that are issued by the verification server govern which mobile devices are allowed to upload their TEKs and which ones are not. The key server must be configured for individual apps that are allowed to upload and which verification servers they accept certificates from. The issuance of these certificates is the key functionality of the verification server.

The verification certificates are necessary for the uploading of keys to the exposure notifications key server, as that server has no other means of identity-based access control.

For examples of how to issue certificates that the key server will accept, see the reference design source code.

Server components

The verification server consists of two front-end components:

  • A Web UI that public health officials or those they designate will use to input diagnosis parameters (optional) and issue VCs that are provided to users.
  • A JSON-over-HTTP API server that accepts VCs in exchange for a long-term token. The server exchanges the long-term certificate combined with an HMAC of the TEKs for a signed diagnosis verification certificate that can be presented to the key server, along with the actual TEKs for processing.

The verification UI is dependent on an authentication that is used to manage logins. Both front-end components are dependent on a shared database.

The VC-check API also uses a key management service to sign the issued verification certificates.

There should also be a data deletion component that is run on a schedule. The data deletion component is tasked with removing old (used and unused) VC entries and expired long-term token state from the database.


Figure 2: Verification server architecture

Issuing VCs

The Web UI is used by PHA staff to issue a VC for a patient. The UI should be customized to the needs of the local PHA. It is possible to have no customization and to only issue VCs and sign them. In that case, all transmission risk values must be calculated within the mobile exposure notification app, and the role of the verification server is only to certify that data.

When a VC is issued, it needs to be saved to the database along with any transmission risk override parameters specified at the time of issuance. VCs must be set with reasonable, human-scale expiry time (such as 1 hour). All VC implementations may use a check digit in some form, as it helps defend against mistyped VCs and can be used to reduce database load with a quick in-memory check.

When VCs are submitted from the mobile app, the code should be marked as used and a longer-term token should be issued to the mobile device. This token can be valid for a longer period of time (for example, 24 hours). When the user of the app is ready to submit their TEKs to the server, they exchange the long-term token for a verification certificate that can be sent to the server for acceptance of the TEKs. The certificate contains the HMAC of the TEKs the device wishes to submit along with any transmission risk overrides, and is signed with an asymmetric signing key. The key server must know the public key portion of the signing key.

VC validation

When a user enters a VC into their mobile phone, they are initiating the sharing of their TEKs.

The verification server must receive the required information from the VC and the HMAC of the TEK data. The app should not communicate the key for the HMAC to the verification server. The verification server will not know the number of keys being uploaded or the value of the keys.

Upon receipt of this information, the verification server will validate the VC from the database and also mark it as used. It is important to ensure VCs are used only once.

If a VC is valid, the override parameters and metadata are bundled into a JWT according to the verification protocol. The JWT must be signed using the ES256 (ECDSA p256) algorithm. It is important to note that JWTs are signed but not encrypted. They should be transmitted only over secure connections. The public key for the signing key must be communicated to the operator of the key server so that these certificates can be accepted.

Once the JWT is issued, the job of the verification server is done, and the returned JWT is sent by the mobile app to the key server along with the TEKs.

Cleanup

The VC data should be deleted from the database on a regular basis. We recommend deleting data after it has been in the server for 14 days.

Verification protocol

For information on the verification protocol, see Public Health Authority Diagnosis Verification Protocol on GitHub.

JWT verification and accepted claims

The key server will accept this JWT in the current verificationPayload field in the Exposure Notifications API. When this field 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 recalculating the HMAC that was signed by the PHA verification server. The hmackey field must be base64-encoded.

The JWT 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 key server.
  • 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.

The standard header field of kid is used to determine the public key to use at the key server for verifying the verification certificate's signature.

We also require a set of private claims to transmit data from the PHA verification server to the key server:

  • reportType: 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.
  • tekmac: The HMAC of the TEKs that was presented to the PHA verification server. This must be calculated in a specific way, described later in this topic.
  • symptomOnsetInterval: The symptom onset interval indicates when the person whose diagnosis is being verified first experienced symptoms. This is used to populate additional metadata on the assigned TEKs. (optional)

HMAC calculation

To calculate the HMAC, the app needs to combine all the relevant data from the publish request. The key should be at least 128 bits of random data generated on the device. The hash function used must be SHA-256.

To calculate the HMAC, the device must create the following cleartext string: key[,key]

Each key segment contains the following data, period separated: base64(TEK), rolling period start, rolling period count, transmission risk.

The key segments are sorted lexicographically based on the base64 encoding.

The following is an example:

key1.rp1.rpc1.tr1,key2.rp2.rpc2.tr2

For newer clients that are not assigning transmission risk values, you can omit the fourth segment of the per-TEK segment. If you do this, then you must pass a value of 0 (zero) on the publish request at the key server, or you must omit the transmission risk entirerly. That would make the clear text portion look like:

key1.rp1.rpc1,key2.rp2.rpc2

Glossary

  • ECDSA: Elliptic Curve Digital Signature Algorithm
  • epi: Case investigation epidemiologist
  • HMAC: Hash-based message authentication code
  • JWT: JSON Web Token
  • PHA: Public Health Authority
  • TEK: Temporary Exposure Key
  • VC: Verification Code