Skip to content

Commit

Permalink
add initial information
Browse files Browse the repository at this point in the history
  • Loading branch information
Hendrejvr committed Oct 17, 2024
1 parent fa8be5c commit 4c6fbe7
Show file tree
Hide file tree
Showing 20 changed files with 285 additions and 2 deletions.
21 changes: 21 additions & 0 deletions .devcontainer/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Use the official Debian bullseye image as a parent image
FROM mcr.microsoft.com/devcontainers/base:bullseye

# Install dependencies required for asciidoctor and Asciidoctor Diagram
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
ruby \
ruby-dev \
build-essential \
graphviz \
plantuml \
&& gem install asciidoctor -v 2.0.20 \
&& gem install asciidoctor-diagram -v 2.2.14 \
&& gem install asciidoctor-reducer \
&& apt-get clean -y && rm -rf /var/lib/apt/lists/*

# Copy keybinding and task configuration files to the container's .vscode directory
# COPY .vscode/tasks.json .vscode/keybindings.json /workspace/.vscode/

# Set the default command to execute
CMD ["bash"]
29 changes: 29 additions & 0 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/markdown
{
"name": "Adoc Editing",
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
"build": {
"dockerfile": "Dockerfile"
},
// Features to add to the dev container. More info: https://containers.dev/features.
// "features": {},

// Configure tool-specific properties.
"customizations": {
// Configure properties specific to VS Code.
"vscode": {
// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"hanifmifta.adocs",
"MITRE-Health.vscode-language-fsh",
"mohsen1.prettify-json",
"DotJoshJohnson.xml",
"asciidoctor.asciidoctor-vscode"
]
}
},
"features": {
"ghcr.io/devcontainers-contrib/features/gh-cli:1": {}
}
}
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
*.cache
.vscode
13 changes: 13 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
Copyright (c) 2024 gematik GmbH

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

http://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.
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
# gem-push-notifications-concept
This repo contains the gematik concept for push notifications.
# gem-push-notifications-concept
This repo contains the gematik concept for push notifications.

Das Konzept liegt [hier](docs/concept.adoc)
7 changes: 7 additions & 0 deletions SECURITY.MD
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Security Policy

Please submit an issue or pull request for any non critical bugs
or non critical vulnerabilities you find.

In case of a responsible disclosure, please follow instructions
on <https://www.gematik.de/datensicherheit#c1227>.
65 changes: 65 additions & 0 deletions docs/concept.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
= Notification Management image:gematik_logo.png[width=150, float="right"]
// asciidoc settings for DE (German)
// ==================================
:imagesdir: ../images
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
:toc: macro
:toclevels: 3
:toc-title: Inhaltsverzeichnis

toc::[]

== Konzept
=== Architektur
An der Umsetzung des Notification Managements sind folgende Komponenten und Services beteiligt:

image:services-landscape.png[width=50%]

• Push Notification Service: Der Service im ePA-Aktensystem zur Verwaltung der Push-Notifications. Der Service erstellt Push- Notifications für abonnierte Ereignisse und übermittelt diese an das zuständige Push Gateway. Der Push Notification Service bietet Schnittstellen für Versicherte/Vertreter zur Registrierung und Konfiguration von Pushern. Ein Pusher bezieht sich auf eine ePA-FdV-Instanz und ist eine Konfiguration im Aktensystem, in der die Informationen zur Adressierung der Push- Notifications hinterlegt werden (u.a. das zu nutzende Push Gateway, Schlüssel zur Verschlüsselung von Nachrichteninhalten). Der Kontoinhaber kann für beliebig viele Endgeräte Pusher in seinem Konto hinterlegen. Genauso kann ein Vertreter beliebig viele Pusher für das Konto des Versicherten hinterlegen.

image:kontos.png[width=50%]

• Push Gateway: Das Push Gateway besitzt einen anwendungsübergreifenden Endpunkt, an den Push-Notifications übermittelt werden. Das Push Gateway leitet die Informationen der Push- Notification an den Push Provider. Das Push Gateway wird vom Hersteller des ePA-FdV bereitgestellt.
• Push Provider: Der Push Provider ist ein Service des Herstellers des mobilen Betriebssystems. Der Push Provider sendet Notifications an App-Instanzen auf Endgeräten der Nutzer.
• ePA-FdV-Instanz: Die ePA-FdV-Instanz ist ein auf einem mobilen Endgerät installiertes ePA-FdV. Push- Notifications werden für eine ePA-FdV-Instanz registriert und an diese ePA-FdV-Instanz gesendet.
Die Verbindungen zwischen Push Gateway und Aktensystem sind beidseitig authentisiert und verschlüsselt.

=== Registrierung einer ePA-FdV-Instanz
Damit eine ePA-FdV-Instanz Push-Notifications empfangen kann, muss diese zunächst beim Push-Provider sowie im Aktensystem registriert werden.

image:push-notification-registration.png[width=50%]

1. Die ePA-FdV-Instanz registriert sich am Push Provider und erhält ein App Token, welches die ePA-FdV-Instanz eindeutig identifiziert.
2. In der ePA-FdV-Instanz wird ein asymmetrisches Schlüsselpaar (push_pubK, push_privK) generiert und im Endgerät sicher gespeichert.
3. Der Nutzer meldet sich am Aktensystem an und registriert die ePA-FdV-Instanz am Push Notification Service für ein Aktenkonto als einen Pusher. Teil der Registrierungsdaten sind das App Token, die app_id, die Adresse des Push Gateways sowie der öffentliche Schlüssel push_pubK. Die app_id und die Adresse des Push Gateways sind im ePA-FdV durch den Hersteller hinterlegt worden.

=== Versenden von Push-Notifications
Die folgende Abbildung veranschaulicht den Ablauf, wenn ein Ereignis in einem Konto eintritt, für welches Push-Benachrichtigungen gesendet werden sollen (z.B. wenn ein Nutzer ein neues Dokument einstellt):

image:push-notification-send.png[width=50%]

1. Der Push Notification Service des Aktensystems führt folgende Schritte durch
a. Generieren einer eindeutigen EventID
b. Erzeugen des Nachrichteninhalts = („ePA“, Kontonummer, EventDetails). Die EventDetails sind spezifisch für das Event. Da das ePA-FdV Push-Benachrichtigungen von mehreren Anwendungen erhalten kann, signalisiert der konstante Wert „ePA“ dem ePA-FdV in Schritt 6, dass es sich um eine Push-Benachrichtigung bzgl. der Anwendung ePA handelt. Die Kontonummer wird aufgenommen, da auch Vertreter Push-Notifications für das Konto der zu vertretenden Versicherten erhalten können und sie in der Push-Notification erkennen können müssen, auf welches Konto sich die Benachrichtigung bezieht. Dem Nachrichteninhalt wird zur Verschleierung der Länge der Nachricht ein Zufallswert ergänzt (Encoding).
c. Das Paar (EventID, Nachrichteninhalt) wird verschlüsselt im Aktensystem persistiert.
2. Für jeden im Aktenkonto registrierten Pusher p, der für das Ereignis abonniert ist, wird eine Push-Benachrichtigung Norification_p mit folgenden Inhalten erzeugt:
a. content = Nachrichteninhalt aus 1b verschlüsselt mit dem push_pubK des Pushers p. Das Chiffrat wird mit „ePA“ gekennzeichnet. Dies erlaubt dem Push Gateway eine Priorisierung nach Anwendungen.
b. devices = (app_id, App Token)
c. event_id = EventID
3. Für jeden Pusher p wird die Push-Benachrichtigung Notification_p an das Push Gateways des Pushers p übermittelt.
4. Das Push Gateway entfernt in der erhaltenen Notification_p die Kennzeichnung „ePA“ am Chiffrat des Nachrichteninhalts und übermittelt die angepasste Push-Benachrichtigung Notification‘_p an den Push Provider.
5. Der Push-Provider sendet die Notification an die zum App Token gehörende ePA-FdV-Instanz.
6. Die ePA-FdV-Instanz entschlüsselt den Nachrichteninhalt mit dem privaten Schlüssel push_privK und zeigt dem Nutzer den Nachrichteninhalt geeignet an.
Bei Bedarf kann sich der Nutzer am Aktenkonto anmelden, um sich z.B. ein eingestelltes Dokument anzusehen.

== Zugriff auf Push-Notifications im Aktensystem
Die Nachrichteninhalte der Push-Benachrichtigungen werden im Aktensystem verschlüsselt gespeichert (vgl. Schritt 1c im Abschnitt „Versenden von Push-Notifications“). Dies erfolgt aus mehreren Gründen:
• Es ist nicht garantiert, dass jede Push-Notification an der ePA-FdV-Instanz ankommt.
• Der Nutzer soll die Möglichkeit haben, Push-Notifications auch noch lesen zu können, wenn sie in der ePA-FdV-Instanz gelöscht wurden.
• Der Nutzer soll die Möglichkeit haben, Push-Notifications auch von Endgeräten zu lesen, die nicht für Push-Notifications registriert wurden (z.B. Desktop FdV).
Die Verschlüsselung im Aktensystem erfolgt mit einem aktenindividuellen Schlüssel, der nur über eine VAU zugreifbar ist.
Die Benachrichtigungen werden nach 3 Monaten automatisch im Aktensystem gelöscht.
11 changes: 11 additions & 0 deletions docs/config.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
// asciidoc settings for DE (German)
// ==================================
:imagesdir: ../images
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
:toc: macro
:toclevels: 3
:toc-title: Inhaltsverzeichnis
55 changes: 55 additions & 0 deletions docs_sources/concept-source.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
= Notification Management image:gematik_logo.png[width=150, float="right"]
include::./config-source.adoc[]

toc::[]

== Konzept
=== Architektur
An der Umsetzung des Notification Managements sind folgende Komponenten und Services beteiligt:

image:services-landscape.png[width=50%]

• Push Notification Service: Der Service im ePA-Aktensystem zur Verwaltung der Push-Notifications. Der Service erstellt Push- Notifications für abonnierte Ereignisse und übermittelt diese an das zuständige Push Gateway. Der Push Notification Service bietet Schnittstellen für Versicherte/Vertreter zur Registrierung und Konfiguration von Pushern. Ein Pusher bezieht sich auf eine ePA-FdV-Instanz und ist eine Konfiguration im Aktensystem, in der die Informationen zur Adressierung der Push- Notifications hinterlegt werden (u.a. das zu nutzende Push Gateway, Schlüssel zur Verschlüsselung von Nachrichteninhalten). Der Kontoinhaber kann für beliebig viele Endgeräte Pusher in seinem Konto hinterlegen. Genauso kann ein Vertreter beliebig viele Pusher für das Konto des Versicherten hinterlegen.

image:kontos.png[width=50%]

• Push Gateway: Das Push Gateway besitzt einen anwendungsübergreifenden Endpunkt, an den Push-Notifications übermittelt werden. Das Push Gateway leitet die Informationen der Push- Notification an den Push Provider. Das Push Gateway wird vom Hersteller des ePA-FdV bereitgestellt.
• Push Provider: Der Push Provider ist ein Service des Herstellers des mobilen Betriebssystems. Der Push Provider sendet Notifications an App-Instanzen auf Endgeräten der Nutzer.
• ePA-FdV-Instanz: Die ePA-FdV-Instanz ist ein auf einem mobilen Endgerät installiertes ePA-FdV. Push- Notifications werden für eine ePA-FdV-Instanz registriert und an diese ePA-FdV-Instanz gesendet.
Die Verbindungen zwischen Push Gateway und Aktensystem sind beidseitig authentisiert und verschlüsselt.

=== Registrierung einer ePA-FdV-Instanz
Damit eine ePA-FdV-Instanz Push-Notifications empfangen kann, muss diese zunächst beim Push-Provider sowie im Aktensystem registriert werden.

image:push-notification-registration.png[width=50%]

1. Die ePA-FdV-Instanz registriert sich am Push Provider und erhält ein App Token, welches die ePA-FdV-Instanz eindeutig identifiziert.
2. In der ePA-FdV-Instanz wird ein asymmetrisches Schlüsselpaar (push_pubK, push_privK) generiert und im Endgerät sicher gespeichert.
3. Der Nutzer meldet sich am Aktensystem an und registriert die ePA-FdV-Instanz am Push Notification Service für ein Aktenkonto als einen Pusher. Teil der Registrierungsdaten sind das App Token, die app_id, die Adresse des Push Gateways sowie der öffentliche Schlüssel push_pubK. Die app_id und die Adresse des Push Gateways sind im ePA-FdV durch den Hersteller hinterlegt worden.

=== Versenden von Push-Notifications
Die folgende Abbildung veranschaulicht den Ablauf, wenn ein Ereignis in einem Konto eintritt, für welches Push-Benachrichtigungen gesendet werden sollen (z.B. wenn ein Nutzer ein neues Dokument einstellt):

image:push-notification-send.png[width=50%]

1. Der Push Notification Service des Aktensystems führt folgende Schritte durch
a. Generieren einer eindeutigen EventID
b. Erzeugen des Nachrichteninhalts = („ePA“, Kontonummer, EventDetails). Die EventDetails sind spezifisch für das Event. Da das ePA-FdV Push-Benachrichtigungen von mehreren Anwendungen erhalten kann, signalisiert der konstante Wert „ePA“ dem ePA-FdV in Schritt 6, dass es sich um eine Push-Benachrichtigung bzgl. der Anwendung ePA handelt. Die Kontonummer wird aufgenommen, da auch Vertreter Push-Notifications für das Konto der zu vertretenden Versicherten erhalten können und sie in der Push-Notification erkennen können müssen, auf welches Konto sich die Benachrichtigung bezieht. Dem Nachrichteninhalt wird zur Verschleierung der Länge der Nachricht ein Zufallswert ergänzt (Encoding).
c. Das Paar (EventID, Nachrichteninhalt) wird verschlüsselt im Aktensystem persistiert.
2. Für jeden im Aktenkonto registrierten Pusher p, der für das Ereignis abonniert ist, wird eine Push-Benachrichtigung Norification_p mit folgenden Inhalten erzeugt:
a. content = Nachrichteninhalt aus 1b verschlüsselt mit dem push_pubK des Pushers p. Das Chiffrat wird mit „ePA“ gekennzeichnet. Dies erlaubt dem Push Gateway eine Priorisierung nach Anwendungen.
b. devices = (app_id, App Token)
c. event_id = EventID
3. Für jeden Pusher p wird die Push-Benachrichtigung Notification_p an das Push Gateways des Pushers p übermittelt.
4. Das Push Gateway entfernt in der erhaltenen Notification_p die Kennzeichnung „ePA“ am Chiffrat des Nachrichteninhalts und übermittelt die angepasste Push-Benachrichtigung Notification‘_p an den Push Provider.
5. Der Push-Provider sendet die Notification an die zum App Token gehörende ePA-FdV-Instanz.
6. Die ePA-FdV-Instanz entschlüsselt den Nachrichteninhalt mit dem privaten Schlüssel push_privK und zeigt dem Nutzer den Nachrichteninhalt geeignet an.
Bei Bedarf kann sich der Nutzer am Aktenkonto anmelden, um sich z.B. ein eingestelltes Dokument anzusehen.

== Zugriff auf Push-Notifications im Aktensystem
Die Nachrichteninhalte der Push-Benachrichtigungen werden im Aktensystem verschlüsselt gespeichert (vgl. Schritt 1c im Abschnitt „Versenden von Push-Notifications“). Dies erfolgt aus mehreren Gründen:
• Es ist nicht garantiert, dass jede Push-Notification an der ePA-FdV-Instanz ankommt.
• Der Nutzer soll die Möglichkeit haben, Push-Notifications auch noch lesen zu können, wenn sie in der ePA-FdV-Instanz gelöscht wurden.
• Der Nutzer soll die Möglichkeit haben, Push-Notifications auch von Endgeräten zu lesen, die nicht für Push-Notifications registriert wurden (z.B. Desktop FdV).
Die Verschlüsselung im Aktensystem erfolgt mit einem aktenindividuellen Schlüssel, der nur über eine VAU zugreifbar ist.
Die Benachrichtigungen werden nach 3 Monaten automatisch im Aktensystem gelöscht.
11 changes: 11 additions & 0 deletions docs_sources/config-source.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
// asciidoc settings for DE (German)
// ==================================
:imagesdir: ../images
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
:toc: macro
:toclevels: 3
:toc-title: Inhaltsverzeichnis
Binary file added images/Gematik_Logo_Blue.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/Gematik_Logo_Flag.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/Gematik_g_Blue.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/gematik_logo.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/gematik_logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/kontos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/push-notification-registration.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/push-notification-send.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/services-landscape.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
67 changes: 67 additions & 0 deletions resources/scripts/build_with_replace_includes.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
#!/bin/bash
echo "Start building source files"

# check prerequisites
required_asciidoctor_version="2.0.20"
actual_asciidoctor_version=$(asciidoctor --version)
if ! grep -q "$required_asciidoctor_version" <<<"$actual_asciidoctor_version"; then
echo "Incorrect asciidoctor version. Expected $required_asciidoctor_version but found $actual_asciidoctor_version"
exit 1
fi

required_asciidoctor_diagram_version="2.2.14"
actual_asciidoctor_diagram_version=$(gem list | grep "asciidoctor-diagram (")
if ! grep -q "$required_asciidoctor_diagram_version" <<<"$actual_asciidoctor_diagram_version"; then
echo "Incorrect asciidoctor diagram version. Expected $required_asciidoctor_diagram_version but found $actual_asciidoctor_diagram_version"
exit 1
fi

# STAGE_1: creates images from the puml files and will store them in /puml/images

# prepare
cd "$(dirname "$0")" || exit
# rm ../../images/puml_*

# loop through all puml files and create the image
for filename in $(find ../../puml -name '*.puml'); do

filebase=$(basename -- "$filename") # test.adoc
name="${filebase%.*}" # test

if ! git diff --quiet -- "$filename"; then
echo "$filebase has been modified. Creating Puml"

pumlPath=../puml/${name}.puml
newFileRoot=../puml/${name}
newFileName=${newFileRoot//-source/}
echo "Creating Puml ${name}"

tempAdocFile=../../docs_sources/${name}.adoc

# creates a temporary adoc file in order to render with asciidoctor-diagram
touch ${tempAdocFile}
echo "[plantuml, target=../../images/puml_${name}, format=png]
....
include::${pumlPath}[]
...." >${tempAdocFile}
asciidoctor -r asciidoctor-diagram -o ../puml/$newFileName ../../docs_sources/${name}.adoc
rm ../../docs_sources/${name}.adoc
fi

done

# cleanup temp files
if [ -d "../puml" ]; then
rm -r ../puml
fi

# STAGE_2 this creates new adoc files in /docs/resources

for filename in $(find ../../docs_sources -name '*.adoc'); do
newFileName=${filename//-source/}
newFileName=${newFileName//_sources/}
asciidoctor-reducer $filename -o $newFileName -a allow-uri-read
done

# Echo that the process is finished
echo "Finished building source files"

0 comments on commit 4c6fbe7

Please sign in to comment.