diff --git a/docs/details/destination-management.mdx b/docs/details/destination-management.mdx
new file mode 100644
index 0000000000000000000000000000000000000000..c283e4240f23e72d614f102287fbbe9608376747
--- /dev/null
+++ b/docs/details/destination-management.mdx
@@ -0,0 +1,74 @@
+---
+title: Zustellpunktverwaltung
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ApiLink from '@site/src/components/ApiLink';
+
+# Zustellpunktverwaltung
+
+## Bearbeiten eines Zustellpunktes
+
+Für die Aktualisierung eines Zustellpunktes existieren aktuell folgende Endpunkte:
+
+* Vollständige Aktualisierung eines Zustellpunktes: <ApiLink to="/destinations/{destinationId}" withMethod="put" />
+* Partielle Aktualisierung eines Zustellpunktes: <ApiLink to="/destinations/{destinationId}" withMethod="patch" />
+
+Für die Aktualisierung der Schlüssel des Zustellpunktes gibt es folgenden Endpunkt:
+
+* <ApiLink to="/destinations/{destinationId}/keys" withMethod="post"/>
+
+Die Details sind der API-Spec zu entnehmen.
+
+### Beispiele
+
+<Tabs
+ defaultValue="curl"
+ values={[
+ {label: 'curl', value: 'curl',},
+ {label: 'Self-Service-Portal', value: 'ssp',},
+ ]}>
+ <TabItem value="curl" label="foo">
+
+#### Aktualisierung des Verschlüsselungsschlüssels eines Zustellpunktes
+
+```shell
+$ SERVICE_URL=...
+$ JWT_TOKEN=...
+$ DESTINATION_ID=...
+
+# Hinzufügen eines Schlüssels zu einer Destination
+$ curl -X POST \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer $JWT_TOKEN" \
+ --data '{"kty": "RSA", "kid": "new-encryption-key", "alg": "RSA-OAEP-256", "key_ops": ["wrapKey"], "x5c": ["..."], "e": "AQAB", "n": "..."}' \
+ "$SERVICE_URL/destinations/$DESTINATION_ID/keys"
+
+# Setzen der Schlüssel-ID als Verschlüsselungsschlüssel
+$ curl -X PATCH \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer $JWT_TOKEN" \
+ --data '{"encryptionKid": "new-encryption-key"}' \
+ "$SERVICE_URL/destinations/$DESTINATION_ID"
+```
+ </TabItem>
+
+ <TabItem value="ssp">
+
+:::caution Hinweis
+Über das Self-Service-Portal können Zustellpunkte aktuell noch nicht aktualisiert werden.
+:::
+ </TabItem>
+</Tabs>
+
+## Zustellpunkt löschen
+
+Das Löschen von Zustellpunkten kann im Self-Service-Portal durchgeführt werden.
+Ein Zustellpunkt kann nur gelöscht werden, wenn kein Client mit diesem verknüpft ist.
+Durch einen Klick auf die `Destination-ID` in der Zustellpunktverwaltung öffnet sich die Detailansicht für den ausgewählten Zustellpunkt.
+
+<div class="center">
+ <img width="600" alt="Detailansicht Zustellpunkt" src={useBaseUrl('/images/ssp/19-Destination-Detailansicht.png')}/>
+</div>
diff --git a/docs/getting-started/event-log.mdx b/docs/getting-started/event-log.mdx
index b57bb94cf13c26486198321caa4da8a61e590e4a..24498f0621fc3f31a41005e1af6e601a736ea4e4 100644
--- a/docs/getting-started/event-log.mdx
+++ b/docs/getting-started/event-log.mdx
@@ -15,12 +15,12 @@ Für die Übermittlung von Einreichungen zwischen Sendern und Empfängern soll g
Zudem sollen diese Nachweise außerhalb der Submission API und der damit verbundenen Systeme genutzt werden können, damit diese Dritten einfach zur Verfügung gestellt werden können.
SETs erfüllen diese Anforderungen durch folgende Merkmale:
-- Für jedes SET wird ein eindeutiger Herausgeber definiert (`Iss`)
-- Jedes SET kann eindeutig einem konkreten fachlichen Kontext zugeordnet werden (`Sub`)
+- Für jedes SET wird ein eindeutiger Herausgeber definiert (`iss`)
+- Jedes SET kann eindeutig einem konkreten fachlichen Kontext zugeordnet werden (`sub`)
- Mehrere SETs aus unterschiedliche fachlichen Kontexten können zu einem gemeinsamen Vorgang zusammengeführt werden (`txn`)
- SETs können für unterschiedliche Ereignisse ausgeprägt werden und innerhalb dieser Ereignisse können Detailinformationen ergänzt werden, die diese Ereignisse näher beschreiben
- Über ein Zeitstempel (`iat`) können diese Ereignisse zudem konkreten Zeitpunkt zugeordnet werden
-- Durch eine Signatur im JWS Format wird sichergestellt, dass alle SETs integritätsgesichert ist und eindeutig dem Schlüsselinhaber als Ersteller zugeordnet werden können.
+- Durch eine Signatur im JWS Format wird sichergestellt, dass alle SETs ihre Integrität erhalten und eindeutig dem Schlüsselinhaber als Ersteller zugeordnet werden können.
Die Nutzung ist aber nicht auf die Klärung von Streitigkeiten zu technischen Übermittlungen beschränkt. SETs können aufgrund dieser Merkmale unter anderem auch für folgende Zwecke genutzt werden:
- Als Auditinstrument, dass bei Prüfungen oder Sicherheitsvorfällen durch Dritte (bspw. Datenschutz- oder Sicherheitsbeauftragte) genutzt wird,
@@ -70,18 +70,18 @@ In der Payload des signierten SET MÃœSSEN die folgenden [standardisierten Felder
| Feld | Inhalt | Erläuterung |
|--------|------------------------------------------------|---------------------------------------------------------------|
-| iss | Id des Token Issuers | Diese Angabe dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für SETs, die vom Zustelldienst ausgestellt sind, wird die Host-Adresse (API-URL) verwendet. Bei SETs von empfangenden Systemen ist die `destinationId`, an der dieser die Submission schickt. |
-| iat | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. |
-| jti | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. |
-| sub | URI, die den Gegenstand des SET identifiziert | Das Subject eines SET ist eine Kombination aus dem Schlüsselwort `submission` und der Id `submissionId` der Resource. |
-| events | JSON-Objekt der Events in diesem Event-Token | Das Objekt "events" beschreibt eine oder mehrere Ereignisse zu einem logischen Sachverhalt bzw. Gesamtereignis, wie bspw. der Versendung einer Einreichung durch den Sender. Dieses Objekt beinhaltet immer zwingend eine URI, die das jeweilige Gesamtereignis eindeutig identifiziert. Das Objekt der URI des Gesamtereignisses ist aktuell leer, kann aber zukünftig weitere Details zu einem Gesamtereignis enthalten. |
-| txn | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. |
+| `iss` | Id des Token Issuers | Diese Angabe dient dazu, um herauszufinden, wer den Token ausgestellt hat. Für SETs, die vom Zustelldienst ausgestellt sind, wird die Host-Adresse (API-URL) verwendet. Bei SETs von empfangenden Systemen ist die `destinationId`, an der dieser die Submission schickt. |
+| `iat` | Timestamp (UNIX-Format) | Zeitpunkt der Ausstellung des SET. |
+| `jti` | UUID des Token | Die JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet. |
+| `sub` | URI, die den Gegenstand des SET identifiziert | Das Subject eines SET ist eine Kombination aus dem Schlüsselwort `submission` und der Id `submissionId` der Resource. |
+| `events` | JSON-Objekt der Events in diesem Event-Token | Das Objekt "events" beschreibt eine oder mehrere Ereignisse zu einem logischen Sachverhalt bzw. Gesamtereignis, wie bspw. der Versendung einer Einreichung durch den Sender. Dieses Objekt beinhaltet immer zwingend eine URI, die das jeweilige Gesamtereignis eindeutig identifiziert. Das Objekt der URI des Gesamtereignisses ist aktuell leer, kann aber zukünftig weitere Details zu einem Gesamtereignis enthalten. |
+| `txn` | URI, die den Vorgang identifiziert | Als "Transaction Identifier" wird die Vorgangsreferenz `caseId` angegeben. |
:::note SET Beispiel
```json title="SET Header"
{
- "typ": "secevent+jwt"
+ "typ": "secevent+jwt",
"alg": "PS512",
"kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980",
}
@@ -213,24 +213,21 @@ boolean verifyZustelldienstSignature(SignedJWT securityEventToken, String keyId)
### Signaturprüfung eines vom empfangenden System ausgestellten SET
-Um die Signatur eines SET zu überprüfen, welches von einem empfangenden System ausgestellt wurde, ist es notwendig, auf den verwendeten Schlüssel zugreifen zu können.
-Die Schlüssel eines empfangenden Systems sind über die Destination in Form eines JSON Web Key (JWK) Sets öffentlich verfügbar.
-Welche Schritte notwendig sind und wie die Prüfung letztendlich durchgeführt wird, wird im Folgenden anhand eines Beispiels beschrieben.
+Um die Signatur eines von einem empfangenden System ausgestellen SET zu überprüfen ist es notwendig, auf den verwendeten Schlüssel zugreifen zu können.
+Der bzw. die Schlüssel sind öffentlich verfügbar und können über die Submission API abgerufen werden.
-:::caution Hinweis
-Der Mechanismus zum Abrufen von kryptografischen Schlüsseln des empfangenden Systems wird sich bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern.
-:::
-
-Als Ausgangslage dient das Token mit dem folgenden Header und der entsprechenden Payload.
-Aus dem Header wird die `kid` benötigt, sowie die `submissionId` aus dem Payload.
-Konkret sind das hier
+#### Ausgangslage: Das SET
+Als Ausgangslage dient das folgende SET.
+Aus dem Header wird die Schlüssel-ID aus dem Feld `kid` benötigt.
+Aus dem Payload benötigen wir das Feld `submissionId`.
+Konkret sind das hier:
- kid: `dd0409e5-410e-4d98-85b6-f81a40b8d980`
- submissionId: `F65FEAB2-4883-4DFF-85FB-169448545D9F`
```json title="SET Header"
{
- "typ": "secevent+jwt"
+ "typ": "secevent+jwt",
"alg": "PS512",
"kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980",
}
@@ -249,10 +246,12 @@ Konkret sind das hier
}
```
+#### Abruf des JWK zur Gültigkeitsprüfung des SET
+
Mit der `submissionId` kann über den Endpunkt <ApiLink to="/submissions/{submissionId}" /> die zugehörige `destinationId` ermittelt werden.
Hier ist das konkret der Wert `92f2f581-c89d-44a5-b834-1fe3f6fa48d5`.
-```http title="Abfrage der Submission"
+```http title="Abfrage der destinationId einer Submission"
GET /submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F
{
"destinationId": "92f2f581-c89d-44a5-b834-1fe3f6fa48d5",
@@ -260,24 +259,33 @@ GET /submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F
}
```
-Über diese kann dann das JWK Set der zugehörigen Destination über ein <ApiLink to="/destinations/{destinationId}" /> abgefragt werden.
-In dem Attribut `publicKeys` ist das JWK Set abgelegt.
-In den darin enthaltenen Schlüsseln kann dann der Schlüssel mit `kid` von oben gesucht und für die Verifikation genutzt werden.
+Mit den zwei Informationen `kid` und `destinationid` kann nun der JWK zur Signaturprüfung abgerufen werden:
-```http title="Abfrage der Destination"
-GET /destinations/92f2f581-c89d-44a5-b834-1fe3f6fa48d5
+```shell title="Beispiel: Abruf des JWK eines Zustellpunktes"
+$ KID=...
+$ SERVICE_URL=...
+$ DESTINATION_ID=...
+$ curl -X GET \
+ "$SERVICE_URL/destinations/$DESTINATION_ID/keys/$KID"
+---
{
- "publicKeys": {
- "keys": [
- // ...
- ]
- },
- // ...
+ "kty": "RSA",
+ "e": "AQAB",
+ "keyops": ["verify"],
+ "x5c": [
+ "LS0tLS1CRUdJTiBDRVJU...jN1NGKzQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo="
+ ],
+ "x5t": "MTg6NTU6RUY6ME...MEM6QzM6ODQ6QjA6MkE6RkMK",
+ "kid": "787f3a1c-7da7-44d7-9b79-9783b1ea9be8",
+ "alg": "RSA-OAEP-256",
+ "n": "sX2DX7rG5BoJd23...FlxHZt8T6ZqjRa1QcFnkq3_M4-tk"
}
```
-Die Verifikation mit dem Schlüssel ist dann ziemlich geradlinig.
-Es wird noch überprüft, ob der Schlüssel den passenden Algorithmus hat und dann die eigentliche Verifikation über die Methode der Bibliothek durchgeführt.
+#### Validierung des SET mit Hilfe des JWK
+
+Die Verifikation des SET mit dem eben abgerufenen JWK ist dann ziemlich geradlinig.
+Es wird zunächst geprüft ob der Schlüssel den passenden Algorithmus hat. Anschließend wird die eigentliche Verifikation durch die Bibliothek durchgeführt.
```java
boolean verifyClientSignature(SignedJWT securityEventToken, String keyId) {
diff --git a/docs/getting-started/receiving/destination.mdx b/docs/getting-started/receiving/destination.mdx
index 5e3b388a1fc41e9f8c3e0ae21affa12b65c1b865..7f310080e6bace15a4be7e5e65738713a1c98dc1 100644
--- a/docs/getting-started/receiving/destination.mdx
+++ b/docs/getting-started/receiving/destination.mdx
@@ -3,163 +3,119 @@ sidebar_position: 3
title: 🚧 Zustellpunkt anlegen
---
-import Tabs from '@theme/Tabs'
-import TabItem from '@theme/TabItem'
+
import useBaseUrl from '@docusaurus/useBaseUrl';
-Um Einreichungen über FIT-Connect zu empfangen, muss zunächst ein Zustellpunkt angelegt werden. Dies wird über das Self-Service-Portal umgesetzt.
+Um Einreichungen über FIT-Connect zu empfangen, muss zunächst ein Zustellpunkt (Destination) angelegt werden.
+Dies wird über das Self-Service-Portal umgesetzt.
:::caution
-In der finalen API wird eine explizite Aktivierung des Zustellpunkts (über die API oder das Self-Service-Portal) notwendig sein, damit sichergestellt werden kann, dass ein API-Client mit dem Scope `subscribe:destination:<id>` für diese destinationId angelegt und technisch empfangsbereit ist.
+
+In der finalen API wird eine explizite Aktivierung des Zustellpunkts (über die API oder das Self-Service-Portal) notwendig sein.
+Damit soll sichergestellt werden, dass ein API-Client mit dem Scope `subscribe:destination:<id>` für diese `destinationId` angelegt und technisch empfangsbereit ist.
Entsprechende organisatorische und technische Hinweise zu Aktivierung werden an dieser Stelle noch ergänzt.
:::
## Zustellpunkt anlegen
-Unter einem Zustellpunkt (Destination) versteht sich ein technisch eindeutig adressierbarer Endpunkt zur Einreichung von Anträgen oder Berichten an die Verwaltung über die FIT-Connect Übermittlungsinfrastruktur.
+Unter einem Zustellpunkt versteht sich ein technisch eindeutig adressierbarer Endpunkt zur Einreichung von Anträgen oder Berichten an die Verwaltung über die FIT-Connect Übermittlungsinfrastruktur.
Jeder Zustellpunkt muss einem Subscriber-API-Client zugeordnet werden.
-Ein Zustellpunkt repräsentiert dabei typischerweise einen Subscriber-Client (Fachverfahren oder virtuelle Poststelle). Es ist jedoch möglich einem empfangenden System (API-Client) multiple Zustellpunkte zuzuordnen.
+Ein Zustellpunkt repräsentiert dabei typischerweise einen Subscriber-Client (Fachverfahren oder virtuelle Poststelle).
+Es ist jedoch möglich einem empfangenden System (API-Client) multiple Zustellpunkte zuzuordnen.
-Über die Destination-Verwaltung lassen sich neue Zustellpunkte anlegen, bereits hinzugefügt Destinations verwalten und auch wieder entfernen.
+Über die Zustellpunktverwaltung lassen sich neue Zustellpunkte anlegen, bereits hinzugefügt Zustellpunkte verwalten und auch wieder entfernen.
-<img width="600" alt="Destinationverwaltung" src={useBaseUrl('/images/ssp/7-Destinationverwaltung.png')} />
+<div class="center">
+ <img width="600" alt="Zustellpunktverwaltung"
+ src={useBaseUrl('/images/ssp/7-Destinationverwaltung.png')}/>
+</div>
-Über den Menüpunkt <mark>Destination hinzufügen</mark> können neue Destinations zu Ihren Konto hinzugefügt werden.
+Über den Menüpunkt `Zustellpunkt hinzufügen` können neue Zustellpunkte zu Ihrem Konto hinzugefügt werden.
-<img width="800" alt="Formular zum Anlegen einer neuer Destination" src={useBaseUrl('/images/ssp/8-Destination-hinzufuegen.png')} />
+<div class="center">
+ <img width="800" alt="Formular zum Anlegen eines neuen Zustellpunktes"
+ src={useBaseUrl('/images/ssp/8-Destination-hinzufuegen.png')}/>
+</div>
Ein Zustellpunkt benötigt zur Erstellung eine Vielzahl von Angaben, die sich im Wesentlichen auf Kontaktdaten, technische Angaben und Service aufteilen.
-Unter den unter dem Punkt Kontaktdaten abgefragten Informationen werden Details zur Antragempfangenden Instanz erfasst. Sämtliche Felder sind dabei aktuell noch Fließtext. Unter der Funktionspostfachadresse wird eine E-Mail-Adresse erwartet.
+Unter den unter dem Punkt Kontaktdaten abgefragten Informationen werden Details zum antragsempfangenden System erfasst.
+Sämtliche Felder sind dabei aktuell noch Fließtext.
+Unter der Funktionspostfachadresse wird eine E-Mail-Adresse erwartet.
Unter den unter dem Punkt „Technische Angaben“ abgefragten Informationen werden neben einer Callback-URL auch öffentliche Schlüssel zur Signaturprüfung und Verschlüsselung erwartet.
-Beide Schlüssel müssen im JSON-Format vorliegen und den Anforderderungen aus [Vorgaben für kryptographische Verfahren](https://docs.fitko.de/fit-connect/docs/details/crypto) entsprechen.
-Ein Tool und die zugehörige Anleitung um schnell und einfach passende Schlüssel für Testzwecke zu generieren finden Sie unter [Tool zur Erstellung von JSON Web Keys](https://docs.fitko.de/fit-connect/docs/details/jwk-creation/).
+Beide Schlüssel müssen im JSON-Format vorliegen und den Anforderungen aus
+[Vorgaben für kryptographische Verfahren](https://docs.fitko.de/fit-connect/docs/details/crypto) entsprechen.
+Ein Tool und die zugehörige Anleitung um schnell und einfach passende Schlüssel für Testzwecke zu generieren finden Sie unter
+[Tool zur Erstellung von JSON Web Keys](https://docs.fitko.de/fit-connect/docs/details/jwk-creation/).
Unter den unter dem Punkt „Service“ abgefragten Informationen werden ein eindeutiger Leistungsindikator, eine Region aus der eine Anfrage zulässig ist sowie die URI des verwendeten Fachschemas erwartet.
-<img width="800" alt="Destination mit Beispieldaten befüllt" src={useBaseUrl('/images/ssp/9-Destination-hinzufuegen-befuellt.png')} />
+<div class="center">
+ <img width="800" alt="Zustellpunkt mit Beispieldaten befüllt"
+ src={useBaseUrl('/images/ssp/9-Destination-hinzufuegen-befuellt.png')}/>
+</div>
-Wurden alle Informationen und Schlüssel in korrekter Form übergeben wird die Destination erstellt.
+Wurden alle Informationen und Schlüssel in korrekter Form übergeben wird der Zustellpunkt erstellt.
-<img width="600" alt="Destination wurde erfolgreich angelegt" src={useBaseUrl('/images/ssp/11-Destination-erfolgreich-angelegt.png')} />
+<div class="center">
+ <img width="600" alt="Destination wurde erfolgreich angelegt"
+ src={useBaseUrl('/images/ssp/11-Destination-erfolgreich-angelegt.png')}/>
+</div>
-:::caution Wichtig!
+:::caution
Alle neu angelegten Zustellpunkte haben nach der Erstellung den Status `created` und sind für sendende Systeme nicht sichtbar und adressierbar.
Hiermit soll verhindert werden, dass Einreichungen an den Zustellpunkt übersendet werden, ohne das ein empfangsbereites System vorliegt, dass die Einreichungen für diesen Zustellpunkt an der API abrufen kann.
-Daher ist zwingend vor der Aktivierung eines Zustellpuntes [ein API-Client anzulegen](https://docs.fitko.de/fit-connect/docs/account) und diesem Zustellpunkt zuzuweisen (siehe nächster Abschnitt).
+Daher ist zwingend vor der Aktivierung eines Zustellpunktes [ein API-Client anzulegen](https://docs.fitko.de/fit-connect/docs/account) und diesem Zustellpunkt zuzuweisen (siehe nächster Abschnitt).
:::
-## Zugriff auf Zustellpunkte einrichten {#add-destination-to-client}
-Clients vom Typ **Subscriber** können Destinations zugeordnet werden. Der Client empfängt dann die für den Zustellpunkt bestimmten Anfragen. Durch einen Klick auf die <mark>Client-ID</mark> eines Clients vom Typ **Subscriber** in der Client-Verwaltung öffnet sich die Detailansicht.
+## Zugriff auf Zustellpunkte einrichten
+Clients vom Typ **Subscriber** können Zustellpunkten zugeordnet werden.
+Der Client empfängt dann die für den Zustellpunkt bestimmten Anfragen.
+Durch einen Klick auf die Client-ID eines Clients vom Typ **Subscriber** in der Client-Verwaltung öffnet sich die Detailansicht.
-<img width="600" alt="Destination zu einem Client hinzufügen" src={useBaseUrl('/images/ssp/16-Destination-zu-Client-hinzufuegen.png')} />
+<div class="center">
+ <img width="600" alt="Zustellpunkte zu einem Client hinzufügen"
+ src={useBaseUrl('/images/ssp/16-Destination-zu-Client-hinzufuegen.png')}/>
+</div>
-Unter Destinations werden alle verfügbaren oder bereits verknüpften Destinations angezeigt. Durch aktivieren des Kontrollkästchens vor der gewünschten Destinations öffnet sich der Bestätigungsdialog, um dem Client Zugriff auf die gewählte Destination zu geben.
+Unter `Zustellpunkte` werden alle verfügbaren oder bereits verknüpften Zustellpunkte angezeigt.
+Durch Aktivieren des Kontrollkästchens vor dem Zustellpunkt öffnet sich der Bestätigungsdialog, um dem Client Zugriff auf den Zustellpunkt zu geben.
-<img width="600" alt="Bestätigungsdialog um eine Destination zu einem Client hinzufügen" src={useBaseUrl('/images/ssp/16b-Destination-zu-Client-hinzufuegen.png')} />
+<div class="center">
+ <img width="600" alt="Bestätigungsdialog um einen Zustellpunkt zu einem Client hinzufügen"
+ src={useBaseUrl('/images/ssp/16b-Destination-zu-Client-hinzufuegen.png')}/>
+</div>
-Im Anschluss wird die hinzufügte Destination durch ein Häkchen im Kontrollkästchen gekennzeichnet. Zusätzlich wurde die Destination im Scope des Clients hinzugefügt.
+Im Anschluss wird der hinzugefügte Zustellpunkt durch ein Häkchen im Kontrollkästchen gekennzeichnet.
+Zusätzlich wurde der Zustellpunkt im Scope des Clients hinzugefügt.
-<img width="600" alt="Aktualisierter Scope des Clients" src={useBaseUrl('/images/ssp/16c-Destination-zu-Client-hinzufuegen.png')} />
+<div class="center">
+ <img width="600" alt="Aktualisierter Scope des Clients"
+ src={useBaseUrl('/images/ssp/16c-Destination-zu-Client-hinzufuegen.png')}/>
+</div>
## Zugriff auf Zustellpunkte entfernen
-Bei Clients vom Typ **Subscriber** können ihnen zugeordnete Destinations auch wieder entfernt werden. Durch einen Klick auf das derzeit noch aktive und mit einem Häkchen gekennzeichnete Kontrollkästchen der zu entfernenden Destination, öffnet sich ein Kontrolldialog, in dem das Löschen bestätigt werden muss.
-
-<img width="600" alt="Kontrolldialog zum Entfernen des Zugriffs auf eine Destination" src={useBaseUrl('/images/ssp/17-Destination-vom-Client-entfernen.png')} />
-
-Im Anschluss wird die entfernte Destination nicht länger durch ein Häkchen im Kontrollkästchen gekennzeichnet. Zusätzlich wurde die Destination im Scope des Clients entfernt.
-
-<img width="600" alt="Aktualisierter Scope des Clients" src={useBaseUrl('/images/ssp/17b-Destination-vom-Client-entfernen.png')} />
-
-## Zustellpunkt bearbeiten und aktivieren
-
-Sobald ein Zustellpunkt über das Self-Service-Portal erstellt wurde und eine Destination-ID für diesen Zustellpunkt vergeben und dem Nutzer zugeordnet wurde, kann dieser entweder programmatisch über die API oder über das Self-Service-Portal bearbeitet werden.
-Für die Bearbeitung über die API sind folgende Voraussetzung zu erfüllen:
-- Die Software für die Bearbeitung des Zustellpunkts muss als API-Client angelegt und der Zugriff auf den angelegten Zustellpunkt [im Self-Service-Portal konfiguriert sein](#add-destination-to-client).
-
-<Tabs
- defaultValue="ssp"
- values={[
- { label: 'Self-Service-Portal', value: 'ssp', },
- { label: 'curl', value: 'curl', },
- ]
-}>
-<TabItem value="curl">
-
-**TO-DO: Lösungsneutrale Beschreibung der im Zustellpunkt zu hinterlegenden Informationen**
-
-**TO-DO: Bearbeitung über die API gemäß der API V.1 Spec überarbeiten**
-
-```bash
-$ export SERVICE_URL=...
-$ export JWT_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA
-$ curl \
- -H "Authorization: Bearer $JWT_TOKEN" \
- -H "Content-Type: application/json" \
- --data "@./myDestination.json" \
- -X POST $SERVICE_URL/destinations
-> {
- "destinationId": "7881dba9-4055-4854-8b6d-11ea5b7f3047",
- "contactInformation": {
- "legalName": "Batman Ltd.",
- "address": "Batmansq. 31, 10000 Berlin, DE",
- "phone": "+49111111111",
- "email": "max.mustermann@musterstadt.de",
- "unit": "Referat Gotham"
- },
- "services": [
- {
- "identifier": "urn:xoev-de:xfall:standard:fim-s00000000009_1.0.0",
- "submissionSchemas": [
- "schemaUri": "https://schema.fitko.de/fim/s00000000009_1.0.0.schema.json",
- "mimeType": "application/json"
- ],
- "regions": ["DE13441111"]
- }
- ],
- "callback": "https://example.com/callback",
- "encryptionKid": "my-key-id-0xfff",
- "publicKeys": {
- "keys": [
- {
- "kty": "RSA",
- "kid": "my-key-id-0xfff",
- "alg": "RSA-OAEP-256",
- "key_ops": ["wrapKey"],
- "x5c": [
- "MIID2DCCAkmgAwIBAgIGAXo...w73tI1m1+QAU/6chTyAWvxvATklto2KV+i36lw=="
- ],
- "e": "AQAB",
- "n": "hwAvWxlwpz7sH...2f0u3Ktf1tzzeGTl4UVnUrE35eXF"
- }
- ]
- }
- }
-```
-
-</TabItem>
-
-<TabItem value="ssp">
-
-:::caution Hinweis
-Die Funktionalität zum bearbeiten von Zustellpunkten über das Self-Service-Portal wird derzeit noch umgesetzt.
-:::
-
-</TabItem>
-
-</Tabs>
-## Zustellpunkt löschen
+Bei Clients vom Typ **Subscriber** können zugeordnete Zustellpunkte auch wieder entfernt werden.
+Durch einen Klick auf das derzeit noch aktive und mit einem Häkchen gekennzeichnete Kontrollkästchen des zu entfernenden Zustellpunktes, öffnet sich ein Kontrolldialog, in dem das Löschen bestätigt werden muss.
-Durch einen Klick auf die <mark>Destination-ID</mark> in der Destination-Verwaltung öffnet sich die Detailansicht für den ausgewälten Zustellpunkt.
+<div class="center">
+ <img width="600" alt="Kontrolldialog zum Entfernen des Zugriffs auf einen Zustellpunkt"
+ src={useBaseUrl('/images/ssp/17-Destination-vom-Client-entfernen.png')}/>
+</div>
-<img width="600" alt="Destination Detailansicht" src={useBaseUrl('/images/ssp/19-Destination-Detailansicht.png')} />
+Im Anschluss wird der entfernte Zustellpunkt nicht länger durch ein Häkchen im Kontrollkästchen gekennzeichnet.
+Zusätzlich wurde der Zustellpunkt im Scope des Clients entfernt.
-Durch einen Klick auf <mark>löschen</mark> öffnet sich ein Kontrolldialog, in dem das Löschen der Destination bestätigt werden muss.
+<div class="center">
+ <img width="600" alt="Aktualisierter Scope des Clients"
+ src={useBaseUrl('/images/ssp/17b-Destination-vom-Client-entfernen.png')}/>
+</div>
-<img width="600" alt="Kontrolldialog zum Löschen einer Destination" src={useBaseUrl('/images/ssp/20-Destination-loeschen.png')} />
+## Bearbeiten und Löschen von Zustellpunkten
-Hierbei ist zu Beachten, dass Destination nur dann gelöscht werden können, wenn sie mit keinem Client verknüpft sind.
+Weiterführende Informationen zum Bearbeiten und Löschen von Zustellpunkten finden sich im Artikel
+[Verwalten eines Zustellpunktes](/docs/details/destination-management).
diff --git a/docs/getting-started/sending/encrypt.mdx b/docs/getting-started/sending/encrypt.mdx
index 5cbd04c6bd7dd2bca88c1729321c8ae4261295e3..fde30879e423ae56383c8768042bfa55ab525fa2 100644
--- a/docs/getting-started/sending/encrypt.mdx
+++ b/docs/getting-started/sending/encrypt.mdx
@@ -6,11 +6,27 @@ sidebar_position: 4
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
-Viele Daten, die über den Zustelldienst übertragen werden, enthalten schützenswerte Informationen und müssen verschlüsselt werden. Eine Übertragung über FIT-Connect besteht aus einem Metadatensatz, optionalen Fachdaten und beliebig vielen (0-∞) Dokumenten (Anlagen). Die Metadaten, Fachdaten und Anlagen werden gemäß dem Standard [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) verschlüsselt. Als Datenformat für die Übertragung wird die sogenannte [JWE-Compact Serialisierung](https://tools.ietf.org/html/rfc7516#section-7.1) verwendet. Alle angehängten Dokumente müssen als Binärdateien und nicht als Strings kodiert verschlüsselt werden.
+Über FIT-Connect versendete Daten sind oft schützenswert und müssen daher verschlüsselt werden.
-Gegeben, dass ein öffentlicher Teil eines JWK eines Zustellpunktes [vorhanden ist](./get-destination.mdx#informationen-des-zustellpunktes-erhalten), können mit diesem Daten für diesen Zustellpunkt verschlüsselt werden. Ein Beispiel für den öffentlichen Teil eines JWK ist unten aufgeführt.
+Eine Übertragung über FIT-Connect besteht aus
-```json
+* einem Metadatensatz
+* einem Fachdatensatz (optional)
+* beliebig vielen Anlagen (optional)
+
+Alle drei Datensatzarten müssen mit [JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516) verschlüsselt und mit [JWE-Compact Serialisierung](https://tools.ietf.org/html/rfc7516#section-7.1) serialisiert werden.
+Dokumente müssen als Binärdateien und nicht als Zeichenketten kodiert verschlüsselt werden.
+
+Der [vorher abgerufene Zustellpunkt](./get-destination.mdx#informationen-des-zustellpunktes-erhalten) beinhaltet die Schlüssel-ID des Verschlüsselungsschlüssels unter dem Feld `encryptionKid`.
+Damit können wir den JWK des Zustellpunktes abrufen um Daten zu verschlüsseln.
+
+```shell title="Beispiel: Abruf des JWK eines Zustellpunktes"
+$ KID=... # Wert des Feldes `encryptionKid`
+$ SERVICE_URL=...
+$ DESTINATION_ID=...
+$ curl -X GET \
+ "$SERVICE_URL/destinations/$DESTINATION_ID/keys/$KID"
+---
{
"kty": "RSA",
"e": "AQAB",
@@ -25,19 +41,26 @@ Gegeben, dass ein öffentlicher Teil eines JWK eines Zustellpunktes [vorhanden i
}
```
-## Überprüfen öffentlicher Schlüssel (Zertifikatsprüfung)
+Mit diesem Schlüssel könnten jetzt die oben genannten Datenssätze verschlüsselt werden.
+Die so verschlüsselten Daten können ausschließlich von diesem Zustellpunkt gelesen werden.
+
+Bevor wir mit der Verschlüsselung loslegen können müssen wir den eben abgerufenen JWK noch auf Gültigkeit überprüfen.
+
+## Überprüfen des öffentlichen Schlüssel (Zertifikatsprüfung)
+
:::note Hinweis
-In der Testumgebung ist die Absicherung der öffentlichen Schlüssel eines Zustellpunktes durch Zertifikate optional. Eine Prüfung der Zertifikate kann in diesem Fall zu Testzwecken entfallen.
+In der Testumgebung ist die Absicherung der öffentlichen Schlüssel eines Zustellpunktes durch Zertifikate optional.
+Eine Prüfung der Zertifikate kann in diesem Fall zu Testzwecken entfallen.
:::
-Die JSON Web Keys MÜSSEN vor der Verwendung zwingend im Client auf Gültigkeit geprüft werden. Das umfasst insbesondere folgende Schritte:
+JWKs MÜSSEN vor der Verwendung zwingend im Client auf Gültigkeit geprüft werden. Diese Prüfung umfasst folgende Schritte:
- Überprüfung, dass der JSON Web Key für die Verschlüsselung geeignet ist (`"keyops": ["wrap_key"]`)
- Überprüfung, dass der öffentliche Schlüssel mit dem im JSON Web Key hinterlegten Zertifikat übereinstimmt (Attribute `n` und `e`)
- Überprüfung der Zertifikats-Kette bis zum Wurzelzertifikat (BSI)
- Überprüfung gegen eine Certificate Revocation List und/oder einen OCSP-Endpunkt mit signierten Antworten
-Weitere Informationen zur Gültigkeitsprüfung finden sich in der technischen Richtlinie [BSI TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4).
+Weitere Informationen zur Gültigkeitsprüfung finden sich in der technischen Richtlinie [BSI TR-02103](https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02103/BSI-TR-02103.pdf?__blob=publicationFile&v=4) des BSI.
:::note Hinweis
An dieser Stelle werden noch detailliertere Informationen und konkrete Implementierungsbeispiele zur Prüfung der JSON Web Keys ergänzt.
@@ -92,7 +115,7 @@ const encryptedText = await new CompactEncrypt(encodedText)
```
Anhänge wie PDF-Dateien, Bilder o. ä. liegen meist in einem `Uint8Array` vor bzw. können einfach darin umgewandelt werden.
-Im folgenden Beispiel wird eine Datei aus einem HTML-File-Input direkt heraus verschlüsselt.
+Im Folgenden Beispiel wird eine Datei aus einem HTML-File-Input direkt heraus verschlüsselt.
```javascript
// .arrayBuffer() => https://developer.mozilla.org/en-US/docs/Web/API/Blob/arrayBuffer
@@ -130,8 +153,10 @@ Mit diesem umgewandelten Schlüssel können nun Zeichenketten und Binärdaten ve
```java
JWEHeader header = new JWEHeader(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A256GCM);
+// Zeichenkette
Payload payload = new Payload("{ \"Hello\": \"World\"}");
-/// Alternativ, bei einer Datei
+
+// InputStream (z.B. für Datei)
Payload payload = new Payload(aFileInputStream.readAllBytes());
JWEObject jweObject = new JWEObject(header, payload);
@@ -140,7 +165,7 @@ try {
jweObject.encrypt(new RSAEncrypter(publicKey));
String encrypted = jweObject.serialize();
- System.out.println("Encrypted Text:");
+ System.out.println("Encrypted Text");
System.out.println(encrypted);
} catch (JOSEException e) {
e.printStackTrace();
diff --git a/docs/getting-started/sending/get-destination.mdx b/docs/getting-started/sending/get-destination.mdx
index 2a79cd64e7d808138ae11cff7f1503b334b4f079..09b063bae7db3fa408c000b0d6b29cdc56834f30 100644
--- a/docs/getting-started/sending/get-destination.mdx
+++ b/docs/getting-started/sending/get-destination.mdx
@@ -5,8 +5,9 @@ title: Zustellpunkt ermitteln
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
+import ApiLink from '@site/src/components/ApiLink'
-## Zustellpunkt und destinationId ermitteln
+## Zustellpunkt und `destinationId` ermitteln
Um eine Einreichung an die fachlich korrekte Stelle sicherzustellen und die technischen Parameter des richtigen Zustellpunkt zu ermitteln, muss die `destinationId` der zuständigen Stelle ermittelt werden. Zukünftig wird die Ermittlung der `destinationId` und die Ermittlung der technischen Parameter über die FIT-Connect Routing API möglich sein. Sobald die Routing API umgesetzt ist (voraussichtlich Ende Q3 2021), wird diese Möglichkeit hier beschrieben.
@@ -18,10 +19,10 @@ Diese Informationen sind:
- einem Identifikator der Verwaltungsleitung (`identifier`): Typischerweise entspricht dieser einem LeiKa-Schlüssel (siehe [Leistungskatalog im FIM-Portal](https://fimportal.de/kataloge#download-leistungen)).
- einer Liste an zulässigen Fachdatenschemata (`submissionSchemas`): Hiermit legt das empfangende System fest, welchem Schema die übergebenen Fachdatensätze entsprechen müssen. Welches der angebenen Schemata verwendet werden muss, bestimmt das sendende System aus dem eigenen fachlichen Kontext heraus. Wenn bspw. ein Antrag für einen Schwerbehindertenausweis gestellt wird, muss der Fachdatensatz aus den dort hinterlegten Schemata gemäß dem dortigen Schema für den Schwerbehindertausweis (bspw. ein FIM/XFall Schema) entsprechen.
- einer Liste an Regionen (`regions`), für die die Verwaltungsleistung angeboten wird.
-- Der öffentliche Verschlüsselungsschlüssel (`encryptionKid` und `publicKeys`): Empfangende Systeme veröffentlichen in Form eines JSON Web Key Sets einen oder mehrere Public Keys für die Verschlüsselung der Einreichung. Welcher Public Key zum aktuellen Zeitpunkt für die Verschlüsselung genutzt werden muss, wird über den Parameter `kid` mitgeteilt.
+- Schlüssel-ID des öffentlichen Verschlüsselungsschlüssels (`encryptionKid`): Empfangende Systeme veröffentlichen die Schlüssel-ID ihres Verschlüsselungsschlüssels für die Verschlüsselung von Einreichungen. Der dazugehörige JSON Web Key (JWK) kann anschließend über den Endpunkt <ApiLink to="/destinations/{destinationId}/keys/{keyId}" /> abgefragt werden.
:::caution Hinweis
-Der Mechanismus zum Abruf der Verschlüsselungsschlüssel wird sich bis zur Verföffentlichung der finalen API-Spezifikation noch einmal ändern.
+Der Mechanismus zum Abruf der Verschlüsselungsschlüssel wird sich bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern.
:::
Zum Abruf der Zustellpunkt-Informationen stellt die Submission API einen Endpunkt bereit, der über Angabe des Parameters `destinationId` die technischen Parameter der Einreichung für den jeweiligen Zustellpunkt ausgibt.
@@ -62,26 +63,7 @@ $ curl \
]
}
],
- "encryptionKid": "c66e4423-e28d-4a1f-911d-818f9ab60221",
- "publicKeys": {
- "keys": [
- {
- "kty": "RSA",
- "key_ops": [
- "wrapKey"
- ],
- "alg": "RSA-OAEP-256",
- "x5c": [
- "...(base64 encoded cert)...",
- "...(base64 encoded intermediate cert)...",
- "...(base64 encoded root cert)..."
- ],
- "kid": "c66e4423-e28d-4a1f-911d-818f9ab60221",
- "n": "hGALqq-nbAymF5M...puHAyo3-iMf3UaBsPj0s",
- "e": "AQAB"
- }
- ]
- }
+ "encryptionKid": "c66e4423-e28d-4a1f-911d-818f9ab60221"
}
```
</TabItem>
diff --git a/docs/getting-started/sending/submit.mdx b/docs/getting-started/sending/submit.mdx
index 3fb70f0b638411c3313e9f1b30740763f1f03b86..372d4b6e2b97b3f68632ae8f222dfbee7e80e6fb 100644
--- a/docs/getting-started/sending/submit.mdx
+++ b/docs/getting-started/sending/submit.mdx
@@ -15,7 +15,7 @@ Diese PUT Methode kann nur folgreich durchgeführt werden, wenn folgende Bedingu
Wenn die Nutzung dieses Endpunkts erfolgreich war, wechselt die Einreichung in den Status `submitted` und die vollständige Einreichung (Anlagen, Metadatensatz und Fachdatz) liegt nun für das empfangende System zum Abruf bereit.
-Ein Beispiel für die Nutzung des Endpunkt ist im folgenden Ausschnitt dargestellt:
+Ein Beispiel für die Nutzung des Endpunkt ist im Folgenden Ausschnitt dargestellt:
<Tabs
defaultValue="curl"
diff --git a/docs/sidebar.js b/docs/sidebar.js
index edfb85a47b74ca888ba5d69a68281b0ce792169f..7701752a3f6d6ea75bc2ec9d83de218457c7b707 100644
--- a/docs/sidebar.js
+++ b/docs/sidebar.js
@@ -77,6 +77,7 @@ module.exports = {
label: 'Detailinformationen',
items: [
'details/crypto',
+ 'details/destination-management',
'details/jwk-creation',
'details/schema-reference',
'details/pgp-export',
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 1f6d7c021f2d830b0b4a4fda949224f553de5295..769d5b96d3f1897fff6c76f273cc89fd22de4747 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -46,6 +46,7 @@ module.exports = {
style: 'light',
copyright: `Copyright © ${new Date().getFullYear()} FITKO (Föderale IT-Kooperation) | Zum Gottschalkhof 3 | 60594 Frankfurt am Main | E-Mail: poststelle@fitko.de | https://www.fitko.de | Die FITKO ist eine Anstalt des öffentlichen Rechts. Sie wird vertreten durch die Präsidentin Frau Dr. Annette Schmidt.`,
},
+ hideableSidebar: true,
},
presets: [
[
diff --git a/src/css/custom.css b/src/css/custom.css
index db02f91008f78a8421d773dc90372c7b1644cb4e..e06ae715499f8a359e2bc914bc07444eabc24e97 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -9,3 +9,7 @@ dl dt {
fill: var(--ifm-font-color-base);
stroke: var(--ifm-font-color-base);
}
+
+.center {
+ text-align: center;
+}
\ No newline at end of file
diff --git a/static/images/ssp/20-Destination-loeschen.png b/static/images/ssp/20-Destination-loeschen.png
deleted file mode 100644
index b61787e96db07ad6a8589d212a3636f1e087ff74..0000000000000000000000000000000000000000
Binary files a/static/images/ssp/20-Destination-loeschen.png and /dev/null differ