Exposure key export file format and validation guide

This guide shows how to validate Exposure Notifications key server export files that contain diagnosis keys and their schema. This verification ensures they will be accepted and successfully parsed by the Exposure Notifications API.

Prerequisites

To validate Exposure Notifications key server export files, you need the following:

• An understanding of protocol buffers
• Exposure Notifications key server. This is required for uploading and downloading keys. See the documentation in the open source repository for more information.
• The Go language SDK.
• A protoc client. For installation instructions, see Validate schema.
• The Exposure Notifications Android reference design.
• The latest version of Android Studio.
• An Android device with the Exposure Notifications debug mode enabled.
• OpenSSL.
• An export file. See Generating an export if you don't have one yet.

Validate the protocol buffer schema

Follow these steps to ensure that an export file adheres to the correct protocol buffer schema.

1. Install a protoc client, such as the proto-lens client.

2. Clone or download the reference server implementation:

   git clone https://github.com/google/exposure-notifications-server.git

3. In a terminal, navigate to the exposure-notification-server/examples folder.

4. Create a new folder for the verification and navigate into it:

   mkdir verify && cd verify

5. Unzip the export.zip file generated by the server into the folder:

   unzip ../export.zip

6. Run the following command:

   tail +17c < export.bin | protoc --decode TemporaryExposureKeyExport --proto_path ../../internal/pb/export/ export.proto | head -n 10

If the preceding command succeeds, the protocol buffer format is valid. This doesn't necessarily mean the export file is valid, though. Continue to the next section to check the signature on the export file.

If the command doesn't succeed and you're working on new code, review your export generation code. If your app has been working but you start getting errors later, look at your server code for recent updates. For additional testing, you can regenerate a file manually and use that to track down the source of the problem.

For more information on validating schemas, see Inspecting an export.

Verify the signature

After validating the protocol buffer schema in the export file, follow these steps to verify that the signature is valid.

1. Clone or download the reference server implementation:

   git clone https://github.com/google/exposure-notifications-server.git

2. In a terminal, navigate to the exposure-notification-server/examples folder.

3. Create a new folder for the verification and navigate into it:

   mkdir verify && cd verify

4. Unzip the export.zip file generated by the server into the folder:

   unzip ../export.zip

5. Run the following command:

   go run ../../tools/unwrap-signature/ --in=export.sig --out=sigRaw

6. Run the following command:

   openssl dgst -sha256 -verify public.pem -signature sigRaw export.bin

If the response is Verified OK, then the signature is valid. Otherwise, the signature is not valid, which could be due to incorrect signing, or the verification key not being available on the device. Make sure a key was fully rolled out to devices before using it for signing exports, and contact your Google partner to make sure the key was added into our system.

Validate keyfile

Follow these steps to validate that the Temporary Exposure Keys (TEKs) included in the export file satisfy Exposure Notifications requirements.

1. Clone or download the reference server implementation:

   git clone https://github.com/google/exposure-notifications-server.git

2. In a terminal, run the following command:

   go run exposure-notifications-server/tools/export-analyzer --file=path_to_file/export.zip

The preceding command checks the length and rolling period, and outputs a log describing any issues. You can view the different checks at the bottom of this file.

Ongoing monitoring

You should continually validate the server's export files to catch regressions. Ideally, you should build monitoring into the app, and report back errors that may arise in the call to provideDiagnosisKeys(). This way you can ensure that the files downloaded by your app are correctly processed. This can catch bugs in export generation, problems with signatures, and files that are corrupted.

Alternatively or additionally, you can set up an ongoing validation process at the server that directly checks the export files themselves, perhaps immediately after their creation. This can check for some potential known issues, but may not catch the full breadth of potential issues (including, for example, problems retrieving the files).