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.
Install a protoc client, such as the proto-lens client.
Clone or download the reference server implementation:
git clone https://github.com/google/exposure-notifications-server.git
In a terminal, navigate to the
exposure-notification-server/examples
folder.Create a new folder for the verification and navigate into it:
mkdir verify && cd verify
Unzip the
export.zip
file generated by the server into the folder:unzip ../export.zip
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.
Verify the signature
After validating the protocol buffer schema in the export file, follow these steps to verify that the signature is valid.
Clone or download the reference server implementation:
git clone https://github.com/google/exposure-notifications-server.git
In a terminal, navigate to the
exposure-notification-server/examples
folder.Create a new folder for the verification and navigate into it:
mkdir verify && cd verify
Unzip the
export.zip
file generated by the server into the folder:unzip ../export.zip
Run the following command:
go run ../../tools/unwrap-signature/ --in=export.sig --out=sigRaw
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.
Clone or download the reference server implementation:
git clone https://github.com/google/exposure-notifications-server.git
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).