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.

Verify that the API accepts file

After validating the schema signature and keyfile, check that the API accepts the file. Although you could do this directly with your app, you can also use the Android reference design as follows:

1. Clone or download the reference server implementation:

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

2. Enable debug mode and configure it to:

   • Bypass app signature check.
   • Enable diagnosis key file signature check.

   • Enable custom diagnosis key file signature fields:

     • Set the public key (the one used to sign the export.bin file).
     • Set the sample package name: com.google.android.apps.exposurenotification.
     • Define the signature_id and signature_version used in export.bin.

3. Use Android Studio to build and run the Android reference design.

4. Download and push the export.zip to test in the device:

   adb push export.zip sdcard/Downloads

5. In the app, click Debug tab > Provide Manually > Provide Keys.

6. In Input Method, select File.

7. Choose the export.zip file in the picker.

8. Click Provide.

If the provided file was successfully parsed, the app shows a toast such as:

Figure 1: Toast showing a successful validation

After the successful parse, the output logs include a message such as:

“I/ExposureNotification: [MatchingTracer] Matching job complete…

If the file was not accepted due to an issue with the signature or format, the app shows a toast such as:

Figure 2: Toast showing a failed validation

There may be cases in which the app accepts the file but the matching does not succeed, revealed when the “Matching job complete” log message isn't present. That can mean one of two things:

• There is an issue in the export file. To address this, analyze the full output, filtering by TAG=ExposureNotification.
• There is an issue found when matching. To address this, capture a bug report and submit a bug.

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).