DgcReader 1.3.1

DgcReader

Extensible .NET library for decoding and validating European Digital Green Certificates

Summary

The library allows to decode and validate any EU Digital Green Certificate, providing some abstractions to easily implement specific providers for every country backend.

It supports any kind of project compatible with .NET Standard 2.0 and also legacy applications from .NET Framework 4.5.2 onwards.

Starting from version 1.3.0, the library has been included in the list of verified SDKs by Italian authorities (Ministero della salute).
The approval only refers to the main module DgcReader in combination with DgcReader.TrustListProviders.Italy and DgcReader.RuleValidators.Italy, using configuration parameters compliant with the current Italian regulations.

For usage in different countries, please refer to the disclaimer and to the specific documentation of each project.

Usage

The main entry point of the library is the DgcReaderService class.

You can simply register it as a service:

public void ConfigureServices(IServiceCollection services)
{
   ...
   services.AddDgcReader()                     // Add the DgcReaderService as singleton
       .AddItalianTrustListProvider(o =>       // Register the ItalianTrustListProvider service (or any other provider type)
       {
           // Optionally, configure the provider with custom options
           o.RefreshInterval = TimeSpan.FromHours(24);
           o.MinRefreshInterval = TimeSpan.FromHours(1);
           o.SaveCertificate = true;
           ...
       })
       .AddItalianBlacklistProvider()      // The blacklist provider service
       .AddItalianRulesValidator();        // Finally, the rules validator
}

then getting it from the DI ServiceCollection:

...
// Getting an instance by dependency injection (from .NET standard 2.0 onward)
var dgcReader = ServiceCollection.GetService<DgcReaderService>();

If you don't use the dependency injection, you can instantiate it directly:

a) Use a TrustListProviderand RulesValidator:

// Create an instance of the TrustListProvider (eg. ItalianTrustListProvider) and the other required services
var httpClient = new HttpClient();
var trustListProvider = new ItalianTrustListProvider(httpClient);
var rulesValidator = new DgcItalianRulesValidator(httpClient);  // Note: this implementation is both a IRulesValidator and a IBlacklistProvider

// Create an instance of the DgcReaderService
var dgcReader = new DgcReaderService(trustListProvider, rulesValidator, rulesValidator);

Once instantiated and configured with at least the ITrustListProvider service, you can simply call one of the methods shown in c)

b) Use the DgcReaderService without arguments (i.e. no TrustListProviderand RulesValidator):

This lets you decode all the QR code data without verification, but still gives you a quick idea about how the library works. You can use the open source EU Digital Green Test Certifactes or your personal certificate.

// Create the default instance of the `DgcReaderService` with an empty constructor
var dgcReader = new DgcReaderService();

c) Run the validation

...
string qrCodeData = "Raw qr code data staring with HC1:";

// Decode and validate the qr code data.
// The result will contain all the details of the validated object
var result = await dgcReader.GetValidationResult(qrCodeData);

var status = result.Status;
var signatureIsValid = result.HasValidSignature;
...

or

...
string qrCodeData = "Raw qr code data staring with HC1:";
try
{
    // Decode and validate the signature.
    // If anything fails, an exception is thrown containing the error details
    var result = await dgcReader.Verify(qrCodeData);
}
catch(Exception e)
{
    Console.WriteLine($"Error verifying DGC: {e.Message}");
}

Information about how to interprete the decoded values can be found in the Value Sets for Digital Green Certificates and the COVID-19 Data Reporting for Non-Lab-Based Testing.

Rules validation

Rules validation is an optional service and can be done by registering an IRulesValidator service, or by passing it to the constructor.

Once registered, the validator will be executed when calling DgcReader.Verify() or DgcReader.GetValidationResult().
If validation succeded, the result status will be set to Valid or PartiallyValid, otherwise another status will be returned when calling DgcReader.GetValidationResult(), or an exception will be thrown when using DgcReader.Verify().

While TrustList providers and BlackList providers are virtually interchangeable, the rules for determining if a certificate is valid are different for every country.
For this reason, a specific implementation of the IRulesValidator should be used in order to determine if the certificate is valid for a particular country.

Supported frameworks differences

The library supports a wide range of .NET and .NET Framework versions, trying to keep the dependencies to third party libraries at minimum. For this reason, the implementation of the cryptographic functionalities for signature validations and certificates parsing are implemented with the apis of the System.Security.Cryptography namespace.
These APIs were not fully implemented in previous versions of the framework, so the version compiled for .NET Framework 4.5.2 uses the BouncyCastle library instead.

Packages

Description	Version
Main package, containing the DgcReaderService
TrustList implementation for the Italian backend
TrustList implementation for the Swedish backend
Abstractions for building TrustList providers
Implementation for the Italian validation rules

Extending the library

All you have to do in order to extend the library is to implement the interfaces exposed under the DgcReader.Interfaces.* namespace. You can use the implementations in the repository as an example, or you can code them from scratch.
If you are implementing a TrustList provider, the DgcReader.TrustListProviders.Abstractions package can results useful to simply implement a service optimized for multiple concurrent requests like a web application.
Any suggestion will be appreciated!

Requirements

In order to compile and run the solution, you will need the following tools:

• Microsoft Visual Studio 2019 with the latest updates installed (16.11.7 at the moment of writing), or Microsoft Visual Studio 2022
• Because some projects supports multiple version of the .NET framework, you should have installed the related targeting packs. At the moment, .NET Framework 4.5.2, .NET Framework 4.7 and .NET Standard 2.0 are supported

<a name="disclaimer">Disclaimer</a>

Some implementations in this repository may not have been approved by official authorities, or may be approved only by some countries.
Unless otherwise indicated, such implementations must be considered unofficial, and it is not assured in any way that they fully comply with dispositions of the reference countries.

The author assumes no responsibility for any unauthorized use of the library and no warranties about the correctness of the implementation, as better stated in the License.

Some code of the library is based on the DCCValidator App.
Many thanks to their authors for sharing their code!

Copyright © 2021 Davide Trevisan
Licensed under the Apache License, Version 2.0