About • Development • Documentation • Support • Contribute • Licensing
This repository contains the source code of the EU Digital COVID Certificate Validation Service.
The validation service can validate EU Digital Covid Certificates for travel and booking services using business rules from dgca-businessrule-service and certificates from dgca-verifier-service.
The validation has a complex work flow that involves
- dgca-validation-decorator - additional service on travel system
- dgca-booking-demo - travel system mock
- dgca-booking-demo-frontend
- dgca-verifier-app-android - provide dcc
Note: The document defines in the identity document RFC7517 for x5c, which is a json array instead of a string. The kid is calculated over the first certificate of the chain.
The validation service checks the provided DCC for:
- Expiration
- Issuing Date validity
- Cryptographic validity
- FNT/GNT/DOB Matching
- Provided Certificate Type
- Category Checks (not implemented)
- Business Rules
The VS does not perform additional checkups regarding the "category" of the access token, which is depending on the operator of the service to do additional checks or not, if necessary.
The confirmation token is a signed JWT which confirms the successful checkup of a DCC associated with a subject. This token can be signed by a self signed certificate which was created especially for this VS instance OR by a CSCA. Which option is chosen depends on the operator. Whatever is chosen, it's recommended to share the VS signer certificate public keys on national lists or to share the Identity Documents URLs of the validation services, for validating confirmation tokens across all service providers in a decentralized manner.
The VS delivers a result OK (all checks passed), NOK (DCC not valid) or CHK (cross check necessary). CHK means in this case to cross check documents and/or request additional RAT or PCR tests, because the VS was not able to check the DCC successfully. Depending on the used additional checks in the VS, controlled by the categories, the CHK value can be used for manual checkups as well.
The public key for the initialization call must be in a PEM format with or without PEM Markers. In the case of Apple iOS the public key must be converted into DER format at first before generating a PEM out of it (https://github.com/eu-digital-green-certificates/dgca-app-core-ios/blob/main/Sources/Services/X509.swift#L39). Otherwise the key is encoded in ASN1 format and not readable by Java's Bouncy Castle.
RSA Keys should have a minimum of 3072 bits according to the RSA recommendation of TLS certificates (https://github.com/eu-digital-green-certificates/dgc-overview/blob/main/guides/certificate-governance.md#requirements-on-tls-upload-and-csca).
| Enc Scheme Name | Enc Key | Sig Alg Name | Wallet Public Key | Key Encryption Details | DCC Encryption Details |
|---|---|---|---|---|---|
| RSAOAEPWithSHA256AESCBC | Mandatory, minimum 32 bytes | SHA256withECDSA | ECDSA Key, secp256r1, x.509 PEM Format | Mode=OAEP, MGF=MGF1, Hash=SHA256 | IV=X-Nonce (16 Bytes), must be randomly generated |
| RSAOAEPWithSHA256AESGCM | Mandatory, minimum 32 bytes | SHA256withECDSA | ECDSA Key, secp256r1, x.509 PEM Format | Mode=OAEP, MFG=MGF1, Hash=SHA25 | IV=X-Nonce (16 Bytes), randomly generated |
Please note: the encryption schemes were selected in this manner, to support a wide range of devices, programming languages and tools. Embedded encryption schemas like ECIES and similar can be provided for the future (e.g. Apple iOS Ecies schemes).
Accesstokens must have a valid audience, iat, kid and exp for the call. The kid is checked against the available public keys, which can be loaded from:
- Fixed Provider (Environment Variable DGC_ACCESSKEYS)
- Identity Document (Environment Variable Decorator URL, dynamically download)
- Custom Key Provider (not implemented yet)
The provided keys in the identity document should be held in an HSM or any kind of vault (hashicorp, jks etc.). To increase the security it's recommended to rollover the keys for encryption from time to time or provide multiple ones in the same time.
To select the right key for encryption, a wallet app should search for "type": "DccEncryptionScheme2021" in the verification Methods to identity available encryption schemas. All found methods can be scanned for the needed schema e.g. RSAOAEPWithSHA256AESGCM. Within the "verificationMethods" can the linked key material be found for encryption. The latest method of this array should be used for encryption.
When the validation service is linked in the validation decorator, the TLS certificate is defined there to allow the connection pinning. Is this certificate changed in the future, the decorators must be informed about this change to insert the certificate in the own identity document under "ValidationServiceKey". To establish the rollover, the new service must be added in the "services" section as well as a new service (e.g. ValidationService-5). It's recommended that the wallet app handles these multiple services grouped by validation service URL (sorted by latest service added) to support the rollover. For instance, are three services configured and all of them roll over in the same time. The document should contain 6 validation service definitions with 3 groups of two items. Each couple of items have the same url. In the wallet app, just the three latest should be shown for selection.
- Open JDK 11
- Maven
- Docker
- Authenticate 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:packagesfor downloading packages
- Copy/Augment
~/.m2/settings.xmlwith the contents ofsettings.xmlpresent in this repository- Replace
${app.packages.username}with your github username - Replace
${app.packages.password}with the generated PAT
- Replace
- Run
docker login docker.pkg.github.com/eu-digital-green-certificatesbefore running further docker commands.- Use your GitHub username as username
- Use the generated PAT as password
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.
- Check settings.xml in root folder and copy the servers to your own
~/.m2/settings.xmlto connect the GitHub repositories we use in our code. Provide your GitHub username and access token (see GitHub Help) under the variables suggested. - Run
mvn clean packagefrom the project root folder
- Perform maven build as described above
- Run
docker-compose upfrom the project root folder
After all containers have started you will be able to reach the application on your local machine under port 8080.
The following channels are available for discussions, feedback, and support requests:
| Type | Channel |
|---|---|
| Issues | |
| Other requests |  |
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.
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.