Development • Service APIs • Documentation • Support • Contribute • Contributors • Repositories • Licensing
The goal of this project is to develop the official Corona-Warn-App for Germany based on the exposure notification API from Apple and Google. The apps (for both iOS and Android) use Bluetooth technology to exchange anonymous encrypted data with other mobile phones (on which the app is also installed) in the vicinity of an app user's phone. The data is stored locally on each user's device, preventing authorities or other parties from accessing or controlling the data. This repository contains the implementation of the server for encryption keys for the Corona-Warn-App.
In this documentation, Corona-Warn-App services are also referred to as CWA services.
You can find the architecture overview here, which will give you a good starting point in how the backend services interact with other services, and what purpose they serve.
After you've checked out this repository, you can run the application in one of the following ways:
- As a Docker-based deployment on your local machine. You can run either:
- Single components using the respective Dockerfile or
- The full backend using the Docker Compose (which is considered the most convenient way)
- As a Maven-based build on your local machine. If you want to develop something in a single component, this approach is preferable.
If you want to use Docker-based deployment, you need to install Docker on your local machine. For more information about downloading and installing Docker, see the official Docker documentation.
For your convenience, a full setup including the generation of test data has been prepared using Docker Compose. To build the backend services, run docker-compose build in the repository's root directory. A default configuration file can be found under .env in the root folder of the repository. The default values for the local Postgres and Zenko Cloudserver should be changed in this file before docker-compose is run.
Once the services are built, you can start the whole backend using docker-compose up.
The distribution service runs once and then finishes. If you want to trigger additional distribution runs, run docker-compose run distribution.
The docker-compose contains the following services:
| Service | Description | Endpoint and Default Credentials |
|---|---|---|
| submission | The Corona-Warn-App submission service | http://localhost:8000 http://localhost:8006 (for actuator endpoint) |
| distribution | The Corona-Warn-App distribution service | NO ENDPOINT |
| postgres | A postgres database installation | localhost:8001 postgres:5432 (from containerized pgadmin) Username: postgres Password: postgres |
| pgadmin | A pgadmin installation for the postgres database | http://localhost:8002 Username: [email protected] Password: password |
| cloudserver | Zenko CloudServer is a S3-compliant object store | http://localhost:8003/ Access key: accessKey1 Secret key: verySecretKey1 |
| verification-fake | A very simple fake implementation for the tan verification. | http://localhost:8004/version/v1/tan/verify The only valid tan is edc07f08-a1aa-11ea-bb37-0242ac130002. |
In rare cases the docker-compose runs into a timing issue if the distribution service starts before the bucket of the objectstore was created. This is not a big issue as you can simply run docker-compose run distribution to trigger additional distribution runs after the objectstore was initialized.
If you would like to build and run a single CWA service, it's considered easiest to run them in a Docker environment. You can do this using the script provided in the respective CWA service directory. The Docker script first builds the CWA service and then creates an image for the runtime, which means that there are no additional dependencies for you to install.
To build and run the distribution service, run the following command:
./services/distribution/build_and_run.shTo build and run the submission service, run the following command:
./services/submission/build_and_run.shThe submission service is available on localhost:8080.
If you want to actively develop in one of the CWA services, the Maven-based runtime is most suitable. To prepare your machine to run the CWA project locally, we recommend that you first ensure that you've installed the following:
- Minimum JDK Version 11: OpenJDK / SapMachine
- Maven 3.6
- Postgres
- Zenko CloudServer
If you are already running a local Postgres, you need to create a database cwa and run the following setup scripts:
- Create the different CWA roles first by executing create-roles.sql.
- Create local database users for the specific roles by running create-users.sql.
- It is recommended to also run enable-test-data-docker-compose.sql
, which enables the test data generation profile. If you already had CWA running before and an existing
diagnosis-keytable on your database, you need to run enable-test-data.sql instead.
You can also use docker-compose to start Postgres and Zenko. If you do that, you have to
set the following environment-variables when running the Spring project:
For the distribution module:
POSTGRESQL_SERVICE_PORT=8001
VAULT_FILESIGNING_SECRET=</path/to/your/private_key>
SPRING_PROFILES_ACTIVE=signature-dev,disable-ssl-client-postgresFor the submission module:
POSTGRESQL_SERVICE_PORT=8001
SPRING_PROFILES_ACTIVE=disable-ssl-server,disable-ssl-client-postgres,disable-ssl-client-verification,disable-ssl-client-verification-verify-hostnameAfter you made sure that the specified dependencies are running, configure them in the respective configuration files.
- Configure the Postgres connection in the submission config and in the distribution config
- Configure the S3 compatible object storage in the distribution config
- Configure the private key for the distribution service, the path need to be prefixed with
file:VAULT_FILESIGNING_SECRETshould be the path to the private key, example available in<repo-root>/docker-compose-test-secrets/private.pem
After you've checked out the repository, to build the project, run mvn install in your base directory.
Navigate to the service you want to start and run the spring-boot:run target. The configured Postgres and the configured S3 compliant object storage are used as default. When you start the submission service, the endpoint is available on your local port 8080.
If you want to start the submission service, for example, you start it as follows:
cd services/submission/
mvn spring-boot:runTo enable the DEBUG log level, you can run the application using the Spring dev profile.
mvn spring-boot:run -Dspring.profiles.active=devTo be able to set breakpoints (e.g. in IntelliJ), it may be necessary to use the -Dspring-boot.run.fork=false parameter.
The API that is being exposed by the backend services is documented in an OpenAPI specification. The specification files are available at the following locations:
| Service | OpenAPI Specification |
|---|---|
| Submission Service | services/submission/api_v1.json |
| Distribution Service | services/distribution/api_v1.json |
| Profile | Effect |
|---|---|
dev |
Turns the log level to DEBUG. |
cloud |
Removes default values for the datasource and objectstore configurations. |
demo |
Includes incomplete days and hours into the distribution run, thus creating aggregates for the current day and the current hour (and including both in the respective indices). When running multiple distributions in one hour with this profile, the date aggregate for today and the hours aggregate for the current hour will be updated and overwritten. This profile also turns off the expiry policy (Keys must be expired for at least 2 hours before distribution) and the shifting policy (there must be at least 140 keys in a distribution). |
testdata |
Causes test data to be inserted into the database before each distribution run. By default, around 1000 random diagnosis keys will be generated per hour. If there are no diagnosis keys in the database yet, random keys will be generated for every hour from the beginning of the retention period (14 days ago at 00:00 UTC) until one hour before the present hour. If there are already keys in the database, the random keys will be generated for every hour from the latest diagnosis key in the database (by submission timestamp) until one hour before the present hour (or none at all, if the latest diagnosis key in the database was submitted one hour ago or later). |
signature-dev |
Sets the app package ID in the export packages' signature info to de.rki.coronawarnapp-dev so that the non-productive/test public key will be used for client-side validation. |
signature-prod |
Sets the app package ID in the export packages' signature info to de.rki.coronawarnapp so that the productive public key will be used for client-side validation. |
disable-ssl-client-postgres |
Disables SSL for the connection to the postgres database. |
| Profile | Effect |
|---|---|
dev |
Turns the log level to DEBUG. |
cloud |
Removes default values for the datasource configuration. |
disable-ssl-server |
Disables SSL for the submission endpoint. |
disable-ssl-client-postgres |
Disables SSL with a pinned certificate for the connection to the postgres database. |
disable-ssl-client-verification |
Disables SSL with a pinned certificate for the connection to the verification server. |
disable-ssl-client-verification-verify-hostname |
Disables the verification of the SSL hostname for the connection to the verification server. |
The full documentation for the Corona-Warn-App can be found in the cwa-documentation repository. The documentation repository contains technical documents, architecture information, and whitepapers related to this implementation.
The following channels are available for discussions, feedback, and support requests:
| Type | Channel |
|---|---|
| General Discussion |  |
| Concept Feedback |  |
| Backend Issue |  |
| Other Requests |  |
Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines. By participating in this project, you agree to abide by its Code of Conduct at all times.
The German government has asked SAP and Deutsche Telekom to develop the Corona-Warn-App for Germany as open source software. Deutsche Telekom is providing the network and mobile technology and will operate and run the backend for the app in a safe, scalable and stable manner. SAP is responsible for the app development, its framework and the underlying platform. Therefore, development teams of SAP and Deutsche Telekom are contributing to this project. At the same time our commitment to open source means that we are enabling -in fact encouraging- all interested parties to contribute and become part of its developer community.
The following public repositories are currently available for the Corona-Warn-App:
| Repository | Description |
|---|---|
| cwa-documentation | Project overview, general documentation, and white papers |
| cwa-server | Backend implementation for the Apple/Google exposure notification API |
| cwa-verification-server | Backend implementation of the verification process |
Copyright (c) 2020 SAP SE or an SAP affiliate company.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE for the specific language governing permissions and limitations under the License.