Exposure Notification Reference Key Server

View on GitHub

Getting Started

    How to Deploy
    How to Publish Keys
    How to Download Keys
    Estimating the Cost of Deployment

Design

    Server Deployment Options
    Server Functional Requirements
    Verification Protocol Design
    API Definitions

Google Exposure Notification Key Server

Functional requirements

This documents the functional requirements for building a decentralized exposure notification system. For deployment strategies, see Server Deployment Options.

System Components

The Exposure Notification Key Server’s architecture has been split into components. The following diagram shows the relationship between the different components:

A diagram showing the Exposure Notification Key Server components and their relationship

The server components are responsible for the following functions:

Publishing temporary exposure keys

Before reporting temporary exposure keys to the exposure notifications key server, a diagnosis must first verified by a diagnosis verification server. The diagnosis verification server is intentionally separate from the exposure notifications server. The verification server is run by a local government or public health authority. The exposure notification key server is responsible for validating these certificates.

When a user reports a diagnosis, it is reported using the publish API server. In the reference server implementation, the data is encoded in JSON and sent over HTTPS, however you can use any encoding and protocol. None of the data stored in the database is personally identifiable information (PII).

A given mobile application and server pair could agree upon additional information to be shared. The information described in this section is the minimum required set in order to validate the uploads and to generate the necessary client batches for ingestion into the device for key matching.

We have provides a sample API in exposure_types.go.

Minimum required fields, followed by a JSON example:

The following snippet is an example POST request payload in JSON format.

{
  "temporaryExposureKeys": [
    {"key": "base64 KEY1 (16 bytes)", "rollingStartNumber": 12345, "rollingPeriod": 144, "transmissionRisk": 5},
    {"key": "base64 KEY2 (16 bytes)", "rollingStartNumber": 12489, "rollingPeriod": 10, "transmissionRisk": 6},
    {"key": "base64 KEYN (16 bytes)", "rollingStartNumber": 12499, "rollingPeriod": 100, "transmissionRisk": 7}],
  "healthAuthorityID": "gov.state.doh",
  "verificationPayload": "signed JWT issued by public health authority",
  "hmackey": "base64 encoded HMAC key used in preparing the data for the verification server",
  "symptomOnsetInterval": 12345,
  "revisionToken": "empty or result of previous publish"
  "padding": "random string data..."
}

The publish request should respond with a structure described in exposure_types.go.

The revision token is a critical piece of ensuring that revised keys that ensures that a different device cannot revise a previously uploaded key. We have a reference implementation in the revision package.

{
  "revisionToken": "oaque token that needs to be sent on future publish.",
  "insertedExposures": 14,
  "error": "omitted, or error message",
  "code": "omitted or standard error code",
  "padding": "padding to normalize response size"
}

Requirements and recommendations

Batch creation and publishing

You should schedule a script that generates files for download over the HTTPS protocol to client devices. The generation of these files are a regular and frequent operation (batches should be generated at least once a day), we recommend that you generate the files in a single operation rather than on-demand, and distribute the files using a CDN.

For information on the format of the batch file, see Exposure Key Export File Format and Verification and Working with Export Files.

The batch file generation should be per-region, incremental feeds of new data. While additional data can be included in the downloads, there is a minimum set that is required by the exposure notification API, which is relayed from affected users in an unmodified form.

The device operating system and libraries will use the known public key to verify an attached data signature before loading the data. To make the data verifiable:

Important: The matching algorithm only runs on data that has been verified with the public key distributed by the device configuration mechanism.

The app on the device must know which files to download. We recommend that a consistent index file is used so that a client would download that index file to discover any new, unprocessed batches.

If you are using a CDN to distribute these files, ensure that the cache control expiration is set so that the file is refreshed frequently for distribution.

Managing secrets

The use of a secure secret manager (for example, Hashicorp, Key Vault, Cloud Secret) or a hardened on-premises equivalent is required to store the following data:

Data Deletion

Since devices will only be retaining the temporary exposure keys for a limited time (a configurable number of days), we recommend:

You should design your database to accommodate bulk deletion due to abuse, broken apps, human error, or incorrect lab results.

Edit this page