DgcReader.TrustListProviders.Abstractions 1.3.0

DgcReader

An extensible, unofficial library for decoding and validate the European Digital Green Certificate

Summary

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

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

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 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.

In the repository there is currently an implementation for the Italian validation rules.
Note: These rules are changing overtime, so it is not ensured in any way that the implementation it is fully compliant with the current Italian dispositions.
Anyway, current Italian regulations also requires the usage of the offical SDK it-dgc-verificac19-sdk-android for an application in order to be compliant.

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

Upgrading from version < 1.2.0

In 1.2.0 release of the packages, many changes was made in order to cleanup and standardize the interfaces as mush as possible. If you are upgrading from a previus version, keep this in mind and read this readme carefully in order to correctly use the library as intended.

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

Disclaimer

This library is not an official implementation, therefore its use may be subject to restrictions by some countries regulations.
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