Merge branch 'mr-destinationSignature' into 'main'

Update description of destinationSignature validation

See merge request !246

docs/changelog.md

@@ -4,6 +4,9 @@ Das Format dieser Datei basiert auf [Keep a Changelog](https://keepachangelog.co
 
 Das hier veröffentlichte Changelog bezieht sich auf die [Testinstanz von FIT-Connect](https://docs.fitko.de/fit-connect/docs/getting-started/get-started#testing).
 
+## 2022-10-13
+### Dokumentation
+- Dokumentation zur [Prüfung der `destinationSignature`](sending/get-destination.mdx#destinationSignature) überarbeitet und präzisiert.
 
 ## 2022-10-10
 ### Dokumentation

docs/sending/get-destination.mdx

@@ -108,8 +108,12 @@ Die Zustellpunkt-Informationen bestehen aus:
 - Der Name der zuständigen Fachbehörde (`destinationName`).
 - Die URL des Logos der zuständigen Fachbehörde (`destinationLogo`).
 
-### Inhalt der Adressierungsinformationen (Parameter `destinationSignature`)
+### Adressierungsinformationen (Parameter `destinationSignature`) {#destinationSignature}
+Die im Parameter `destinationSignature` hinterlegten Adressierungsinformationen sind vom Self-Service Portal (SSP) signiert und wurden zuvor von der für den Zustellpunkt zuständigen Stelle [im Portalverbund hinterlegt](../organisation-tasks/routing.mdx).
+
+#### Payload der `destinationSignature`
 Der dekodierte Inhalt (Payload) der Adressierungsinformationen sieht beispielhaft wie folgt aus (Leerzeichen und Zeilenumbrüche dienen ausschließlich der besseren Lesbarkeit):
+
 ```json
 {
   "submissionHost": "submission-api-testing.fit-connect.fitko.dev",
@@ -130,10 +134,11 @@ Der dekodierte Inhalt (Payload) der Adressierungsinformationen sieht beispielhaf
 }
 ```
 
-### Signaturprüfung der vom Self-Service Portal (SSP) signierten Adressierungsinformationen (Parameter `destinationSignature`) {#checkDestinationSignature}
-Bei den signierten Adressierungsinformationen handelt es sich um signierte JSON Web Tokens (JWTs).
-Um die Signatur der vom Self-Service-Portal signierten JWTs zu überprüfen, ist es notwendig, auf die verwendeten Schlüssel (im Format JSON Web Key, kurz JWK) zugreifen zu können.
-Das Self-Service-Portal stellt ein JSON Web Key Set (JWKS) öffentlich zugänglich über den Endpunkt `/.well-known/jwks.json` bereit.
+#### Signaturprüfung der Adressierungsinformationen (Parameter `destinationSignature`) {#checkDestinationSignature}
+Bei den vom Self-Service Portal (SSP) signierten Adressierungsinformationen handelt es sich um einen signierten JSON Web Token (JWT).
+Durch eine Prüfung der Signatur des JWT kann eine Manipulation der Adressierungsinformationen durch die Systeme des Portalverbund sowie den Routingdienst ausgeschlossen werden.
+
+Den zur Prüfung der Signatur benötigten öffentlichen Schlüssel (im Format JSON Web Key, kurz JWK) stellt das Self-Service-Portal stellt in einem JSON Web Key Set (JWKS) öffentlich zugänglich über den Endpunkt `/.well-known/jwks.json` bereit.
 Für unser Testsystem ist das JWKS z.B. [hier](https://portal.auth-testing.fit-connect.fitko.dev/.well-known/jwks.json) verfügbar.
 
 Ein Beispiel für ein JWKS ist in folgendem Ausschnitt dargestellt:
@@ -154,9 +159,14 @@ Ein Beispiel für ein JWKS ist in folgendem Ausschnitt dargestellt:
 }
 ```
 
-Mit diesem JWKS kann die Signatur der Adressierungsinformationen überprüft werden.
-Hierfür muss der Schlüssel mit der passenden Schlüssel-ID (Key-ID) aus dem `kid`-Header der Adressierungsinformationen im JWKS ermittelt werden.
-Dann kann man mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung durchführen.
+Zur Prüfung der Signatur der Adressierungsinformationen muss der passenden Schlüssel mit der im `kid`-Header der Adressierungsinformationen hinterlegten Schlüssel-ID im JWKS ermittelt werden.
+Anschließend kann mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung erfolgen.
+
+#### Prüfung von Leistungsschlüssel/ARS {#checkservices}
+Zusätzlich sollte geprüft werden, ob der gegenüber der Routing-API angefragte Leistungsschlüssel und ARS zu einer der in den Adressierungsinformationen angegeben Kombinationen aus Leistungsschlüssel und ARS passt.
+Erfolgt eine Anfrage auf Basis einer über die Routing API ermittelten Area-ID (anhand einer Postleitzahl bzw. eines Gebeitsnamens), so muss an dieser Stelle auf das korrekte Mapping des Routingdienstes zw. Postleitzahl/Gebeitsnamen und ARS vertraut werden, sodass eine Prüfung des ARS durch den Sender keinen Mehrwert bietet und daher ausgelassen werden kann.
+
+#### Code-Beispiel
 
 <Tabs
   defaultValue="java"
@@ -203,6 +213,8 @@ Im folgenden Beispiel wird die Bibliothek [nimbus-jose-jwt](https://connect2id.c
         validateTrueOrElseThrow(payload.getClaim("jti") != null, "The claim jti is missing in the payload of the JWT.");
         validateTrueOrElseThrow(payload.getClaim("destinationId") != null, "The claim destinationId is missing in the payload of the JWT.");
         validateTrueOrElseThrow(payload.getClaim("submissionHost") != null, "The claim submissionHost is missing in the payload of the JWT.");
+
+        // check if requested region/service matches an entry of the services list
         validateTrueOrElseThrow(payload.getClaim("services") != null, "The claim services is missing in the payload of the JWT.");
         validateTrueOrElseThrow(!((JSONArray) payload.getClaim("services")).isEmpty(), "At least one service is needed.");
         validateTrueOrElseThrow(