christianjara / dgca-verifier-service

Repository for the dgca verifier service.

EU Digital COVID Certificate Verifier Service

About • Development • Documentation • Support • Contribute • Contributors • Licensing

About

This repository contains the source code of the Digital Green Certificates Verifier Service.

The DGC Verifier Service is part of the national backends and caches the public keys that are distributed through the DGCG. It is accessed by the DGC Verifier Apps (Android, iOS) to update the key store periodically.

Development

Note: The verifier service needs a connection to the gateway in order to run. There is no standalone version available.

Prerequisites

• Open JDK 11
• Maven
• Docker
• An installation of the DGCG
• Keys to access the DGCG via the DGCG Connector of the DGC-lib
• Authenticate to Github Packages

Needed keys for accessing the DGC Gateway

For accessing the DGC Gateway via the DGC Connector you need the following keys in place:

• The public key of the used Gateway. The public key should be stored in the tls_trust_store. If you use one of the provided gateways, you will get the public key as .pem from DIGIT. This .pem needs to be converted into pkcs12 format:

  openssl pkcs12 -export -in pub_tls.pem -name trust -out tls_trust_store.p12
  

• Your key pair for accessing the Gateway stored in tls_key_store. This needs to be generated by yourself and then whitelisted by operations team (see onboarding manual of the Gateway). To use it in the verifier service this needs to be converted as well into pkcs12 format:

  openssl pkcs12 -export -in tls.pem -inkey tls_private.pem -name 1 -out tls_key_store.p12
  

• The public key of the TrustAnchor of the Gateway. If you use one of the provided Gateways you will get it as well, at onboarding. The key should be stored in a jks file.

For more information on how to generate certificates for DGC Gateway and how to run your own local one, please have a look in the documentation of the Gateway.

Authenticating in to GitHub Packages

As some of the required libraries (and/or versions are pinned/available only from GitHub Packages) You need to authenticate to GitHub Packages The following steps need to be followed

• Create PAT with scopes:
  • read:packages for downloading packages

GitHub Maven

• Copy/Augment ~/.m2/settings.xml with the contents of settings.xml present in this repository
  • Replace ${app.packages.username} with your github username
  • Replace ${app.packages.password} with the generated PAT

GitHub Docker Registry

• Run docker login docker.pkg.github.com/eu-digital-green-certificates before running further docker commands.
  • Use your GitHub username as username
  • Use the generated PAT as password

For further information about the keys and certificates needed, please refer to the documentation of the DGCG and the DGC-lib

Build

Whether you cloned or downloaded the 'zipped' sources you will either find the sources in the chosen checkout-directory or get a zip file with the source code, which you can expand to a folder of your choice.

In either case open a terminal pointing to the directory you put the sources in. The local build process is described afterwards depending on the way you choose.

Build with maven

Building this project is done with maven.

• Check settings.xml in the root folder of this git repository as example.
  Copy the servers to your own ~/.m2/settings.xml in order to connect the GitHub repositories we use in our code. Provide your GitHub username and access token (see GitHub Help) under the variables suggested.

• Run the following command from the project root folder

mvn clean install

All required dependencies will be downloaded, the project build and the artifact stored in your local repository.

Run with docker

• Perform maven build as described above
• Place the keys and certificates named above into the certs folder.
• Adjust the values in the docker-compose.yml file to fit the url for the gateway you use and your keys and certificates you have to access it.

  - DGC_GATEWAY_CONNECTOR_ENDPOINT=https://dgc-gateway.example.com
  - DGC_GATEWAY_CONNECTOR_TLSTRUSTSTORE_PATH=file:/ec/prod/app/san/dgc/tls_trust_store.p12
  - DGC_GATEWAY_CONNECTOR_TLSTRUSTSTORE_PASSWORD=dgcg-p4ssw0rd
  - DGC_GATEWAY_CONNECTOR_TLSKEYSTORE_ALIAS=1
  - DGC_GATEWAY_CONNECTOR_TLSKEYSTORE_PATH=file:/ec/prod/app/san/dgc/tls_key_store.p12
  - DGC_GATEWAY_CONNECTOR_TLSKEYSTORE_PASSWORD=dgcg-p4ssw0rd
  - DGC_GATEWAY_CONNECTOR_TRUSTANCHOR_ALIAS=ta
  - DGC_GATEWAY_CONNECTOR_TRUSTANCHOR_PATH=file:/ec/prod/app/san/dgc/trust_anchor.jks
  - DGC_GATEWAY_CONNECTOR_TRUSTANCHOR_PASSWORD=dgcg-p4ssw0rd

Note: Leave the path as is and only change the file names, as the certs folder will be mapped to this folder inside the docker container.

• Run the following command from the project root folder

docker-compose up --build

After all containers have started, you will be able to reach the service on your local machine under port 8080.

Documentation

OpenAPI Spec

Service description

Support and feedback

The following channels are available for discussions, feedback, and support requests:

Type	Channel
Issues
Other requests

How to contribute

Contribution and feedback is 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.

Contributors

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.

Licensing

Copyright (C) 2021 T-Systems International GmbH and all other contributors

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.