From 1ee6a5132415cfb75a9201b209ba8882bab84ba7 Mon Sep 17 00:00:00 2001 From: Eric Bratter Date: Fri, 16 Oct 2020 12:37:28 -0400 Subject: [PATCH 1/3] fix: update backend service to include EFGS --- images/solution_architecture/figure_1.svg | 900 +++++++++++++- images/solution_architecture/figure_6.svg | 1335 ++++++++++++++++++++- solution_architecture.md | 8 +- 3 files changed, 2240 insertions(+), 3 deletions(-) diff --git a/images/solution_architecture/figure_1.svg b/images/solution_architecture/figure_1.svg index 1908c3d..af1442c 100644 --- a/images/solution_architecture/figure_1.svg +++ b/images/solution_architecture/figure_1.svg @@ -1,3 +1,901 @@ - Produced by OmniGraffle 6.6.2 2020-05-31 08:58:46 +0000Figure 1Ebene 1Mobile PhoneCWAMobile PhoneCWAMobile PhoneApple iPhone or Android phoneRetrieve results+ TANCorona-Warn-App (CWA)Test result retrieval and exposure notification (tracing)(Apple iOS and Google Android)Verificationof TAN Exposure NotificationFrameworkExposure NotificationDataRBroadcastingof RPI andencrypted metadata ScanningBLE Beacon Mechanics(No active connection)ScanningBroadcastingBluetoothLowEnergy(BLE)Hardware InterfaceVerification ServerCorona-Warn-App ServerDownload of keysand configuration RCDNCDNContent Delivery Network (CDN)RRUpload of keys(+TAN for verification)Aggregated keys+ configurationLaboratory Information System (LIS)Portal ServerHealth AuthorityHotlineRRRRRRRetrieve resultsMobile PhoneCWAOpen SourceExisting SolutionsFigure 1: High-level architecture overviewTest Result ServerR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Produced by OmniGraffle 7.17.5\n2020-10-16 16:08:56 +0000 + + high-level-overview + + + Layer 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Figure 1: High-level architecture overview + + + + + + + Mobile Phone + Apple iPhone or Android phone + + + + + + + Bluetooth + Low + Energy + (BLE) + Hardware + Interface + + + + + + + Exposure + Notification + Framework + + + + + + + Corona-Warn-App (CWA) + Test result retrieval and exposure + notification (tracing) + (Apple iOS and Google Android) + + + + + + + Open Source + + + + + + + Existing Solutions + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Exposure + Notification Data + + + + + + + + + + + + + + + Mobile Phone + + + + + + + BLE Beacon Mechanics + (No active connection + + + + + + + + + + + + + + + + + + + + + + + + CWA + + + + + + + Mobile Phone + + + + + + + CWA + + + + + + + Mobile Phone + + + + + + + CWA + + + + + + + + + + + + + + Broadcasting + + + + + Broadcasting of RPI + encrypted metadata + + + + + Scanning + + + + + + + Laboratory Information + System (LIS) + + + + + + + Health + Authority + + + + + + + Hotline + + + + + + + Test Result Server + + + + + + + Portal Server + + + + + + + Verification Server + + + + + + + Corona-Warn-App + Server + + + + + + + European Federation + Gateway + + + + + + + + + + + + + + + Content Delivery + Network (CDN) + + + + + + + + + + R + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + Verification + of TAN + + + + + + + + + + + R + + + + + + + + + + + + + + + + + Aggregated keys + + Configuration + + + + + + + + + + R + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + Upload/Download + of keys + + + + + Callback + Notifications + + + + + Retrieve + Results + + + + + + + + + + R + + + + + + + + + + + + + + + + Upload of keys + (+TAN for Verification) + + + + + + + + + + R + + + + + + + + + + + + + + + + Download of keys and + configuration + + + + + + + + + + R + + + + + + + + + + + + + + + + Retrieve results + + TAN + + + + + Scanning + + + + + diff --git a/images/solution_architecture/figure_6.svg b/images/solution_architecture/figure_6.svg index fee43e5..1a5337d 100644 --- a/images/solution_architecture/figure_6.svg +++ b/images/solution_architecture/figure_6.svg @@ -1,3 +1,1336 @@ - Produced by OmniGraffle 6.6.2 2020-05-31 08:58:46 +0000Figure 6Ebene 1Open TelekomCloud (OTC)Mobile PhoneOS API/SDKfor Exposure Notification zxingQR Code LibraryCamerapoll testresultsRRegistrationTokenRTrigger local notificationRProtobuflibraryOS CryptoSDKROS API/SDKfor Push Messages(Notification Framework)Verification ServerCorona-Warn-AppServerTANverificationdownload of keysand parameters Laboratory Information System (LIS)RRPortal ServerHealthAuthorityHotlinesubmitresultrequest newlab/probe IDRRRCDNCDNContent Delivery Network (CDN)RRUpload of keys + TANaggregatedkeyshash(GUID)hash(Reg. Token)DatabaseOpen SourceRread QRcode fromapp (GUID) Operating System (OS) ComponentRRRhash(TAN)Test results hash(GUID)Test labprocessingsamples(Lab Client)Rsee more detailed documentation (to be published)Existing external system/library (consumed)RRretrieve TANregister with GUIDCorona-Warn-App for tracing and test result retrieval(Apple iOS / Google Android)RStorage ServiceRAggregateddiagnosis keysTransport MetadataRemovalRFigure 6: Actors in the system, including external parties (blue components to be open-sourced)Test Result ServerR + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Produced by OmniGraffle 7.17.5\n2020-10-16 16:14:53 +0000 + + Figure 6 + + + Layer 1 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + FG Environment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Open Source + + + + + + + Operating System + (OS) Component + + + + + + + Existing external + system/library + (consumed) + + + + + + + + Mobile Phone + + + + + + + OS API/SDK for + Exposure + Notification + + + + + + + OS Crypto + SDK + + + + + + + Camera + + + + + + + OS API/SDK for Push + Messages (Notification + Framework) + + + + + + + zxing QR + code Library + + + + + + + Protobuf + library + + + + + + + Registration + Token + + + + + + + Corona-Warn-App for tracing and test result retrieval + (Apple iOS / Google Android) + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + Read QR + code from + app + (GUID) + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + Trigger local + notification + + + + + + + + See more detailed + documentation + (to be published) + + + + + + + Content Delivery + Network (CDN) + + + + + + + Content Delivery + Network (CDN) + + + + + + + Content Delivery + Network (CDN) + + + + + + + + + + R + + + + + + + + + + + + + + + + Download of + keys and + parameters + + + + + + + Storage Service + + + + + + + + + + R + + + + + + + + + + + + + + + + + + Aggregated + diagnosis keys + + + + + + + + + + + + + + + Transport + Metadata Removal + + + + + + + + + + R + + + + + + + + + + + + + + + + Upload of keys + TAN + + + + + + + Corona-Warn-App + Server + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + Database + + + + + + + + + + + + + + + European Federation + Gateway Service + + + + + + + + + + R + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + Upload/ + Download of + keys + + + + + Callback + Notifications + + + + + + + Verification Service + + + + + + + + + + + R + + + + + + + + + + + + + + + + + TAN + Verification + + + + + + + + + + R + + + + + + + + + + + + + + + + Retrieve TAN + + + + + + + + + + R + + + + + + + + + + + + + + + + Poll Test + Results + + + + + + + + + + R + + + + + + + + + + + + + Register with + GUID + + + + + + + Test Result Server + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + hash (GUID) + hash (Reg. Token) + + + + + + + Hash (TAN) + + + + + + + Test results hash + (GUID) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Portal Server + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + Laboratory + Information System + (LIS) + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + + + + + R + + + + + + + + + + + + + + + + + + + Test lab processing + samples + (Lab Client) + + + + + Request new + lab/probe ID + + + + + Submit Result + + + + + Open Telekom Cloud (OTC) + + + + + Figure 6: Actors in the system, including external parties (blue components to be open-sourced) + + + + + + + + diff --git a/solution_architecture.md b/solution_architecture.md index 85c53b7..b0ff416 100644 --- a/solution_architecture.md +++ b/solution_architecture.md @@ -117,12 +117,18 @@ The Corona-Warn-App Server needs to fulfill the following tasks: - Threshold values for [attenuation buckets](#attenuation-buckets) - Risk scores for defined values - Threshold values for risk categories and alerts + - Valid country codes for EFGS Visited Countries - On a regular schedule (e.g. hourly) - Assemble diagnosis keys into chunks for a given time period - Store chunks as static files (in protocol buffers, compatible with the format specified by Apple and Google) - Transfer files to a storage service as shown at the bottom of *Figure 6* which acts as a source for the Content Delivery Network (CDN) +- Handle the integration with the [European Federation Gateway Service](https://github.com/eu-federation-gateway-service/efgs-federation-gateway) which consists of: + - Downloading keys which are shared from connected countries and making then available for use by the CWA Mobile applications + - Upload relevant keys for DE to the service to share with other connected countries + - Expose a callback API which can be used by the EFGS to notify CWA when new key batches are available for download + - Handle the translation of keys values for DSOS and TRL -Those tasks are visualized in *Figure 7*. Each of swim lanes (vertical sections of the diagram) on the left side (Phone 1, Phone 2, Phone n) represent one device that has the Corona-Warn-App installed. The user of Phone 1 has taken a SARS-CoV-2 test (which comes back positive later). The users of Phone 2 and Phone n only use the functionality to trace potential exposure. +Those tasks relevant for interaction with the CWA Mobile application are visualized in *Figure 7*. Each of swim lanes (vertical sections of the diagram) on the left side (Phone 1, Phone 2, Phone n) represent one device that has the Corona-Warn-App installed. The user of Phone 1 has taken a SARS-CoV-2 test (which comes back positive later). The users of Phone 2 and Phone n only use the functionality to trace potential exposure. The Corona-Warn-App Server represents the outside picture of the individual service working in the back end. For a better understanding, the database has been visualized separately. ![Figure 7: Interaction of the mobile application(s) with the back-end servers and CDN](images/solution_architecture/figure_7.svg "Figure 7: Interaction of the mobile application(s) with the back-end servers and CDN") From 47a192f75a7fba52b51e94a94cef02d6b45e6163 Mon Sep 17 00:00:00 2001 From: Eric Bratter Date: Fri, 16 Oct 2020 12:50:19 -0400 Subject: [PATCH 2/3] fix: dead link for app version config --- cwa-versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cwa-versioning.md b/cwa-versioning.md index fe0f32f..6af13ce 100644 --- a/cwa-versioning.md +++ b/cwa-versioning.md @@ -14,7 +14,7 @@ We plan to never deprecate outdated API versions. That means that even on MAJOR Backend components will always remain compatible due to ongoing the availability of old API versions. -To ensure that all clients use the current "state of the art" information in order to apply the respective algorithms the cwa-server component can deprecate older Android and iOS app versions. The current minimum required app versions can be viewed in the [App Version Config](https://github.com/corona-warn-app/cwa-server/blob/master/services/distribution/src/main/resources/master-config/app-version-config.yaml). +To ensure that all clients use the current "state of the art" information in order to apply the respective algorithms the cwa-server component can deprecate older Android and iOS app versions. The current minimum required app versions can be viewed in the [App Version Config](https://github.com/corona-warn-app/cwa-server/blob/master/services/distribution/src/main/resources/application.yaml#L93). The `app-version-config` is checked by the mobile clients on a regular basis. When the client detects that the required `min` version is higher than the current installed version, the user will be notified about the need to update the app. The app will not be useable until this update is performed. ## Changelogs From fa9e1d4e8956c5102371dcca873fb4e2082a88b7 Mon Sep 17 00:00:00 2001 From: Eric Bratter Date: Fri, 20 Nov 2020 08:51:57 -0500 Subject: [PATCH 3/3] chore: code review comments --- solution_architecture.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/solution_architecture.md b/solution_architecture.md index b0ff416..d9d1d08 100644 --- a/solution_architecture.md +++ b/solution_architecture.md @@ -123,12 +123,12 @@ The Corona-Warn-App Server needs to fulfill the following tasks: - Store chunks as static files (in protocol buffers, compatible with the format specified by Apple and Google) - Transfer files to a storage service as shown at the bottom of *Figure 6* which acts as a source for the Content Delivery Network (CDN) - Handle the integration with the [European Federation Gateway Service](https://github.com/eu-federation-gateway-service/efgs-federation-gateway) which consists of: - - Downloading keys which are shared from connected countries and making then available for use by the CWA Mobile applications + - Downloading keys which are shared from connected countries and making them available for use by the CWA Mobile applications - Upload relevant keys for DE to the service to share with other connected countries - Expose a callback API which can be used by the EFGS to notify CWA when new key batches are available for download - Handle the translation of keys values for DSOS and TRL -Those tasks relevant for interaction with the CWA Mobile application are visualized in *Figure 7*. Each of swim lanes (vertical sections of the diagram) on the left side (Phone 1, Phone 2, Phone n) represent one device that has the Corona-Warn-App installed. The user of Phone 1 has taken a SARS-CoV-2 test (which comes back positive later). The users of Phone 2 and Phone n only use the functionality to trace potential exposure. +Those tasks relevant for interaction with the CWA Mobile application are visualized in *Figure 7*. Each of swim lanes (vertical sections of the diagram) on the left side (Phone 1, Phone 2, Phone n) represents one device that has the Corona-Warn-App installed. The user of Phone 1 has taken a SARS-CoV-2 test (which comes back positive later). The users of Phone 2 and Phone n only use the functionality to trace potential exposure. The Corona-Warn-App Server represents the outside picture of the individual service working in the back end. For a better understanding, the database has been visualized separately. ![Figure 7: Interaction of the mobile application(s) with the back-end servers and CDN](images/solution_architecture/figure_7.svg "Figure 7: Interaction of the mobile application(s) with the back-end servers and CDN")