Open Covid Certificate Validator

This an open source API to validate EU Digital COVID Certificates. It receives a COVID certificate and validates it using a list of signing certificates provided by an EU member state.

The server provides a simple JSON-API that returns validation result and the data stored inside a certificate. There is also a simple web frontend to test the service.

There is a basic demo available at

https://covid.merlinschumacher.de/

The demo neither logs IP addresses nor stores any COVID certificate data.

NOTICE: THIS IS NOT AN OFFICIAL VALIDATOR! IT COMES WITHOUT ANY WARRANTIES!

Getting started

The easiest way to run OCCV is to use a container. An up to date docker image is provided via GitHubs Container Image Registry under ghcr.io/merlinschumacher/open-covid-certificate-validator:main.

To start the container you need a recent version of Docker and docker-compose. Just execute docker-compose up and the server will answer on port 8000 of your server. Modify the compose file to fit your needs. Currently only validation against the German list of certificates provided by Ubirch and the Austrian list of certificates is supported. But this should be able to validate all certificates issued in the EU. The certificates are updated every 24 hours.

To start the container just with docker run:

docker run -p 8000:8000 -e CERT_COUNTRY=DE ghcr.io/merlinschumacher/open-covid-certificate-validator:main

If you want to start the service manually, you need to set up a virtual envinroment and install the package requirements. Then set the environment variable CERT_COUNTRYto either DE or AT and run python main.py. After the service starts it should run on http://localhost:8000.

To access the API send a POST request containing the following JSON to /:

    {"dcc": "HC1:XXXX..."}

Replace the payload with the data of the COVID certificate. The server will then return the following answer, if the certificate is valid:

{
  "valid": true,
  "dccdata": {
    "1": "AT",
    "4": 1635876000,
    "6": 1620324000,
    "-260": {
      "1": {
        "v": [
          {
            "dn": 1,
            "ma": "ORG-100030215",
            "vp": "1119349007",
            "dt": "2021-02-18",
            "co": "AT",
            "ci": "URN:UVCI:01:AT:10807843F94AEE0EE5093FBC254BD813#B",
            "mp": "EU/1/20/1528",
            "is": "Ministry of Health, Austria",
            "sd": 2,
            "tg": "840539006"
          }
        ],
        "nam": {
          "fnt": "MUSTERFRAU<GOESSINGER",
          "fn": "Musterfrau-Gößinger",
          "gnt": "GABRIELE",
          "gn": "Gabriele"
        },
        "ver": "1.0.0",
        "dob": "1998-02-26"
      }
    }
  }
}

If it's invalid, the server will simply return

{
    "valid":false, 
    "ddcdata":{}
}

The ddcdata field contains all the data encoded in the certificate according to the specification by the EU

Validation rules

The service returns a list of so called business rules on the endpoint /business_rules. To check if the validated certificate is currently valid in a given context you must evaluate those rules. The rules are a variant of JsonLogic called CertLogic.

Contributing

Everyone is invited to contribute to the service and provide pull-requests, ideas and feedback.

Foremost the service needs testing with certificates from all issuing countries and also the implementation of all available validation lists from the EU members. You can contribute with testing your certificate and reporting your success or possible errors.

Privacy

While the data encoded in the certificate are sent to the server, they are never stored. They will be processed to generate a response and are deleted afterwards. There is no logging of indidivual data of any kind.

The web service

This container provides a simple web service to test and validate certificates. It uses your webcam or phone camera to scan a QR code for a certificate and sends it to the API.

Technology

The API service is written in Python and uses FastAPI to provide the JSON API. The validation is handled by python-cwt, a CBOR Web Token library.

The web interface is still very rudimentary and build in Typescript using jsQR to decode the QR codes.