README

Exposure Notification Reference Key Server

COVID‑19 Exposure Notifications API

Exposure Notification Reference Key Server Documentation

In our continued effort to help governments and health authorities during the COVID-19 pandemic, we have authored an open source reference implementation of an Exposure Notification Key Server.

The server reference in this repository implements the Exposure Notifications API and provides reference code for working with Android and iOS apps that are built by public health authorities. The reference server source code is available on GitHub and can be deployed on any infrastructure or cloud provider selected by a public health authority.

Our hope is by making this privacy-preserving server implementation available to health authorities, we can enable their developers to use the open source code to get started quickly.

Overview

The server is responsible for the following functions:

  • Accepting the temporary exposure keys of affected users from mobile devices.

  • Validating the temporary exposure keys using the device attestation API.

  • Storing the temporary exposure keys 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 temporary exposure keys. After 14 days, or configured time period, the exposure keys can no longer be matched to a device.

Tutorials and reference documentation

You can read tutorials on deploying and using the reference Exposure Notification Key Server here:

Issues and Questions

You can open a GitHub Issue. Please be sure to include as much detail as you can to help aid in addressing your concern. If you wish to reach out privately, you can send an e-mail exposure-notifications-feedback@google.com.

Contributing to this project

Contributions to this project are welcomed. For more information about contributing to this project, see the contribution guidelines.

Directories

Path Synopsis
cmd
admin-console
Package main runs the debugger service.
Package main runs the debugger service.
backup
This package is the service that deletes old exposure keys; it is intended to be invoked over HTTP by Cloud Scheduler.
This package is the service that deletes old exposure keys; it is intended to be invoked over HTTP by Cloud Scheduler.
cleanup-export
This package is the service that deletes old exposure keys; it is intended to be invoked over HTTP by Cloud Scheduler.
This package is the service that deletes old exposure keys; it is intended to be invoked over HTTP by Cloud Scheduler.
cleanup-exposure
This package is the service that deletes old exposure keys; it is intended to be invoked over HTTP by Cloud Scheduler.
This package is the service that deletes old exposure keys; it is intended to be invoked over HTTP by Cloud Scheduler.
debugger
Package main runs the debugger service.
Package main runs the debugger service.
export
This package is the service that publishes infected keys; it is intended to be invoked over HTTP by Cloud Scheduler.
This package is the service that publishes infected keys; it is intended to be invoked over HTTP by Cloud Scheduler.
export-importer
This binary provides a server that can import export files from a trusted partner.
This binary provides a server that can import export files from a trusted partner.
exposure
This package is the primary infected keys upload service.
This package is the primary infected keys upload service.
federationin
This package is the service that pulls federation results from other federation severs.
This package is the service that pulls federation results from other federation severs.
federationout
This package is the gRPC server for federation requests to send data to other federations servers.
This package is the gRPC server for federation requests to send data to other federations servers.
generate
Deployable server to generate fake exposure keys on demand.
Deployable server to generate fake exposure keys on demand.
jwks
This package is the service update encryption keys; it is intended to be invoked over HTTP by Cloud Scheduler.
This package is the service update encryption keys; it is intended to be invoked over HTTP by Cloud Scheduler.
key-rotation
This package is the service rotates revision token encryption keys; it is intended to be invoked over HTTP by Cloud Scheduler.
This package is the service rotates revision token encryption keys; it is intended to be invoked over HTTP by Cloud Scheduler.
mirror
This binary provides a server that can mirror export files.
This binary provides a server that can mirror export files.
pkg
api/v1
Package v1 contains API definitions that can be used outside of this codebase.
Package v1 contains API definitions that can be used outside of this codebase.
api/v1alpha1
Package v1alpha1 contains API definitions that can be used outside of this codebase in their alpha form.
Package v1alpha1 contains API definitions that can be used outside of this codebase in their alpha form.
base64util
Package base64util extracts base64 encoding/decoding logic into a single API that is tolerant of various paddings.
Package base64util extracts base64 encoding/decoding logic into a single API that is tolerant of various paddings.
cache
Package cache implements an inmemory cache for any interface{} object.
Package cache implements an inmemory cache for any interface{} object.
cryptorand
Package cryptorand defines a rand.Source from crypto/rand.
Package cryptorand defines a rand.Source from crypto/rand.
database
Package database is a facade over the data storage layer.
Package database is a facade over the data storage layer.
enkstest
Package enkstest provides test helpers and provisioners.
Package enkstest provides test helpers and provisioners.
errcmp
Package errcmp contins a convince helper for checking error conditions in tests
Package errcmp contins a convince helper for checking error conditions in tests
keys
Package keys defines the interface to and implementation of key management operations.
Package keys defines the interface to and implementation of key management operations.
logging
Package logging sets up and configures logging.
Package logging sets up and configures logging.
observability
Package observability sets up and configures observability tools.
Package observability sets up and configures observability tools.
render
Package render defines rendering functionality.
Package render defines rendering functionality.
secrets
Package secrets defines a minimum abstract interface for a secret manager.
Package secrets defines a minimum abstract interface for a secret manager.
server
Package server provides an opinionated http server.
Package server provides an opinionated http server.
signal
Package signal provides convenance methods for sending interrupt signals to the self process.
Package signal provides convenance methods for sending interrupt signals to the self process.
timeutils
Package timeutils defines functions to close the gaps present in Golang's default implementation of Time.
Package timeutils defines functions to close the gaps present in Golang's default implementation of Time.
util
Package util is a CLI tool for generating test exposure key data.
Package util is a CLI tool for generating test exposure key data.
verification
Package verification provides verification utilities.
Package verification provides verification utilities.
tools
example-verification-signing
This package implements a sample server that implements a piece of the public health authority verification protocol: https://github.com/google/exposure-notifications-server/blob/main/docs/design/verification_protocol.md To call this server using curl: curl -d '{"verificationCode":"fakeCode","tekhmac":"replace w/ tek hmac"}' -H "Content-Type: application/json" -X POST http://localhost:8080/ The FULL protocol is implemented by https://github.com/google/exposure-notifications-verification-server/
This package implements a sample server that implements a piece of the public health authority verification protocol: https://github.com/google/exposure-notifications-server/blob/main/docs/design/verification_protocol.md To call this server using curl: curl -d '{"verificationCode":"fakeCode","tekhmac":"replace w/ tek hmac"}' -H "Content-Type: application/json" -X POST http://localhost:8080/ The FULL protocol is implemented by https://github.com/google/exposure-notifications-verification-server/
export-analyzer
This tool displays the content of the export file.
This tool displays the content of the export file.
export-config
This package is used to create entries in the ExportConfig table.
This package is used to create entries in the ExportConfig table.
export-generate
This utility generates test exports signed with local keys
This utility generates test exports signed with local keys
export-viz
This tool writes a visualization of an export file.
This tool writes a visualization of an export file.
exposure-client
This package is a CLI tool for generating test exposure key data.
This package is a CLI tool for generating test exposure key data.
federationin-query
This package is a CLI tool for creating federationin FederationQuery records.
This package is a CLI tool for creating federationin FederationQuery records.
federationout-authorization
This package is a CLI tool for creating FederationAuthorization entries, controlling who can access the federationout endpoint.
This package is a CLI tool for creating FederationAuthorization entries, controlling who can access the federationout endpoint.
federationout-test
This package is a CLI tool for calling the gRPC federationout server, for manual testing.
This package is a CLI tool for calling the gRPC federationout server, for manual testing.
hmac-calculator
Unmarshals a public JSON message from a file and calculated the HMAC using the server code.
Unmarshals a public JSON message from a file and calculated the HMAC using the server code.
interval
This utility takes an exposure notifications interval number and turns it into a timestamp.
This utility takes an exposure notifications interval number and turns it into a timestamp.
seed
Package main provides a utility that bootstraps the initial database with users and realms.
Package main provides a utility that bootstraps the initial database with users and realms.
sign
This tool attempts to sign a string with all configured export signing keys in the system.
This tool attempts to sign a string with all configured export signing keys in the system.
unwrap-signature
This utility unwraps the export.TEKSignatureList proto and extracts the signature so that an export file can be verified with openssl.
This utility unwraps the export.TEKSignatureList proto and extracts the signature so that an export file can be verified with openssl.
verify
This tool verifies that a SHA256 and signature can be valided by the provided public key.
This tool verifies that a SHA256 and signature can be valided by the provided public key.
internal
admin
Package admin provides a small admin UI.
Package admin provides a small admin UI.
authorizedapp
Package authorizedapp handles allowed applications.
Package authorizedapp handles allowed applications.
authorizedapp/database
Package database is a database interface to authorized apps.
Package database is a database interface to authorized apps.
authorizedapp/model
Package model is a model abstraction of authorized apps.
Package model is a model abstraction of authorized apps.
azurekeyvault
Package azurekeyvault provides shared functionality between the signing and secret clients for KeyVault
Package azurekeyvault provides shared functionality between the signing and secret clients for KeyVault
backup
Package backup implements periodic backups.
Package backup implements periodic backups.
buildinfo
Package buildinfo provides high-level build information injected during build.
Package buildinfo provides high-level build information injected during build.
cleanup
Package cleanup implements the API handlers for running data deletion jobs.
Package cleanup implements the API handlers for running data deletion jobs.
debugger
Package debugger is a server-side debugger component that displays debug information about the system.
Package debugger is a server-side debugger component that displays debug information about the system.
export
Package export defines the handlers for managing exposure key exporting.
Package export defines the handlers for managing exposure key exporting.
export/database
Package database is a database interface to export.
Package database is a database interface to export.
export/model
Package model is a model abstraction of exports.
Package model is a model abstraction of exports.
exportimport
Package exportimport imports export files into the local database Package exportimport implements the handlers for the export-importer functionality.
Package exportimport imports export files into the local database Package exportimport implements the handlers for the export-importer functionality.
exportimport/database
Package database is a database interface for export importing.
Package database is a database interface for export importing.
exportimport/model
Package model is a model abstraction of export import configuration and status.
Package model is a model abstraction of export import configuration and status.
federationin
Package federationin handles pulling data from other federation servers.
Package federationin handles pulling data from other federation servers.
federationin/database
Package database is a database interface to federation in.
Package database is a database interface to federation in.
federationin/model
Package model is a model abstraction of federation in.
Package model is a model abstraction of federation in.
federationout
Package federationout handles requests from other federation servers for data.
Package federationout handles requests from other federation servers for data.
federationout/database
Package database is a database interface to federation out.
Package database is a database interface to federation out.
flag
Package flag includes custom flag parsing logic.
Package flag includes custom flag parsing logic.
generate
Package generate contains HTTP handler for triggering data generation into the databae.
Package generate contains HTTP handler for triggering data generation into the databae.
integration
Package integration defines the integration test.
Package integration defines the integration test.
jsonutil
Package jsonutil provides common utilities for properly handling JSON payloads in HTTP body.
Package jsonutil provides common utilities for properly handling JSON payloads in HTTP body.
jwks
Package jwks manages downloading and updating the keys from a JWKS source for keys.
Package jwks manages downloading and updating the keys from a JWKS source for keys.
keyrotation
Package keyrotation implements the API handlers for running key rotation jobs.
Package keyrotation implements the API handlers for running key rotation jobs.
metrics
Package metrics contains utilities for exporting metrics.
Package metrics contains utilities for exporting metrics.
metrics/metricsware
Package metricsware provides a middleware for recording metrics of different kinds
Package metricsware provides a middleware for recording metrics of different kinds
middleware
Package middleware defines common http middlewares.
Package middleware defines common http middlewares.
mirror
Package mirror implements the export file mirroring job.
Package mirror implements the export file mirroring job.
mirror/database
Package database is a database interface for mirror settings.
Package database is a database interface for mirror settings.
mirror/model
Package model is a model abstraction of mirror data structures.
Package model is a model abstraction of mirror data structures.
pb
project
Package project contains project level utilities that don't have another good home.
Package project contains project level utilities that don't have another good home.
publish
Package publish defines the exposure keys publishing API.
Package publish defines the exposure keys publishing API.
publish/database
Package database is a database interface to publish.
Package database is a database interface to publish.
publish/model
Package model is a model abstraction of publish.
Package model is a model abstraction of publish.
revision
Package revision defines the internal structure of the revision token and utilities for marshal/unmarshal which also encrypts/decrypts the payload.
Package revision defines the internal structure of the revision token and utilities for marshal/unmarshal which also encrypts/decrypts the payload.
revision/database
Package database contains the management of interactions with the database for createion and storage of the wrapped keys that encrypet revision certificates.
Package database contains the management of interactions with the database for createion and storage of the wrapped keys that encrypet revision certificates.
serverenv
Package serverenv defines common parameters for the sever environment.
Package serverenv defines common parameters for the sever environment.
setup
Package setup provides common logic for configuring the various services.
Package setup provides common logic for configuring the various services.
storage
Package storage is an interface over Google Cloud Storage.
Package storage is an interface over Google Cloud Storage.
utils
Package utils provides utilities to be used in testing.
Package utils provides utilities to be used in testing.
verification
Package verification provides the ability to verify the diagnosis certificates (JWTs) coming from public health authorities that are responsible for verifying diagnosis pin codes and certifying the TEKs.
Package verification provides the ability to verify the diagnosis certificates (JWTs) coming from public health authorities that are responsible for verifying diagnosis pin codes and certifying the TEKs.
verification/database
Package database is a database interface to health authorities.
Package database is a database interface to health authorities.
verification/model
Package model is a model abstraction of health authorities.
Package model is a model abstraction of health authorities.