The backend implementation for DP3T
This project is licensed under the terms of the MPL 2 license. See the LICENSE file.
For an example project using the SDK look at the Swiss contact tracing app SwissCovid.
The Decentralised Privacy-Preserving Proximity Tracing (DP3T) project is an open protocol for COVID-19 proximity tracing using Bluetooth Low Energy functionality on mobile devices, which ensures that personal data and computation stay entirely on an individual's phone. It was produced by a core team of over 25 scientists and academic researchers from across Europe. It has also been scrutinized and improved by the wider community.
DP3T is a free-standing effort, begun at the EPFL and ETHZ, where the protocol was produced and where the implementation into an open-sourced app and server is taking place.
Please read the Contribution Guide before submitting any pull-request.
This documentation describes the backend used for the SwissCovid application. It is focused on providing information for the requests used for the Exposure Notification framework. Although, code of the old format is still provided, no documentation or support is available except the code itself.
Since multiple countries are now using the Exposure Notifications Framework, the European Union started an effort to allow federation of keys coming from multiple countries. Every country connected to the gateway can then up- and download keys from all participating countries (relayed via the gateway). This means that people e.g. using the Swiss app in Germany can, if they decide to share their keys with Germany, infect people using the German app and vice versa.
For this another module was added, which periodically synchronizes keys, which are marked for sharing to a gateway service. The official European Federation Gateway Service (EFGS) can be found here. The Swiss fork adds Postgres-Support as well as some other minor features.
Further information on the Interoperability Module can be found in the dpppt-backend-sdk-interops module
In order to have reproducible builds the io.github.zlika maven plugin is used. It replaces all timestamp with the timestamp of the last commit, and orders the entries in the JAR alphabetically. The github action then computes the sha256sum of the resulting JAR and adds the output as an build artifact.
For development purposes an hsqldb can be used to run the web service locally. For production systems, it is recommended to connect to a PostgreSQL database (cluster if possible).
The keys that are stored in the database contain the GAEN key data as specified by Google/Apple, as well as some more fields to indicate the origin of the keys, and if the keys should be shared with a federation gateway. For the federation gateway a further field batch_tag is needed to indicate the batch this key has been uploaded with.
| Column | Description |
|---|---|
| pk_exposed_id | Primary key, autogenerated |
| key | The tek, as Base64 HEX string |
| rolling_start_number | Tek rolling start number, 10-minute interval since UTC epoch |
| rolling_period | Tek rolling period, number of 10-minute intervals that a key is valid for |
| received_at | Rounded timestamp the tek was received, |
| report_type | The reportType indicating how the person uploading the key was "verified" (e.g. confirmed test) |
| days_since_onset_of_symptoms | c.f. Interops documentation |
| origin | String where this key was retrieved from ISO-3166-1-Alpha-2 |
| batch_tag | If uploaded to EFGS, indicates the batchTag of the batch this key was uploaded with |
| share_with_federation_gateway | Indicate if this key should be shared with the federation gateway |
This schema contains the uuid field to be stored temporarily. This is used to prevent replay attacks of the same token twice and the entry will be removed, after the validity of the token has been expired.
| Column | Description |
|---|---|
| pk_redeem_uuid_id | Primary key, autogenerated |
| uuid | UUID from JWD token |
| received_at | Rounded timestamp the token was received |
To allow a monitoring of uploads to a federation gateway, this table holds log entries indicating different actions and error messages.
| Column | Description |
|---|---|
| pk_federation_sync_log_id | |
| gateway | Which gateway the log originated from |
| action | The action associated with the entry (UPLOAD |
| batch_tag | The batchTag associated with the batch the message was generated for |
| upload_date | The date the batch was uploaded (the parameter given for the API call to the gateway) |
| start_time | When the action started. (end - start = duration) |
| end_time | When the action ended. (end - start = duration) |
| state | If the action was successful (ERROR |
To control different behaviors, SpringBoot profiles are used. The idea is to provide an abstract base class, which defines everything needed. Such properties can be defined as abstract, and their implementation can be provided in an extended class.
Currently three non-abstract configs (dev, test, abn and prod) are provided, which are used in the current deployed version of the backend. Those are the CloudConfigs and they are optimized to work with an environment using KeyCloak and CloudFoundry.
Furthermore, two non-abstract configs (dev, prod) are provided, which implement a basic configuration, and which should work out-of-the-box. It generates new key pairs, used to sign the payload, each time the web service is started. For an example on how to persist the keys across startup, have a look at the cloud configs.
Note that the
devconfig uses a HSQLDB, which is non-persistent, whereasprodneeds a running instance of PostgreSQL (either in a docker or native).
If you plan to provide new extensions or make adjustments and want to provide those to the general public, it is recommended to add a new configuration for your specific case. This can be e.g. an abstract class (e.g. WSCloudBaseConfig), which extends the base class providing certain needed keys or functions. If you provide an abstract class, please make sure to add at least one non-abstract class showing the implementation needed.
There is also a possible extension to the base web service provided. The JWT config is intended to implement a possibility to authorize the post requests used to publish the secret keys from the clients. JWTs, which are signed by a health authority, are used. An interface is provided, which can be used to define the behavior of authorization (c.f. the ValidateRequest class and its implementation in NoValidateRequest and JWTValidator).
Since a client has to send its keys to the backend, it would be possible to filter traffic based on post requests to the backend, in order to find out, which IP addresses are "infected". To minimize such a risk clients will send a fake request, where the time delay is based on a Poisson distribution.
In order to minimize the risk of timing attacks, to find out whether a request was fake or not, a time-delay of 1.5s is introduced for the POST request.
Clients pad the number of keys with fake keys, if not enough keys are provided by the framework (e.g. the app is installed for less than 14 days). On fake keys the web-service should not validate any dates. The key payload though needs to be the exact same size!
We started with the project before Google and Apple announced the Exposure Notifications. For some time we supported both the old DP3T protocol and the new GAEN protocol, which is based on DP3T. Now that GAEN has become available on most of the versions, we removed DP3T support in the backend to lower the attack surface and make development easier.
Since the Exposure Notifications format has been adopted, we drop support for legacy notifications. Currently no feature-requests are implemented for the old format, but if a PR is provided, it can still be merged.
By default, the legacy controller (DPPPTController) uses the base url /v1/.
Here an implementation for the Exposure Notification Library by Google and Apple is provided.
By default, the EN controller (GaenController) uses the base url /v1/gaen/.
The web-service provides three endpoints, which map the Exposure Notification specifications.
/v1/gaen/exposed: POST Send a list of infected keys. If a JWT is used to authorize the request, send a JWT back to authorize the call of the following day. If the request as a whole is a "fake"-request, meaning the JWT has the "fake" claim set to "1", no keys are inserted.
/v1/gaen/exposednextday: POST Since the EN framework won't give the key of the current day, the upload has to be split into two. This endpoint receives the key of the last day. This endpoint eventually will be removed, as soon as the EN framework is adjusted. If JWT are activated, this endpoint ne
No open issues yet, or sync has not completed.