Home

Awesome

La version française suit.

COVID Alert Diagnosis Server

COVID Alert is now retired: For more information, visit the Government of Canada COVID Alert home page.

Adapted from https://github.com/CovidShield/server

This repository implements a diagnosis server to use as a server for Apple/Google's Exposure Notification framework, informed by the guidance provided by Canada's Privacy Commissioners.

The choices made in implementation are meant to maximize privacy, security, and performance. No personally-identifiable information is ever stored, and nothing other than IP address is available to the server. No data at all is retained past 21 days. This server is designed to handle use by up to 38 million Canadians, though it can be scaled to any population size.

In this document:

Overview

Apple/Google's Exposure Notification specifications provide important information to contextualize the rest of this document.

There are two fundamental operations conceptually:

These two operations are implemented as two separate servers (key-submission and key-retrieval) generated from this codebase, and can be deployed independently as long as they share a database. It is also possible to deploy any number of configurations for each of these components, connected to the same database, though there would be little value in deploying multiple configurations of key-retrieval.

For a more technical overview of the codebase, especially of the protocol and database schema, see this video.

Retrieving diagnosis keys

When diagnosis keys are uploaded, the key-submission server stores the data defined and required by the Exposure Notification API in addition to the time at which the data was received by the server. This submission timestamp is rounded to the nearest hour for privacy preservation (to prevent correlation of multiple keys to the same user).

The hour of submission is used to group keys into buckets, in order to prevent clients (COVID Alert mobile app) from having to download a given set of key data multiple times in order to repeatedly check for exposure.

The published diagnosis keys are fetched—with some best-effort authentication—from a Content Distribution Network (CDN), backed by key-retrieval. This allows a functionally-arbitrary number of concurrent users.

Retrieving Exposure Configuration

Exposure Configuration, used to determine the risk of a given exposure, is also retrieved from the key-retrieval server. A JSON document describing the current exposure configuration for a given region is available at the path /exposure-configuration/<region>.json, e.g. for Ontario (region ON):

$ curl https://retrieval.covidshield.app/exposure-configuration/ON.json
{"minimumRiskScore":0,"attenuationLevelValues":[1,2,3,4,5,6,7,8],"attenuationWeight":50,"daysSinceLastExposureLevelValues":[1,2,3,4,5,6,7,8],"daysSinceLastExposureWeight":50,"durationLevelValues":[1,2,3,4,5,6,7,8],"durationWeight":50,"transmissionRiskLevelValues":[1,2,3,4,5,6,7,8],"transmissionRiskWeight":50}

Submitting diagnosis keys

In brief, upon receiving a positive diagnosis, a health care professional will generate a One Time Code through a web application frontend (COVID Alert Portal), which communicates with key-submission. This code is sent to the patient, who enters the code into their COVID Alert mobile app. This code is used to authenticate the Application (once) to the diagnosis server. Encryption keypairs are exchanged by the Application and the key-submission server to be stored for fourteen days, and the One Time Code is immediately purged from the database.

These keypairs are used to encrypt and authorize Diagnosis Key uploads for the next fourteen days, after which they are purged from the database.

The encryption scheme employed for key upload is NaCl Box (a public-key encryption scheme using Curve25519, XSalsa20, and Poly1305). This is widely regarded as an exceedingly secure implementation of Elliptic-Curve cryptography.

Data usage

The Diagnosis Key retrieval protocol used in COVID Alert was designed to restrict the data transfer to a minimum. With large numbers of keys and assuming the client fetches using compression, there is minimal protocol overhead on top of the key data size of 16 bytes.

In all examples below:

Data below is current at May 12, 2020. For each case, we assume the example daily new cases is a steady daily recurrence.

Deployed only to province of Ontario

There were 350 new cases in Ontario on May 10, 2020. 350 * 28 * 18 = 170kB per day, thus, deploying to the province of Ontario at current infection rates would cause 7.1kB of download each hour.

Deployed to Canada

There were 1100 new cases in Canada on May 10, 2020. 1100 * 28 * 18 = 540kB per day, thus, deploying to Canada at current infection rates would cause 23kB of download each hour.

Deployed to entire United States of America

There were 18,000 new cases in America on May 10, 2020. 18,000 * 28 * 18 = 8.9MB per day, thus, deploying to the all of America at current infection rates would cause: 370kB of download each hour.

Deployed to entire world

If COVID Alert were deployed for the entire world, we would be inclined to use the "regions" built into the protocol to implement key namespacing, in order to not serve up the entire set of global diagnosis keys to each and every person in the world, but let's work through the number in the case that we wouldn't:

There were 74,000 new cases globally on May 10, 2020. 74,000 * 28 * 16 = 36MB per day, thus, deploying to the entire world at current infection rates would cause: 1.5MB of download each hour.

Generating one-time codes

We use a one-time code generation scheme that allows authenticated case workers to issue codes, which are to be passed to patients with positive diagnoses via whatever communication channel is convenient.

This depends on a separate service, holding credentials to talk to this (key-submission) server. We have a sample implementation we will open source soon, but we anticipate that health authorities will prefer to integrate this feature into their existing systems. The integration is extremely straightforward, and we have minimal examples in several languages. Most minimally:

curl -XPOST -H "Authorization: Bearer $token" "https://submission.covidshield.app/new-key-claim"

Protocol documentation

For a more in-depth description of the protocol, please see the "proto" subdirectory of this repo.

Deployment notes

Platforms

We hope to provide reference implementations on AWS, GCP, and Azure via Hashicorp Terraform.

Amazon AWS

Kubernetes

Metrics and Tracing

COVID Alert uses OpenTelemetry to configure the metrics and tracing for the server, both the key retrieval and key submission.

Metrics

Currently, the following options are supported for enabling Metrics:

Metrics can be enabled by setting the METRIC_PROVIDER variable to stdout, pretty, or prometheus.

Both stdout and pretty will send metrics output to stdout but differ in their formatting. stdout will print the metrics as JSON on a single line whereas pretty will format the JSON in a human-readable way, split across multiple lines.

If you want to use Prometheus, please see the additional configuration requirements below.

Server Events

The server tracks in aggregate by day or hour and by originator (Bearer Token) the following events.

OTKGenerated

This tracks the number of One Time Keys generated by calling the /new-key-claim endpoint.

OTKClaimed

This tracks the number of One Time Keys generated by calling the /claim-key endpoint. This is done when a One Time Key is entered by a citizen into their phone.

OTKUnclaimed

This tracks the number of One Time Keys that are unclaimed and are younger than the config.AppConstants.OneTimeCodeExpiryInMinutes configuration value.

OTKExpired

This tracks the number of claimed One Time Keys that have expired in the database a key expires when it has been claimed and is older than the config.AppConstants.EncryptionKeyValidityDays.

OTKExhausted

This tracks the number of claimed One Time Keys that have 0 for the remaining_keys field in the encryption_keys table.

OTKRegenerated

This tracks the number of times the /new-key-claim endpoint is called with an existing hashID. When this occurs the existing One Time Key is deleted and a new one is generated in it's place.

OTKExpiredNoUploads

The tracks the number of One Time Keys that have been claimed and expired with no uploads of Temporary Exposure Keys

OTKDurations

This tracks how long One Time Keys are unclaimed for to rounded up to the nearest hour.

Prometheus

In order to use Prometheus as a metrics solution, you'll need to be running it in your environment.

You can follow the instructions here for running Prometheus.

You will need to edit the configuration file, prometheus.yml to add an additional target so it actually polls the metrics coming from the COVID Alert server:

...
    static_configs:
    - targets: ['localhost:9090', 'localhost:2222']

Tracing

Currently, the following options are supported for enabling Tracing:

Tracing can be enabled by setting the TRACER_PROVIDER variable to stdout or pretty.

Both stdout and pretty will send trace output to stdout but differ in their formatting. stdout will print the trace as JSON on a single line whereas pretty will format the JSON in a human-readable way, split across multiple lines.

Note that logs are emitted to stderr, so with stdout mode, logs will be on stderr and metrics will be on stdout.

Contributing

See the Contributing Guidelines.

Who Built COVID Alert?

COVID Alert was originally developed by volunteers at Shopify. It was released free of charge under a flexible open-source license.

This repository is being developed by the Canadian Digital Service. We can be reached at cds-snc@tbs-sct.gc.ca.

Serveur de diagnostic COVID Alert

Alerte COVID a été mis hors service : Pour en savoir davantage, visitez la page d'accueil d’Alerte COVID du gouvernement du Canada.

Adapté à partir de https://github.com/CovidShield/server (voir les modifications)

Ce dépôt implémente un serveur de diagnostic à utiliser comme serveur pour le cadriciel de notification d’exposition d’Apple et de Google, suivant les directives fournies par les commissaires à la protection de la vie privée du Canada.

Les choix faits dans l’implémentation visent à maximiser la confidentialité, la sécurité et le rendement. Les renseignements identificatoires ne sont jamais stockés, et il n’y a que l’adresse IP qui est accessible au serveur. Aucune donnée n’est conservée après 21 jours. Ce serveur est conçu pour gérer jusqu’à 38 millions d’utilisateurs canadiens, même s’il peut être étendu à n’importe quelle taille de population.

Dans la présente documentation :

Aperçu

Les spécifications de la notification d’exposition d’Apple et de Google fournissent des renseignements importants pour contextualiser le reste de ce document.

Il y a deux opérations fondamentales sur le plan conceptuel :

Ces deux opérations sont implémentées en tant que deux serveurs distincts (key-submission et key-retrieval) générés à partir de cette base de code, et peuvent être déployées indépendamment tant qu’elles partagent une base de données. Il est également possible de déployer n’importe quel nombre de configurations pour chacun de ces composants, connectés à la même base de données, même s’il y aurait peu d’utilité à déployer plusieurs configurations de key-retrieval.

Pour une vue d’ensemble technique du code de base, particulièrement du protocole et du schéma de base de données, voir cette vidéo.

Récupération des clés de diagnostic

Au moment du téléversement des clés de diagnostic, le serveur key-submission stocke les données définies et requises par l’interface de programmation d’applications (API) de notification d’exposition en plus de la date à laquelle les données ont été reçues par le serveur. L’horodatage de cet envoi est arrondi à l’heure la plus proche pour la protection de la vie privée (pour empêcher la corrélation de plusieurs clés avec le même utilisateur).

L’heure d’envoi est utilisée pour regrouper les clés en compartiments, afin d’empêcher que les clients (l’application mobile COVID Alert) aient à télécharger un certain ensemble de données de clés plusieurs fois pour pouvoir vérifier l’exposition de manière répétée.

Les clés de diagnostic publiées sont extraites (avec une authentification optimisée) à partir d’un réseau de distribution du contenu (RDC), soutenu par key-retrieval. Cela permet un nombre fonctionnellement arbitraire d’utilisateurs simultanés.

Récupération de la configuration de l’exposition

La configuration de l’exposition, utilisée pour déterminer le risque d’une exposition donnée, est également récupérée sur le serveur key-retrieval. Un document JSON décrivant la configuration d’exposition actuelle pour une région donnée est disponible par le chemin /exposure-configuration/<region>.json, par exemple pour l’Ontario (région ON) :

$ curl https://retrieval.covidshield.app/exposure-configuration/ON.json
{"minimumRiskScore":0,"attenuationLevelValues":[1,2,3,4,5,6,7,8],"attenuationWeight":50,"daysSinceLastExposureLevelValues":[1,2,3,4,5,6,7,8],"daysSinceLastExposureWeight":50,"durationLevelValues":[1,2,3,4,5,6,7,8],"durationWeight":50,"transmissionRiskLevelValues":[1,2,3,4,5,6,7,8],"transmissionRiskWeight":50}

Envoyer les clés de diagnostic

En bref, lorsque qu’un diagnostic positif est établi, le professionnel de la santé générera un code à usage unique avec une application Web frontale (COVID Alert Portal) qui communique avec key-submission. Ce code est envoyé au patient, qui entre le code dans son application mobile COVID Alert. Ce code est utilisé pour authentifier l’application (une fois) vis-à-vis le serveur de diagnostic. Les paires de clés de chiffrement sont échangées par l’application et le serveur key-submission et sont stockée pendant quatorze jours, et la base de données est immédiatement purgée du code à usage unique.

Ces paires de clés sont utilisées pour chiffrer et autoriser les téléversements de clé de diagnostic pendant les quatorze jours qui suivent, après quoi elles sont enlevées de la base de données.

Le schéma de chiffrement utilisé pour le téléchargement de clés est NaCl Box (un schéma de chiffrement de clé publique utilisant Curve25519, XSalsa20 et Poly1305). Il s’agit d’une implémentation considérée extrêmement sécuritaire de la cryptographie à courbe elliptique.

Utilisation des données

Le protocole de récupération des clés de diagnostic utilisé dans COVID Alert a été conçu pour limiter le transfert de données à un minimum. Considérant le grand nombre de clés, et en supposant que le client les extraie en utilisant la compression, il y a un surdébit de protocole minimal en plus de la taille des données de clé de 16 octets.

Dans tous les exemples ci-dessous :

Les données ci-dessous datent du 12 mai 2020. Pour chaque cas, nous supposons que les exemples de nouveaux cas recensés sont une récurrence quotidienne constante.

Déployé uniquement dans la province d’Ontario

Il y a eu 350 nouveaux cas en Ontario le 10 mai 2020 : 350 * 28 * 18 = 170 ko par jour. Ainsi, un déploiement dans la province de l’Ontario au taux d’infection actuel engendrerait 7,1 ko de téléchargement par heure.

Déployé au Canada

Le 10 mai 2020, il y a eu 1100 nouveaux cas au Canada : 1100 * 28 * 18 = 540 ko par jour. Ainsi, le déploiement au Canada au taux d’infection actuel entraînerait 23 ko de téléchargement par heure.

Déployé dans l’ensemble des États-Unis d’Amérique

Il y a eu 18 000 nouveaux cas aux États-Unis le 10 mai 2020 : 18 000 * 28 * 18 = 8,9 mégaoctets [Mo] par jour. Ainsi, le déploiement dans l’ensemble des États-Unis au taux d’infection actuel entraînerait 370 ko de téléchargement par heure.

Déployé dans le monde entier

Si COVID Alert était déployé dans le monde entier, nous serions enclins à utiliser les « régions » conçues dans le protocole pour établir des espaces de noms pour les clés, afin de ne pas desservir l’ensemble des clés de diagnostic mondiales pour chaque personne dans le monde. Passons cependant en revue les chiffres au cas où nous ne le ferions pas :

Le 10 mai 2020, il y a eu 74 000 nouveaux cas dans le monde : 74 000 * 28 * 16 = 36 Mo par jour. Ainsi, le déploiement dans le monde entier au taux d’infection actuel entraînerait 1,5 Mo de téléchargement par heure.

Génération de codes à usage unique

Nous utilisons un système de génération de codes à usage unique qui permet aux professionnels authentifiés d’émettre des codes. Ces codes doivent être transmis aux patients présentant un diagnostic positif par l’intermédiaire de n’importe quel canal de communication pratique.

Cette démarche dépend d’un service différent, qui détient des justificatifs pour communiquer avec ce serveur (key-submission). Nous avons une implémentation à titre d’exemple dont le code source sera bientôt ouvert. Cependant, nous nous attendons à ce que les autorités sanitaires préfèrent intégrer cette fonctionnalité dans leurs systèmes existants. L’intégration est extrêmement simple, et on dispose d’exemples en plusieurs languages. Au minimum :

curl -XPOST -H "Authorization: Bearer $token" "https://submission.covidshield.app/new-key-claim"

Documentation du protocole

Pour une description détaillée du protocole, veuillez consulter le sous-répertoire « proto » de ce dépôt.

Remarques de déploiement

Plateformes

Nous espérons fournir des implémentations de référence sur AWS, GCP et Azure par Hashicorp Terraform.

Amazon AWS

Kubernetes

Indicateurs et traçage

COVID Alert utilise OpenTelemetry pour configurer les indicateurs et le traçage du serveur, à la fois pour la récupération et l’envoi des clés.

Indicateurs

Actuellement, les options suivantes sont prises en charge pour activer les indicateurs :

Les indicateurs peuvent être activés en définissant la variable METRIC_PROVIDER sur stdout, pretty, ou prometheus.

Aussi bien stdout que pretty enverront les indicateurs de sortie à stdout, mais leur mise en forme diffère. stdoutimprimera les indicateurs en tant que JSON sur une seule ligne, tandis quepretty` formatera le JSON de manière lisible pour les humains, avec une séparation sur plusieurs lignes.

Si vous voulez utiliser Prometheus, veuillez consulter les exigences de configuration supplémentaires ci-dessous. Événements du serveur Le serveur fait le suivi des événements suivants de façon agrégée par jour ou par heure, et par desserveur (Bearer Token).

OTKGenerated

Assure le suivi du nombre de clés à usage unique (OTK) générées lorsque le point d’extrémité /new-key-claim est appelé.

OTKClaimed

Assure le suivi du nombre de clés à usage unique (OTK) générées lorsque le point d’extrémité /claim-key est appelé. Événement réalisé lorsqu’une clé à usage unique est entrée dans l’application par un citoyen.

OTKUnclaimed

Assure le suivi du nombre de clés à usage unique (OTK) qui n’ont pas été réclamées et dont le délai est en deçà de la valeur de configuration config.AppConstants.OneTimeCodeExpiryInMinutes.

OTKExpired

Assure le suivi du nombre de clés à usage unique (OTK) qui ont expiré dans la base de données. Une clé expire lorsqu’elle a été réclamée mais que son délai dépasse config.AppConstants.EncryptionKeyValidityDays.

OTKExhausted

Suivi du nombre de clés à usage unique (OTK) dont le champ remaining_keys est 0 dans le tableau encryption_keys.

OTKRegenerated

Suivi du nombre de fois où le point d’extrémité /new-key-claim est appelé avec un hashID existant. Lorsque cela se produit, la clé à usage unique existante est supprimée, et une nouvelle clé à usage unique est générée.

OTKExpiredNoUploads

Suivi du nombre de clés à usage unique (OTK) qui ont été réclamées et qui ont expiré sans que les clés d’exposition temporaires (temporary exposure keys) ne soient téléversées.

OTKDurations

Suivi de la durée pendant laquelle les clés à usage unique (OTK) sont non réclamées. Valeur en nombre d’heures, arrondie à la hausse.

Prometheus

Pour utiliser Prometheus comme solution d’indicateurs, vous devez l’exécuter dans votre environnement.

Vous pouvez suivre les instructions ici pour exécuter Prometheus.

Vous devrez éditer le fichier de configuration prometheus.yml pour ajouter une cible supplémentaire afin qu’il interroge réellement les indicateurs provenant du serveur COVID Alert :

...
    static_configs:
    - targets: ['localhost:9090', 'localhost:2222']

Traçage

Actuellement, les options suivantes sont prises en charge pour activer le traçage :

Le traçage peut être activé en définissant la variable TRACER_PROVIDER sur stdout ou pretty.

Aussi bien stdout que pretty enverront le traçage de sortie à stdout, mais leur mise en forme diffère. stdout imprimera le traçage en tant que JSON sur une seule ligne, tandis que pretty formatera le JSON de manière lisible pour les humains, avec une séparation sur plusieurs lignes.

Notez que les journaux sont émis en mode stderr, de sorte qu’avec le mode stdout, les journaux seront en mode stderr et les indicateurs seront en mode stdout.

Contribution

Consultez les Directives de contribution.

Qui a conçu COVID Alert?

COVID Alert a été développé à l’origine par des bénévoles de Shopify. Il a été diffusé gratuitement en vertu d’une licence ouverte flexible.

Ce dépôt est maintenu par le Service numérique canadien. Vous pouvez nous joindre à cds-snc@tbs-sct.gc.ca.