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:
- Overview
- Deployment Guide
- Reference Documentation
- Server Functional Requirements
- Server Deployment Options
- API Definitions
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
|
|
|
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. |
|
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. |
|
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. |
|
internal
|
|
|
admin
Package admin provides a small admin UI.
|
Package admin provides a small admin UI. |
|
admin/authorizedapps
Package authorizedapps is part of the admin system.
|
Package authorizedapps is part of the admin system. |
|
admin/exports
Package exports is part of the admin system.
|
Package exports is part of the admin system. |
|
admin/healthauthority
Package healthauthority is part of the admin system.
|
Package healthauthority is part of the admin system. |
|
admin/index
Package index contains admin console indexHandler for the main landing page.
|
Package index contains admin console indexHandler for the main landing page. |
|
admin/siginfo
Package siginfo is part of the admin system.
|
Package siginfo is part of the admin system. |
|
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 |
|
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. |
|
database
Package database is a facade over the data storage layer.
|
Package database is a facade over the data storage layer. |
|
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. |
|
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 contains EN Server integration tests.
|
Package integration contains EN Server integration tests. |
|
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. |
|
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/cleanup
Package cleanup contains OpenCensus metrics and views for cleanup operations
|
Package cleanup contains OpenCensus metrics and views for cleanup operations |
|
metrics/export
Package export contains OpenCensus metrics and views for export operations
|
Package export contains OpenCensus metrics and views for export operations |
|
metrics/federationin
Package federationin contains OpenCensus metrics and views for federationin operations
|
Package federationin contains OpenCensus metrics and views for federationin operations |
|
metrics/federationout
Package federationout contains OpenCensus metrics and views for federationout operations
|
Package federationout contains OpenCensus metrics and views for federationout operations |
|
metrics/metricsware
Package metricsware provides a middleware for recording metrics of different kinds
|
Package metricsware provides a middleware for recording metrics of different kinds |
|
metrics/publish
Package publish contains OpenCensus metrics and views for publish operations
|
Package publish contains OpenCensus metrics and views for publish operations |
|
metrics/rotate
Package rotate contains OpenCensus metrics and views for rotate operations
|
Package rotate contains OpenCensus metrics and views for rotate operations |
|
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 ceritfying 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 ceritfying 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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
testing
|
|
|
enclient
Package enclient is a client for making requests against the exposure notification server.
|
Package enclient is a client for making requests against the exposure notification server. |
|
tools
|
|
|
admin-console
This tool provides a small admin UI.
|
This tool provides a small admin UI. |
|
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 |
|
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. |
|
sign
This tool attempts to sign a string with all configurd export signing keys in the system.
|
This tool attempts to sign a string with all configurd 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. |
Click to show internal directories.
Click to hide internal directories.