exposure-notifications-verification-server

module
v0.19.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 8, 2021 License: Apache-2.0

README

Exposure Notifications Verification Server

This is a reference implementation for an Exposure Notifications verification server, part of the broader Google Exposure Notifications system.

About the Server

This server follows the high level flow for a verification system:

  1. Authenticates and authorizes humans using Identity Platform.

  2. Provides a web interface for epidemiologists (epi) to enter test parameters (e.g. status + test date) to issue a verification code.

    • Short verification codes are typically 6-10 numeric digits and can be read over the phone to a patient. They expire quickly, usually in less than one hour.

    • Longer verification codes can be sent directly to the patient via SMS. These codes generally last longer, like 24 hours.

  3. Provides a JSON-over-HTTP API for exchanging the verification code for a verification token. This API is called by the patient's device.

    • Verification tokens are signed JWTs with a configurable validity period.

  4. Provides a JSON-over-HTTP API for exchanging the verification token for a verification certificate. This API call also requires an HMAC of the Temporary Exposure Key (TEK) data+metatata. This HMAC value is signed by the verification server to be later accepted by an exposure notifications server. This same TEK data used to generate the HMAC here, must be passed to the exposure notifications server, otherwise the request will be rejected.

    • Please see the documentation for the HMAC Calculation

    • The Verification Certificate is also a JWT

Architecture diagram

Verification Flow

Architecture details

  • This application is comprised of the following services which are designed to be serverless and scale independently:

    • cmd/server - Web UI for creating verification codes

    • cmd/apiserver - Server for mobile device applications to do verification

    • cmd/adminapi - (optional) Server for connecting existing PHA applications to the verification system.

    • cmd/cleanup - Server for cleaning up old data. Required in order to recycle and reuse verification codes over a longer period of time.

  • PostgreSQL database for shared state. Other databases may work, but we only aim to support Postgres at this time.

  • Redis for caching and distributed rate limiting.

  • Identity Platform for login.

More resources

Directories

Path Synopsis
cmd
adminapi
This server implements the admin facing APIs for issuing diagnosis codes and checking the status of previously issued codes.
 This server implements the admin facing APIs for issuing diagnosis codes and checking the status of previously issued codes.
apiserver
This server implements the device facing APIs for exchanging verification codes for tokens and tokens for certificates.
 This server implements the device facing APIs for exchanging verification codes for tokens and tokens for certificates.
appsync
This server syncs the published list of mobile apps to this server's db.
 This server syncs the published list of mobile apps to this server's db.
cleanup
This server implements the database cleanup.
 This server implements the database cleanup.
e2e-runner
This server is a simple webserver that triggers the e2e-test binary.
 This server is a simple webserver that triggers the e2e-test binary.
enx-redirect
migrate
A binary for running database migrations
 A binary for running database migrations
modeler
This server builds or re-builds the statistical models for predicting the future number of codes a realm with generate for abuse prevention.
 This server builds or re-builds the statistical models for predicting the future number of codes a realm with generate for abuse prevention.
server
docs
images/architecture Module
internal
auth
Package auth exposes interfaces for various auth methods.
 Package auth exposes interfaces for various auth methods.
browser
Package browser provides helpers for writing integration tests that interact with the browser.
 Package browser provides helpers for writing integration tests that interact with the browser.
clients
Package clients defines API clients for interacting with select APIs.
 Package clients defines API clients for interacting with select APIs.
envstest
Package envstest defines global test helpers for the entire project.
 Package envstest defines global test helpers for the entire project.
firebase
Package firebase is common logic and handling around firebase.
 Package firebase is common logic and handling around firebase.
i18n
Package i18n defines internationalization and localization.
 Package i18n defines internationalization and localization.
icsv
Package icsv defines an interface for things that can export as CSV.
 Package icsv defines an interface for things that can export as CSV.
project
Package project defines global project helpers.
 Package project defines global project helpers.
routes
Package routes defines the routing for services.
 Package routes defines the routing for services.
pkg
api
Package api defines the JSON-RPC API between the browser and the server as well as between mobile devices and the server.
 Package api defines the JSON-RPC API between the browser and the server as well as between mobile devices and the server.
buildinfo
Package buildinfo provides high-level build information injected during build.
 Package buildinfo provides high-level build information injected during build.
cache
Package cache implements an caches for objects.
 Package cache implements an caches for objects.
clients
Package clients defines e2e clients.
 Package clients defines e2e clients.
config
Package config defines the environment baased configuration for this project.
 Package config defines the environment baased configuration for this project.
controller
Package controller defines common utilities used by web and API controllers.
 Package controller defines common utilities used by web and API controllers.
controller/admin
Package admin contains controllers for system wide administrative actions.
 Package admin contains controllers for system wide administrative actions.
controller/apikey
Package apikey contains web controllers for listing and adding API Keys.
 Package apikey contains web controllers for listing and adding API Keys.
controller/appsync
Package appsync syncs the published list of mobile apps to this server's db.
 Package appsync syncs the published list of mobile apps to this server's db.
controller/associated
Package associated handles the iOS and Android associated app handler protocols.
 Package associated handles the iOS and Android associated app handler protocols.
controller/certapi
Package certapi implements the token + TEK verification API.
 Package certapi implements the token + TEK verification API.
controller/cleanup
Package cleanup implements periodic data deletion.
 Package cleanup implements periodic data deletion.
controller/codes
Package codes defines a web controller for the code status page of the verification server.
 Package codes defines a web controller for the code status page of the verification server.
controller/flash
Package flash implements flash messages.
 Package flash implements flash messages.
controller/issueapi
Package issueapi implements the API handler for taking a code request, assigning an OTP, saving it to the database and returning the result.
 Package issueapi implements the API handler for taking a code request, assigning an OTP, saving it to the database and returning the result.
controller/jwks
Package jwks handles returning JSON encoded information about the server's encryptionn keys.
 Package jwks handles returning JSON encoded information about the server's encryptionn keys.
controller/login
Package login defines the controller for the login page.
 Package login defines the controller for the login page.
controller/middleware
Package middleware contains application specific gin middleware functions.
 Package middleware contains application specific gin middleware functions.
controller/mobileapps
Package mobileapps contains web controllers for listing and adding mobile apps.
 Package mobileapps contains web controllers for listing and adding mobile apps.
controller/modeler
Package modeler implements periodic statistical calculations.
 Package modeler implements periodic statistical calculations.
controller/realmadmin
Package realmadmin contains web controllers for changing realm settings.
 Package realmadmin contains web controllers for changing realm settings.
controller/realmkeys
Package realmkeys contains web controllers for realm certificate key management.
 Package realmkeys contains web controllers for realm certificate key management.
controller/redirect
Package redirect defines the controller for the deep link redirector.
 Package redirect defines the controller for the deep link redirector.
controller/stats
Package stats produces statistics.
 Package stats produces statistics.
controller/user
Package user contains web controllers for listing and adding users.
 Package user contains web controllers for listing and adding users.
controller/verifyapi
Package verifyapi implements the exchange of the verification code (short term token) for a long term token that can be used to get a verification certification to send to the key server.
 Package verifyapi implements the exchange of the verification code (short term token) for a long term token that can be used to get a verification certification to send to the key server.
database
Package database manages database connections and ORM integration.
 Package database manages database connections and ORM integration.
digest
Package digest includes common digest helpers
 Package digest includes common digest helpers
email
Package email is logic for sending email invitations Package email is logic for sending email invitations
 Package email is logic for sending email invitations Package email is logic for sending email invitations
jwthelper
Package jwthelper implements some common methods on top of the JWT library.
 Package jwthelper implements some common methods on top of the JWT library.
keyutils
Package keyutils provides helpers for working with ECDSA public keys.
 Package keyutils provides helpers for working with ECDSA public keys.
observability
Package observability provides tools for working with open census.
 Package observability provides tools for working with open census.
pagination
Package pagination defines pagination helpers.
 Package pagination defines pagination helpers.
ratelimit
Package ratelimit defines common rate limiting logic and config.
 Package ratelimit defines common rate limiting logic and config.
ratelimit/limitware
Package limitware provides middleware for rate limiting HTTP handlers.
 Package limitware provides middleware for rate limiting HTTP handlers.
rbac
Package rbac implements authorization.
 Package rbac implements authorization.
redis
Package redis defines redis-specific configurations.
 Package redis defines redis-specific configurations.
render
Package render defines rendering functionality.
 Package render defines rendering functionality.
sms
Package sms defines interfaces for sending SMS text messages.
 Package sms defines interfaces for sending SMS text messages.
testsuite
Package testsuite includes helpers for building a testsuite.
 Package testsuite includes helpers for building a testsuite.
tools
e2e-test
gen-keys
Utility for creating keys using the Key Manager.
 Utility for creating keys using the Key Manager.
gen-secret
Small uiliity to generate random bytes and store them as secrets in Google Secret Manager.
 Small uiliity to generate random bytes and store them as secrets in Google Secret Manager.
get-certificate
Exchanges a verification token for a verification certificate (step 2).
 Exchanges a verification token for a verification certificate (step 2).
get-code
Exchanges a verification code for a verification token.
 Exchanges a verification code for a verification token.
get-token
Exchanges a verification code for a verification token.
 Exchanges a verification code for a verification token.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.