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:
-
Authenticates and authorizes humans using Firebase authentication.
-
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.
-
-
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.
-
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
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.
-
Firebase authentication for login.
More resources
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
add-realm
Adds a new realm.
|
Adds a new realm. |
|
add-users
Adds a user or enables that user if they record already exists
|
Adds a user or enables that user if they record already exists |
|
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. |
|
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. |
|
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. |
|
migrate
A binary for running database migrations
|
A binary for running database migrations |
|
docs
|
|
|
images/architecture
Module
|
|
|
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 provides functions for invoking the APIs of the verification server
|
Package clients provides functions for invoking the APIs of the verification server |
|
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/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/codestatus
Package codestatus defines a web controller for the code status page of the verification server.
|
Package codestatus 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/home
Package home defines a web controller for the home page of the verification server.
|
Package home defines a web controller for the home page of the verification server. |
|
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/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/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. |
|
jsonclient
Package jsonclient is a simple JSON over HTTP Client.
|
Package jsonclient is a simple JSON over HTTP Client. |
|
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. |
|
otp
Package otp contains the implementation of the issuance of verification codes.
|
Package otp contains the implementation of the issuance of verification codes. |
|
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. |
|
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. |
|
tools
|
|
|
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. |
|
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. |