Skip to content

Commit

Permalink
Merge branch 'main' into fix-concept-typos
Browse files Browse the repository at this point in the history
  • Loading branch information
@Hendrejvr
Hendrejvr authored Nov 19, 2024
2 parents 2fb275f + ab84edf commit ff825f3
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 5 deletions.
7 changes: 5 additions & 2 deletions docs/concept.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,16 +73,19 @@ Ganz ähnlich wie bei vielen Messaging-Anwendungen werden die verwendeten Schlü

Der Fachdienst erhält ein ISS und einen Zeitstempel von dessen Erzeugung von dem FdV bei der Registrierung. Mittels einer "Hashed Message Authentication Code (HMAC)-based key derivation function" (HKDF) [RFC-5869] werden per `HKDF(ISS, info="<Jahr>-<Monat>")` zwei Werte abgeleitet:

- Ein Geheimnis für den Monat und Jahr des Zeitstempels (`shared-secret-Jahr-Monat`)
- ein AES/GCM-Schlüssel für den Monat und Jahr des Zeitstempels (`AES/GCM-Schlüssel-Jahr-Monat`).
1. Ein Geheimnis für den Monat und Jahr des Zeitstempels (`shared-secret-Jahr-Monat`)
2. ein AES/GCM-Schlüssel für den Monat und Jahr des Zeitstempels (`AES/GCM-Schlüssel-Jahr-Monat`).

Diese beiden Werte werden im Fachdienst sicher gespeichert und das ISS wird im Fachdienst gelöscht.

==== Beispiel für einen Austausch im Oktober 2023: image:{Status_InReview}[]

Das ISS sei zufällig erzeugt gleich (hexdump) `f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2`. Dann ergibt `HKDF(ISS, info="2023-10", L=64) = (hexdump) 185fed66ea5cabbe00147bbd298b5dab0ed41b57ab254d35897b3a4504306e3b3b4adcd58dea98db8e9cb0f5763fcd04fe932d67926cc04b20ba2a2f304ffff9`. Die ersten 32 Byte (256 Bit) sind das `shared-secret-2023-10` gleich (hexdump) `185fed66ea5cabbe00147bbd298b5dab0ed41b57ab254d35897b3a4504306e3b` und die letzten 32 Byte sind der `AES/GCM-Schlüssel-2023-10` ist gleich (hexdump) `3b4adcd58dea98db8e9cb0f5763fcd04fe932d67926cc04b20ba2a2f304ffff9`.

Soll im Oktober 2023 eine Benachrichtigung kryptographisch gesichert werden, um sie an das E-Rezept-FdV zu versenden, dann wird der Schlüssel `AES/GCM-Key-2023-10` dafür verwendet. Soll im November 2023 eine Benachrichtigung gesichert werden, so muss per `HKDF(shared-secret-2023-10, info="2023-11")` wieder ein Geheimnis -- diesmal für November 2023 -- und ein neuer AES/GCM-Schlüssel abgeleitet werden. `shared-secret-2023-11 = (hexdump) 0c8662d90b04818afb317406fe7fcfcf8d103cd9bc6ad7847890d28620e85ec3`, `AES/GCM-Schlüssel-2023-11 = (hexdump) 39aa5dacd538f53f4b956d84c9b8f2e26933274d160b9fd1a263a27681c6331b`

Alle `shared-secret-Jahr-Monat` und alle AES/GCM-Schlüssel-Jahr-Monat, die älter sind als zwei Monate werden, sowohl im Notification Service als auch im E-Rezept-FdV gelöscht, jedoch niemals das jüngste noch verfügbare (auch wenn es älter als zwei Monate ist). Der fachliche Hintergrund von "zwei Monaten" ist, dass sichergestellt sein muss, dass falls der E-Rezept-FD die Benachrichtigung Sekunden vor Monatsende erstellt, und diese im E-Rezept-FdV erst nach einigen Sekunden dann im Folgemonat empfangen werden, die Entschlüsselung im E-Rezept-FdV immer noch möglich sein muss.

Sollte erst im Januar 2024 die nächste Benachrichtigung gesendet werden, so muss die Ableitung für `2023-12` erzeugt werden und darauf basierend anschließend die Ableitung für `2024-01`. Anschließend werden die Ableitungs- und Schlüsseldaten für `2023-11`` gelöscht. Die Schlüsseldaten für `2024-01` werden für die kryptographische Sicherung verwendet.

Somit erreicht man das Ziel, dass bei Kompromittierung eines `AES/GCM-Jahr-Monat-Schlüssels` nur die Benachrichtigungen der letzten zwei Monate entschlüsselt werden können.
Expand Down
8 changes: 6 additions & 2 deletions docs_sources/concept-source.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ Die anderen sind Fachdienst oder Push-Provider spezifisch.

Der Benachrichtigungsinhalt einer jeden Benachrichtigung wird mittels eines Authenticated-Encryption-Verfahrens verschlüsselt (AES/GCM), sodass der Inhalt der Benachrichtigung nicht von Dritten eingesehen oder veränderten werden kann.


Wenn sich eine FdV-Installation beim Fachdienst für Benachrichtigungen registriert, erzeugt die App ein initiales gemeinsames Geheimnis (`initial-shared-secret` (`ISS`)) und überträgt dieses kryptographisch gesichert an den Fachdienst.

Dieses gemeinsame Geheimnis ist die Grundlage der kryptographischen Sicherung des Benachrichtigungsinhaltes. Die Benachrichtigung wird vom Fachdienst mit verschlüsseltem Benachrichtigungsinhalt über das Push Gateway und den Push Provider an die FdV-Installation übermittelt.
Expand All @@ -59,16 +60,19 @@ Ganz ähnlich wie bei vielen Messaging-Anwendungen werden die verwendeten Schlü

Der Fachdienst erhält ein ISS und einen Zeitstempel von dessen Erzeugung von dem FdV bei der Registrierung. Mittels einer "Hashed Message Authentication Code (HMAC)-based key derivation function" (HKDF) [RFC-5869] werden per `HKDF(ISS, info="<Jahr>-<Monat>")` zwei Werte abgeleitet:

- Ein Geheimnis für den Monat und Jahr des Zeitstempels (`shared-secret-Jahr-Monat`)
- ein AES/GCM-Schlüssel für den Monat und Jahr des Zeitstempels (`AES/GCM-Schlüssel-Jahr-Monat`).
1. Ein Geheimnis für den Monat und Jahr des Zeitstempels (`shared-secret-Jahr-Monat`)
2. ein AES/GCM-Schlüssel für den Monat und Jahr des Zeitstempels (`AES/GCM-Schlüssel-Jahr-Monat`).

Diese beiden Werte werden im Fachdienst sicher gespeichert und das ISS wird im Fachdienst gelöscht.

==== Beispiel für einen Austausch im Oktober 2023: image:{Status_InReview}[]

Das ISS sei zufällig erzeugt gleich (hexdump) `f2ca1bb6c7e907d06dafe4687e579fce76b37e4e93b7605022da52e6ccc26fd2`. Dann ergibt `HKDF(ISS, info="2023-10", L=64) = (hexdump) 185fed66ea5cabbe00147bbd298b5dab0ed41b57ab254d35897b3a4504306e3b3b4adcd58dea98db8e9cb0f5763fcd04fe932d67926cc04b20ba2a2f304ffff9`. Die ersten 32 Byte (256 Bit) sind das `shared-secret-2023-10` gleich (hexdump) `185fed66ea5cabbe00147bbd298b5dab0ed41b57ab254d35897b3a4504306e3b` und die letzten 32 Byte sind der `AES/GCM-Schlüssel-2023-10` ist gleich (hexdump) `3b4adcd58dea98db8e9cb0f5763fcd04fe932d67926cc04b20ba2a2f304ffff9`.

Soll im Oktober 2023 eine Benachrichtigung kryptographisch gesichert werden, um sie an das E-Rezept-FdV zu versenden, dann wird der Schlüssel `AES/GCM-Key-2023-10` dafür verwendet. Soll im November 2023 eine Benachrichtigung gesichert werden, so muss per `HKDF(shared-secret-2023-10, info="2023-11")` wieder ein Geheimnis -- diesmal für November 2023 -- und ein neuer AES/GCM-Schlüssel abgeleitet werden. `shared-secret-2023-11 = (hexdump) 0c8662d90b04818afb317406fe7fcfcf8d103cd9bc6ad7847890d28620e85ec3`, `AES/GCM-Schlüssel-2023-11 = (hexdump) 39aa5dacd538f53f4b956d84c9b8f2e26933274d160b9fd1a263a27681c6331b`

Alle `shared-secret-Jahr-Monat` und alle AES/GCM-Schlüssel-Jahr-Monat, die älter sind als zwei Monate werden, sowohl im Notification Service als auch im E-Rezept-FdV gelöscht, jedoch niemals das jüngste noch verfügbare (auch wenn es älter als zwei Monate ist). Der fachliche Hintergrund von "zwei Monaten" ist, dass sichergestellt sein muss, dass falls der E-Rezept-FD die Benachrichtigung Sekunden vor Monatsende erstellt, und diese im E-Rezept-FdV erst nach einigen Sekunden dann im Folgemonat empfangen werden, die Entschlüsselung im E-Rezept-FdV immer noch möglich sein muss.

Sollte erst im Januar 2024 die nächste Benachrichtigung gesendet werden, so muss die Ableitung für `2023-12` erzeugt werden und darauf basierend anschließend die Ableitung für `2024-01`. Anschließend werden die Ableitungs- und Schlüsseldaten für `2023-11`` gelöscht. Die Schlüsseldaten für `2024-01` werden für die kryptographische Sicherung verwendet.

Somit erreicht man das Ziel, dass bei Kompromittierung eines `AES/GCM-Jahr-Monat-Schlüssels` nur die Benachrichtigungen der letzten zwei Monate entschlüsselt werden können.
Expand Down
49 changes: 48 additions & 1 deletion docs_sources/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,14 +51,61 @@
<img src="images/gematik_logo.png" alt="Gematik Logo">
</div>
</div>
<iframe id="content" name="content" src="" frameborder="0"></iframe>
<iframe id="content" name="content" src="concept/index.html" frameborder="0"></iframe>

<script>
function loadPage(element) {
var links = document.querySelectorAll('#menu a');
links.forEach(link => link.classList.remove('active'));
element.classList.add('active');
}

window.addEventListener('load', function() {
if (window.location.hash && window.location.hash.length > 2) {
var hash = window.location.hash.substring(1).replace('%23', '#');
document.getElementById('content').src = hash;
var links = document.querySelectorAll('#menu a');
links.forEach(link => {
if (hash.startsWith(link.getAttribute('href'))) {
link.classList.add('active');
} else {
link.classList.remove('active');
}
});
}
});

document.getElementById('content').addEventListener('load', function() {
this.contentWindow.addEventListener('hashchange', function() {
console.log("hashchange" + this.location.pathname + this.location.hash);

let path = this.location.pathname + this.location.hash
// escape # from path
path = path.replace('#', '%23');
rootPath = window.location.pathname;
rootPath = rootPath.replace('index.html', '');
path = path.replace(rootPath, '');

if (window.location.hash.substring(1) != path) {
window.location.replace("#" + path);
}
});
});

window.addEventListener('hashchange', function() {
if (window.location.hash && window.location.hash.length > 1) {
var hash = window.location.hash.substring(1).replace('%23', '#');
document.getElementById('content').src = hash;
var links = document.querySelectorAll('#menu a');
links.forEach(link => {
if (hash.startsWith(link.getAttribute('href'))) {
link.classList.add('active');
} else {
link.classList.remove('active');
}
});
}
});
</script>
</body>
</html>

0 comments on commit ff825f3

Please sign in to comment.