C_12299_Anlage_V1.0.0

Prereleases:

Draft_IDP_25_6

Nächste Änderung Vorherige Änderung C_12299_Anlage_V1.0.0

C_12299_Anlage

Inhaltsverzeichnis

C_12299_Anlage
1 Änderungsbeschreibung
2 Änderung in gemSpec_IDP_Dienst
3 Änderungen in gemSpec_Perf
3.1.1 E-Mail-Report IDP-Dienst
4 Änderungen in Steckbriefen
4.1 Änderungen in gemProdT_IDP-Dienst_PTV
4.2 Änderungen in gemAnbT_IDP-Dienst_ATV

1 Änderungsbeschreibung

Problemstellung:
Der Schlüsselwechselprozess des IDP-Dienstes ist derzeit so gestaltet, dass der Anbieter des IDP-Dienstes eine "harte" Umstellung (hard cutover) mit Vorankündigung (per TI-ITSM-Change) durchführt.
Beim Schlüsselwechsel kam es in der Vergangenheit immer wieder zu Problemen, wenn die Clientsysteme (PVS, AVS, KVS und FD) das Discovery Document des IDP-Dienstes nicht unmittelbar nach Bereitstellung des neuen Schlüsselmaterials neu geladen haben bzw. das alte Schlüsselmaterial hartcodiert implementiert hatten (auch bekannt als Zertifikatspinning).
So nutzen Clients, welche den Schlüsselwechsel noch nicht erkannt haben, weiterhin das alte (nicht länger gültige) Schlüsselmaterial. Die mit dem alten Schlüssel für den IDP-Dienst verschlüsselten Daten sind dann am IDP-Dienst nicht verarbeitbar, da dort der alte Schlüssel nicht mehr gültig ist. Neue, vom IDP-Dienst ausgestellte Token können vom Fachdienst nicht validiert werden, wenn der Fachdienst das Discovery Document des IDP-Dienstes nicht unmittelbar nach Bereitstellung des neuen Schlüsselmaterials neu geladen hat.
Es kommt aus Sicht der Nutzer zu einer Störung.

Gewünscht ist eine Übergangsphase, in der das neu zu verwendende Schlüsselmaterial bekannt gemacht wird, während das alte Schlüsselmaterial noch genutzt werden kann.
Um eine schrittweise Migration der Client-Systeme zu ermöglichen, bleibt das bestehende Verhalten zunächst erhalten und es wird parallel dazu ein neuer Schlüsselwechsel-Mechanismus etabliert. Die Client-Systeme können dann selbstständig entscheiden, wann sie eine Migration umsetzen.

Folgende Eigenschaften sind für die Lösung charakteristisch:

Parallel zur heute im Discovery Document hinterlegten "jwks_uri" (die auf eine JSON-Datei zeigt, die alle verwendeten Schlüssel enthält), wird in diesem Dokument der neue Parameter "signed_jwks_uri" aufgenommen.
Als Signaturschlüssel wird das gleiche Schlüsselmaterial verwendet, das auch zum Signieren des Metadaten-Statements (Discovery Document) verwendet wird.
"signed_jwks_uri" referenziert auf ein als JSON Web Signature signiertes JSON Web Key Set (JWKS), das alle derzeit gültigen öffentlichen Schlüssel des IDP-Dienstes auflistet.
Für jeden "key" in diesem Set wird eine eindeutige Key-ID (Parameter "kid") im UUID7-Format [RFC9562#name-uuid-version-7] vom Anbieter verwaltet - im Unterschied zu bisher: gab es einen konstanten Wert: "idp_puk_sig".
Der Identifier "kid" wird im Discovery Document an verschiedenen Stellen verwendet und muss für eine konsistente Referenzierung jeweils die passenden Identifier verwenden.
Während des Übergangszeitraums (üblicherweise mindestens 14 Tage vor dem Entfernen des alten Schlüsselmaterials) enthält das signed_JWKS dann beide public keys. Nach Ablauf der Übergangszeit kann der alte Schlüssel entfernt werden.
Die unsignierten JSON Web Key Sets unter jwks_uri (puk_idp_sig, puk_idp_enc, puk_idp_sig_sek, uri_puk_idp_enc puk_idp_sek) und uri_puk_idp_sig (puk_idp_sig) werden befristet.

2 Änderung in gemSpec_IDP_Dienst

Änderungen an gemSpec_IDP_Dienst zur Umsetzung des optimierten Schlüsselwechselprozesses

In Kapitel 4 Zerlegung des Produkttyps

Befristung: Langfristig sollen die öffentlichen Signatur- und Encryption Schlüssel nur noch über das signed_jwks_uri JWKS bereitgestellt werden, daher wird die Bereitstellung unter den einzelnen Schlüsseln als eigene URI (uri_puk_idp_enc uri_puk_idp_sig) befristet.

Durch Auswertung der gelieferten Betriebsdaten (siehe Kapitel [3 Änderungen in gemSpec_Perf]) wird die gematik die Umstellung der Clients auf die neuen Schnittstellen beobachten und an einem geeigneten Zeitpunkt die Entfernung dieser Schnittstellen über ein weiteres Spezifikationsupdate vorbereiten.

A_20732 - Aufnahme der öffentlichen Schlüssel in das Discovery Document

Der Authorization Server MUSS zu jedem privaten Schlüssel dessen öffentlichen Teil mit einer eigenen absoluten URI in das Discovery Document aufnehmen. [<=]

Änderung nur in der Überschrift: A_20732 - Aufnahme der öffentlichen Schlüssel in das Discovery Document (befristet)

In Kapitel 5.1.1 Aufbau des Discovery Document

alt:

A_20458-02 - Inhalte des Discovery Document

Der Discovery-Endpunkt MUSS sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] mindestens die folgenden Attribute als URI angeben:

"issuer" (hier ist der IdP-Dienst erreichbar),
"jwks_uri" (für den Abruf von "PUK_IDP_ENC sowie des öffentlichen Schlüssels und des Zertifikats von "PUK_IDP_SIG" entsprechend TAB_IDP_DIENST_0003 [RFC7517] – identifiziert anhand der "kid"-Parameter (puk_idp_enc / puk_idp_sig),
"uri_disc" (URI, unter welcher das Discovery Document bereitgestellt wird),
"authorization_endpoint" (URI des Dienstes und des öffentlichen Verschlüsselungsschlüssels des Authorization-Endpunktes gemäß [RFC6749]),
"sso_endpoint" (URI des Authorization-Endpunktes für Requests mit SSO-Token),
"auth_pair_endpoint" (URI des Authorization-Endpunktes für Requests mit Pairing-Daten),
"token_endpoint" (URI des Token-Endpunktes gemäß [RFC6749]),
"uri_puk_idp_enc“ und "uri_puk_idp_sig" (URI der JWK-Objekte für die zwei Schlüssel und des Zertifikates).

[<=]

Geänderte Prüfzuordnung: Die Anforderung richtet sich nun an den Anbieter statt an den Hersteller

neu:

A_20458-03 - Inhalte des Discovery Document

Der Anbieter des IDP-Dienstes MUSS am Discovery-Endpunkt MUSS sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] mindestens die folgenden Attribute als URI angeben:

"issuer" (hier ist der IdP-Dienst erreichbar),
"jwks_uri" (für den Abruf von „PUK_IDP_ENC“ sowie des öffentlichen Schlüssels und des Zertifikats von „PUK_IDP_SIG“ entsprechend TAB_IDP_DIENST_0003 [RFC7517] – identifiziert anhand der „kid“-Parameter (puk_idp_enc / puk_idp_sig)
"signed_jwks_uri" (für den Abruf der öffentlichen Schlüssel und Zertifikate von "PUK_IDP_ENC“ sowie "PUK_IDP_SIG“ entsprechend TAB_IDP_DIENST_0003 [RFC7517] – identifiziert anhand der "kid“-Parameter und des "alias" (puk_idp_enc / puk_idp_sig)),
"uri_disc" (URI, unter welcher das Discovery Document bereitgestellt wird),
"authorization_endpoint" (URI des Dienstes und des öffentlichen Verschlüsselungsschlüssels des Authorization-Endpunktes gemäß [RFC6749]),
"sso_endpoint“ (URI des Authorization-Endpunktes für Requests mit SSO Token),
"auth_pair_endpoint“ (URI des Authorization-Endpunktes für Requests mit Pairing-Daten),
"token_endpoint" (URI des Token-Endpunktes gemäß [RFC6749])
"uri_puk_idp_enc“ und „uri_puk_idp_sig“ (URI der JWK Objekte für die zwei Schlüssel und des Zertifikates).

[<=]

Hinweis: Die Anforderung zur Bereitstellung der Attribute "jwks_uri", "uri_puk_idp_sig“ und "uri_puk_idp_enc“ wurden inhaltlich unverändert in A_27962-* und A_27963-* abgetrennt und befristet.

neu:

A_27963 - jwks_uri im Discovery Document (befristet)

Der Anbieter des IDP-Dienstes MUSS am Discovery-Endpunkt sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] darüber hinaus die folgenden Attribute als URI angeben:

"jwks_uri" (für den Abruf von "PUK_IDP_ENC“ sowie des öffentlichen Schlüssels und des Zertifikats von "PUK_IDP_SIG“ entsprechend TAB_IDP_DIENST_0003 [RFC7517] – identifiziert anhand der "kid“-Parameter (puk_idp_enc / puk_idp_sig).

[<=]

neu:

A_27962 - PUK_IDP_SEK und PUK_IDP_ENC uri im Discovery Document (befristet)

Der Anbieter des IDP-Dienstes MUSS am Discovery-Endpunkt sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] zusätzlich die folgenden Attribute als URI angeben:

"uri_puk_idp_enc" und "uri_puk_idp_sig" (URI der JWK-Objekte für die zwei Schlüssel und das zugehörige Zertifikat).

[<=]

neu:

A_28376 - Inhalte des signierten JWK-Schlüsselsets

Der Anbieter des IDP-Dienstes MUSS sicherstellen, dass das JWK-Schlüsselset, welches im Discovery Document über den Parameter "signed_jwks_uri" referenziert ist, die folgenden Schlüssel gemäß TAB_IDP_DIENST_0003 enthält:

PuK_IDP_SIG,
PuK_IDP_SIG_Sek,
PuK_IDP_ENC,
PuK_DISC_SIG.

Für Schlüssel vom Typ 1 und 2 gilt, dass neue Schlüssel spätestens 48 Stunden vor Ablauf des aktuell verwendeten Schlüssels gleichen Typs im JWK-Schlüsselset veröffentlicht sein MÜSSEN.

Für Schlüssel vom Typ 3 gilt, dass neue Schlüssel spätestens 72 Stunden vor Ablauf des aktuell verwendeten Schlüssels gleichen Typs im JWK-Schlüsselset veröffentlicht sein MÜSSEN. Entfernte Schlüssel MÜSSEN noch 48 Stunden systemintern zum Entschlüsseln nutzbar sein.

Für Schlüssel vom Typ 4 gilt, dass neue Schlüssel spätestens 2 Wochen vor Ablauf des aktuell verwendeten Schlüssels gleichen Typs im JWK-Schlüsselset veröffentlicht sein MÜSSEN.
[<=]

neu:

A_28381 - signed_JWKS IDP_SIG Schlüssel Verwendung und Nachhaltung

Der Anbieter des IDP-Dienst SOLL für Schlüssel vom Typ 1 und 2 nach A_28376-* sicherstellen, dass die Verwendung eines neuen Schlüssels frühestens 48 Stunden nach dessen Veröffentlichung erfolgt und nicht mehr benutzte Schlüssel noch 48 Stunden im JWK-Schlüsselset vorgehalten werden. [<=]

neu:

A_28382 - signed_JWKS DISC_SIG Schlüssel Verwendung

Der Anbieter des IDP-Dienst SOLL für neue Schlüssel vom Typ 4 nach A_28376-* sicherstellen, dass diese frühestens 2 Wochen nach Veröffentlichung verwendet werden. [<=]

neu:

A_27936 - Signaturschlüssel des JWK-Schlüsselsets in signiertem Format

Der Hersteller des IDP-Dienstes MUSS sicherstellen, dass das JWK-Schlüsselset, welches im Discovery Document über den Parameter "signed_jwks_uri" referenziert ist, im Format JSON Web Signature bereitgestellt und mit dem "PrK_DISC_SIG“ Schlüssel gemäß TAB_IDP_DIENST_0003 und [RFC7517] signiert wird.

Hinweis: Das Schlüsselset wird mit dem Content-Type: "application/jwk-set+json" bereitgestellt. [<=]

neu:

A_27937 - Konsistente Repräsentation des JWK-Schlüsselsets in zwei Formaten (befristet)

Der Hersteller des IDP-Dienstes MUSS am Discovery-Endpunkt sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] sicherstellen, dass die öffentlichen Anteile der Schlüsselpaare in den JWK-Schlüsselsets, die durch "jwks_uri", "signed_jwks_uri", "uri_puk_idp_sig" und "uri_puk_idp_enc" referenziert werden, identisch sind.
Die in dem unter "signed_jwks_uri" referenzierten Schlüsselset veröffentlichten Schlüssel MÜSSEN für die anderen Bereitstellungsorte wie folgt angepasst werden:

Abweichend von A_27940-* wird das "alias“ als "kid“ Wert übernommen,
Abweichend von A_27938-* entfällt das "alias“.

Sind in dem unter "signed_jwks_uri" referenzierten Schlüsselset gleichzeitig mehrere Schlüssel mit dem gleichen "alias" veröffentlicht, welche jeweils eine UUIDv7 als "kid" verwenden, so MÜSSEN die Schlüssel für die anderen Bereitstellungsorte wie folgt gewählt werden:

Bei Schlüsseln mit einem auf "_enc" endenden "alias", ist der jüngste (mit größerem numerischem Wert des "kid") zu wählen,
Bei Schlüsseln mit einem auf "_sig" endenden "alias", ist der älteste (mit kleinerem numerischem Wert des "kid") zu wählen.

Sind in dem unter "signed_jwks_uri" referenzierten Schlüsselset gleichzeitig mehrere Schlüssel mit dem gleichen "alias" veröffentlicht, von denen einer keine UUIDv7 als "kid" verwendet, so MÜSSEN die Schlüssel für die anderen Bereitstellungsorte wie folgt gewählt werden:

Bei Schlüsseln mit einem auf "_enc" endenden "alias", ist der Schlüssel zu wählen, der eine UUIDv7 als "kid" verwendet,
Bei Schlüsseln mit einem auf "_sig" endenden "alias", ist der Schlüssel zu wählen, der keine UUIDv7 als "kid" verwendet.

[<=]

Hinweis: Sobald alle den IDP-Dienst nutzenden Systeme mit dem neuen Schlüssel-Set unter "signed_jwks_uri“ umgehen können, wird die Unterstützung für das alte Format A_27962-* und A_27963-* aus dem IDP-Dienst entfernt.

neu:

A_27940 - Einheitliche Schlüssel-Identifikatoren

Der Anbieter des IDP-Dienstes MUSS am Discovery-Endpunkt sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] sicherstellen, dass die öffentlichen Anteile der Schlüsselpaare in den JWK-Schlüsselsets, die durch "signed_jwks_uri“ referenziert werden, mit dem Parameter "kid“ befüllt sind. Der Wert des jeweiligen "kid“-Parameters MUSS für neu hinzugefügte Schlüssel im UUIDv7-Format gemäß [RFC9562#name-uuid-version-7] angegeben sein, dessen Wert den Zeitpunkt der Schlüsselerzeugung widerspiegelt.

[<=]

Hinweis:

Für Systeme, die den IDP-Dienst nutzen und vom IDP-Dienst herausgegebene Token validieren, ist bei der Auswahl des Schlüssels in der signed_JWKS, der zum "kid“ im Token-Signaturheader passt, zu beachten, dass während einer Übergangsphase eine Abweichung zu berücksichtigen ist. Entspricht der "kid“-Wert im Signaturheader einem Wert aus TAB_IDP_DIENST_0003 (in Kleinschreibung), so ist der korrelierende Schlüssel in der signed_JWKS anhand des "alias“ zu identifizieren. Dabei können mehrere Schlüssel zu berücksichtigen sein.

neu:

A_27938 - Ergänzung des Parameters "alias" in signierten JWK-Schlüsselsets

Der Anbieter des IDP-Dienstes MUSS am Discovery-Endpunkt sowohl im internen als auch im externen Discovery Document gemäß [RFC8414#section-2] sicherstellen, dass die öffentlichen Anteile der Schlüsselpaare in den JWK-Schlüsselsets, die durch "signed_jwks_uri“ referenziert werden, den Parameter "alias“ mit den zugehörigen Werten aus TAB_IDP_DIENST_0003 gemäß [RFC7517] in Kleinschreibweise enthalten. [<=]

Hinweis: Der Parameter „alias“ im JWK dient der leichteren Zuordenbarkeit der Schlüsselverwendung.

neu:

A_27941 - Zweifaches Vorkommen von JWK mit gleichem "alias" im Key-Set während des Übergangszeitraums beim Schlüsselwechsel

Der Anbieter des IDP-Dienstes MUSS während des Übergangszeitraums beim Schlüsselwechsel sicherstellen, dass:

der aktuell gültige öffentliche Schlüssel mit zugehörigem "alias" im Key Set vorhanden ist,
der zukünftig gültige öffentliche Schlüssel mit gleichem "alias" im Key Set vorhanden ist,
beide Schlüsselpaare vom System verwendet werden können.

In der Auflistung innerhalb des signed_JWKS soll ein jüngerer Schlüssel (mit größerem numerischen Wert des "kid") stets vor dem älteren Schlüssel des gleichen "alias" erfolgen. Der abzulösende Schlüssel soll mit dem Attribut "deprecated" versehen sein, das den gemäß [RFC7519#section-2] als "NumericDate" formatierten Zeitpunkt angibt, ab dem dieser Schlüssel nicht mehr verwendet werden soll.
[<=]

Hinweis: Den IDP-Dienst nutzende Systeme müssen ab dem Umstellungszeitpunkt t_n (siehe Kapitel "Schlüsselwechselprozess bei JWK-Schlüsselsets") damit umgehen können, dass die ausgestellten Token mit neuen Schlüsseln signiert sind. Der aktuell verwendete Schlüssel ist stets durch seine im Signatur-Header der JWS angegebene Key-ID „kid“ identifizierbar. Im alten Format bezieht sie sich stets auf die "kid" im JWKS – im neuen signed_JKWS Format, sofern die Schlüsselauswahl gemäß Hinweis zu A_27940-* anhand des „alias“ erfolgt, auf einen dieser Schlüssel mit dem gleichlautenden "alias". Stehen mehrere passende Schlüssel (des gleichen "alias") zur Validierung zur Verfügung, so sind ältere (mit kleinerem numerischem Wert des "kid") Schlüssel zu präferieren, neuere aber auch zu berücksichtigen.

Hinweis 2: Den IDP-Dienst nutzende Systeme sollen bei der Auswahl eine Schlüssels, dessen Verwendungszweck das Verschlüsseln ist, den jeweils jüngeren (mit größerem numerischen Wert des "kid") Schlüssel präferieren.

Neues Kapitel 5.1.5 Schlüsselwechselprozess

Der bisher etablierte Schlüsselwechsel zu einem Stichtag wird über einen "harten“ Wechsel eines Schlüssel durchgeführt. Dies kann bei den nutzenden Systemen zu Problemen führen, die den Arbeitsablauf stören oder unterbrechen. Durch das parallel bereitgestellte signierte Schlüssel-Set wird ein Schlüsselwechselprozess mit Übergangszeitraum ermöglicht, während dem sowohl die aktuell gültigen als auch die zukünftig gültigen Schlüssel im Schlüssel-Set bereitgestellt werden und und angepasste betriebliche Anforderungen an den IDP-Dienst die zuverlässige Entschlüsselung auch während des Wechsel des Verschlüsselungsschlüssels sicherstellen.

Vor Beginn des Übergangszeitraums wird der Schlüsselwechsel über das TI-ITSM beantragt (t_n-2). Während des Übergangszeitraums (t_n-1bis t_n) haben Clientsysteme die Aufgabe, den zukünftig gültigen Signaturschlüssel in ihre Systeme (deren Key- bzw. Trust-Store) zu importieren, so dass diese Schlüssel zum Schlüsselwechsel-Termin (t_n) vom IDP Dienst genutzt werden können. Für Verschlüsselungsschlüssel gilt abweichend hiervon, dass diese unverzüglich von den Clientsysteme ab erster Sichtung (t_n-1) zu benutzen sind, spätestens jedoch nach dem Übergangszeitraum.

Nach Ablauf des Übergangszeitraums werden die ungültigen/abgelaufenen Schlüssel aus dem Key-Set entfernt (t_n+1).

Die folgende Abbildung "Schematische Übersicht zum Ablauf des Schlüsselwechselprozess beim IDP-Dienst" zeigt die zeitliche Abfolge des Schlüsselwechselprozesses.

Abbildung 1: Schematische Übersicht zum Ablauf des Schlüsselwechselprozess beim IDP-Dienst

Wenn alle den IDP-Dienst nutzenden Systeme auf die Verarbeitung des signed_JWKS umgestellt sind, kann die Umstellung der "kid“ im ID_TOKEN Header erfolgen, dass dieser die tatsächliche "kid“ des Schlüssels referenziert statt des "alias“.

Änderungen in Kapitel 7

Änderung in Kapitel 7.7 Aufbau des Discovery Document

Es wird der "signed_jwks_uri“ Eintrag unter „jwks_uri“ ergänzt

01|{
02| "alg": "BP256R1",
03| "kid": "puk_disc_sig",
04| "x5c": [
05| "[Enthält das verwendete Signer-Zertifikat als Base64 ASN.1 DER-Encoding. Hier kommt ausnahmsweise NICHT URL-safes Base64-Encoding zum Einsatz!]"
06| ]
07|}
08|.
09|{
10| "authorization_endpoint": "[URL des Authorization Endpunkts.]",
11| "federation_authorization_endpoint": "[URL des Authorization Endpunkt für Anfragen an IDP der Föderation - dieser ist nur im Internet verfügbar]",
12| "auth_pair_endpoint": "[URL des Pairing-Authorization-Endpunkts - dieser ist nur im Internet verfügbar]",
13| "third_party_authorization_endpoint" : "[URL des third_party-Authorization-Endpunkts - dieser ist nur im Internet verfügbar]",
14| "sso_endpoint": "[URL des SSO-Authorization Endpunkts.]",
15| "uri_pair": "[URL des Pairing-Endpunkts.]",
16| "token_endpoint": "[URL des Authorization-Endpunkts.]",
17| "uri_disc": "[URL des Discovery Document.]",
18| "issuer": "http://url.des.idp",
19| "jwks_uri": "[URL einer JWKS-Struktur mit allen vom Server verwendeten Schlüsseln]",
20| "signed_jwks_uri": "[URL einer JWKS-Struktur mit allen vom Server verwendeten Schlüsseln]",
21| "exp": "[Gültigkeit des Token. Beispiel: 1618330390]",
22| "iat": "[Zeitpunkt der Ausstellung des Token. Beispiel: 1618243990]",
23| "uri_puk_idp_enc": "http://url.des.idp/idpEnc/jwk.json",
24| "uri_puk_idp_sig": "http://url.des.idp/idpSig/jwk.json",
25| "subject_types_supported": [ "pairwise" ],
26| "id_token_signing_alg_values_supported": [ "BP256R1" ],
27| "response_types_supported": [ "code" ],
28| "scopes_supported": [ "openid", "e-rezept", "pairing" ],
29| "response_modes_supported": [ "query" ],
30| "grant_types_supported": [ "authorization_code" ],
31| "acr_values_supported": [ "gematik-ehealth-loa-high" ],
32| "token_endpoint_auth_methods_supported": [ "none" ],
33| "code_challenge_methods_supported": [ "S256" ]
34|}
35|.<SIGNATURE>

Hinweis: Der "kid" des "puk_disc_sig" (Zeile 3) Schlüssels im Header des Discovery Document wird nach einem Schlüsselwechsel im UUID7-Format sein

Neues in Kapitel 7.8 Aufbau der JSON Web Key Sets

Kapitel 7.8.1 Aufbau vor/nach einem Schlüsselwechsel

Im folgenden werden exemplarisch die Strukturen und Inhalte der verschiedenen Bereitstellungsorte (signed_jwks_uri, jwks_uri, uri_puk_idp_enc, uri_puk_idp_sig) vor einem Schlüsselwechsel dargestellt. Die aufgeführten Schlüssel sind allen Clientsystemen bereits bekannt und werden in diesen auch verarbeitet, also enc-Schlüssel zum Verschlüsseln benutzt und sig-Schlüssel zur Verifikation herangezogen.

Beispiel dekodierte (signed_jwks_uri) signed_jwks.jws

01|<HEADER>.{
02|   "keys": [
03| {
04|    "kid": "01981609-b701-789b-a5f4-4a24bcd0d347",
05| "alias": "puk_idp_sig",
06| "use": "sig",
07| "kty": "EC",
08| "crv": "BP-256",
09|   "x": "pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
10| "y": "qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
11| "x5c": [
12|   "<Zertifikat im Base64 ASN.1 DER-Encoding>"
13| ]
14| },
15| {
16|   "kid": "01981832-c2d6-7c00-ad32-688ed41831e8",
17|   "alias": "puk_idp_enc",
18|   "use": "enc",
19|   "kty": "EC",
20|   "crv": "BP-256",
21|   "x": "pkU8LlTZsoGTloO7yjIkV626aGtwpelJ2Wrx7fZtOTo",
22|   "y": "VliGWQLNtyGuQFs9nXbWdE9O9PFtxb42miy4yaCkCi8"
23|   },
24| {
25|   "kid": "01981832-f279-738d-b0ba-f803d7638cfb",
26|   "alias": "puk_idp_sig_sek",
27|   "use": "sig",
28|   "kty": "EC",
29|   "alg": "ES256",
30|   "crv": "P-256",
31|   "x": "sk8Cig9IjJqATxrJkWRdw2gJ7Qut7ygToC8o3z2C_IU",
32|   "y": "LGXTzotnGJuMThRp0QWa2HldCfNoxbMh-PownRgAKko"
33|    },
24| {
25|   "kid": "019975cb-c3e7-7e9e-9988-76bb0efd8684",
26|   "alias": "puk_disc_sig",
27|   "alg": "BP256R1",
28|   "x5c" : [
29|   "<Zertifikat im Base64 ASN.1 DER-Encoding (nicht URL-safe)>"
30| ]
31|    }
32|   ]
33|}.<SIGNATURE>

Die im vorherigen signed_jwks.jws Beispiel gezeigten Schlüssel lassen sich nach den Vorgaben von A_27937-* als jwks.json wie folgt darstellen. Dieser Bereitstellungsort enthält nicht den "puk_disc_sig", da dieser im JWT-Header des Discovery Document enthalten ist.

Beispiel (jwks_uri) jwks.json

01|{
02| "keys": [
03| {
04| "kid": "puk_idp_sig",
05| "use": "sig",
06| "kty": "EC",
07| "crv": "BP-256",
08| "x": "pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
09| "y": "qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
10| "x5c": [
11| "<Zertifikat im Base64 ASN.1 DER-Encoding>"
12| ]
13| },
14| {
15| "kid": "puk_idp_enc",
16| "use": "enc",
17| "kty": "EC",
18| "crv": "BP-256",
19| "x": "pkU8LlTZsoGTloO7yjIkV626aGtwpelJ2Wrx7fZtOTo",
20| "y": "VliGWQLNtyGuQFs9nXbWdE9O9PFtxb42miy4yaCkCi8"
21| },
22| {
23| "kid": "puk_idp_sig_sek",
24| "use": "sig",
25| "kty": "EC",
26| "alg": "ES256",
27| "crv": "P-256",
28| "x": "sk8Cig9IjJqATxrJkWRdw2gJ7Qut7ygToC8o3z2C_IU",
29| "y": "LGXTzotnGJuMThRp0QWa2HldCfNoxbMh-PownRgAKko"
30| }
31| ]
32|}

Nach A_27962-* ist der encryption key aus der signed_jwks.jws nach den Vorgaben von A_27937-* wie folgt in die enc_jwk.json zu übernehmen:

Beispiel (uri_puk_idp_enc) enc_jwk.json

Nach A_27962-* ist der signature key aus der signed_jwks.jws nach den Vorgaben von A_27937-* wie folgt in die sig_jwk.json zu übernehmen:

Beispiel (uri_puk_idp_sig) sig_jwk.json

Kapitel 7.8.2 Aufbau während der puk_idp_sig Schlüsselwechsel-Phase

Im Kapitel 7.8.1 wurde gezeigt, wie die Schlüssel über die verschiedenen Bereitstellungsorte abzubilden sind.

Im Kapitel 7.8.2 wird nun exemplarisch gezeigt, wie die Schlüssel in den Bereitstellungsorten abzubilden sind, wenn ein neuer Signaturschlüssel hinzu kommt. Der neue Schlüssel wird jedoch noch nicht verwendet. Es ist nur ein gültiger Signatur- und Verschlüsselungsschlüssel vorhanden.

Der neue Signaturschlüssel (im Beispiel: "01981831-b7a6-7e59-a148-e1797eefd02e") wird in die signed_jwks.jws aufgenommen, so dass Client-Systeme diesen in ihren Truststore importieren können, bevor die erstmalige Nutzung dieses Signaturschlüssels durch den IDP-Dienst erfolgt.

Wenn der IDP-Dienst anschließend auf diesen neuen Signaturschlüssel wechselt, diesen also produktiv nutzt, entsprechen die Ausgaben strukturell wieder den Beispielen in Kapitel 7.8.1, mit dem Unterschied, dass der Schlüssel (im Beispiel: "01981831-b7a6-7e59-a148-e1797eefd02e") an die Stelle des alten Schlüssels (im Beispiel: "01981609-b701-789b-a5f4-4a24bcd0d347") tritt.

Beispiel dekodierte (signed_jwks_uri) signed_jwks.jws

01|<HEADER>.{
02|   "keys": [
03|   {
04|   "kid": "01981831-b7a6-7e59-a148-e1797eefd02e",
05| "alias": "puk_idp_sig",
06|   "use": "sig",
07| "kty": "EC",
08| "crv": "BP-256",
09| "x": "rugLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXvv4",
10| "y": "aDNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dCeB",
11|   "x5c": [
12|   "<Zertifikat im Base64 ASN.1 DER-Encoding>"
13|   ]
14| },
15| {
16|    "kid": "01981609-b701-789b-a5f4-4a24bcd0d347",
17| "alias": "puk_idp_sig",
18| "use": "sig",
19| "kty": "EC",
20| "crv": "BP-256",
21|   "x": "pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
22| "y": "qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
23| "x5c": [
24|   "<Zertifikat im Base64 ASN.1 DER-Encoding>"
25| ]
26| },
27| {
28|   "kid": "01981832-c2d6-7c00-ad32-688ed41831e8",
29|   "alias": "puk_idp_enc",
30|   "use": "enc",
31|   "kty": "EC",
32|   "crv": "BP-256",
33|   "x": "pkU8LlTZsoGTloO7yjIkV626aGtwpelJ2Wrx7fZtOTo",
34|   "y": "VliGWQLNtyGuQFs9nXbWdE9O9PFtxb42miy4yaCkCi8"
35|   },
36| {
37|   "kid": "01981832-f279-738d-b0ba-f803d7638cfb",
38|   "alias": "puk_idp_sig_sek",
39|   "use": "sig",
40|   "kty": "EC",
41|   "alg": "ES256",
42|   "crv": "P-256",
43|   "x": "sk8Cig9IjJqATxrJkWRdw2gJ7Qut7ygToC8o3z2C_IU",
44|   "y": "LGXTzotnGJuMThRp0QWa2HldCfNoxbMh-PownRgAKko"
45|    },
46| {
47|   "kid": "019975cb-c3e7-7e9e-9988-76bb0efd8684",
48|   "alias": "puk_disc_sig",
49|   "alg": "BP256R1",
50|   "x5c" : [
51|   "<Zertifikat im Base64 ASN.1 DER-Encoding (nicht URL-safe)>"
52| ]
53|    }
54|   ]
55|}.<SIGNATURE>

An den Inhalten der jwks.json ändert der neu aufgenommene Signaturschlüssel (im Beispiel: "01981831-b7a6-7e59-a148-e1797eefd02e") nichts, da die Abbildung nach A_27937-* als jwks.json vorsieht, nur den aktuell verwendeten Signaturschlüssel an dieser Stelle auszugeben.

Beispiel (jwks_uri) jwks.json - unverändert im Vergleich zur Darstellung in Kap. 7.8.1

An den Inhalten der enc_jwk.json ändert der neu aufgenommene Signaturschlüssel (im Beispiel: "01981831-b7a6-7e59-a148-e1797eefd02e") nichts, da hier nur der Verschlüsselungsschlüssel ausgegeben wird.

Beispiel (uri_puk_idp_enc) enc_jwk.json - unverändert im Vergleich zur Darstellung in Kap. 7.8.1

An den Inhalten der sig_jwk.json ändert der neu aufgenommene Signaturschlüssel (im Beispiel: "01981831-b7a6-7e59-a148-e1797eefd02e") nichts, da die Abbildung nach A_27937-* als jwks.json vorsieht, nur den aktuell verwendeten Signaturschlüssel an dieser Stelle auszugeben.

Beispiel (uri_puk_idp_sig) sig_jwk.json - unverändert im Vergleich zur Darstellung in Kap. 7.8.1

Kapitel 7.8.3 Aufbau während der puk_idp_enc Schlüsselwechsel-Phase

Im Kapitel 7.8.2 wurde gezeigt, wie die Schlüssel über die verschiedenen Bereitstellungsorte abzubilden sind, während ein neuer Signaturschlüssel dazu kommt. Dieser neue Signaturschlüssel zu diesem Zeitpunkt jedoch noch nicht zum Signieren benutzt wird.

Es wird in diesem Kapitel exemplarisch gezeigt, wie die Schlüssel in den Bereitstellungsorten abzubilden sind, wenn ein neuer Verschlüsselungsschlüssel hinzu kommt.

Der neue Verschlüsselungsschlüssel (im Beispiel: "01982cab-c519-7890-9d21-edecac5b591a") ist sofort gültig und unverzüglich durch Drittsysteme zu verwenden, wenn Inhalte verschlüsselt an den IDP-Dienst übertragen werden sollen. Der bisherige Schlüssel (im Beispiel: "01981832-c2d6-7c00-ad32-688ed41831e8") wird mit dem Attribut "deprecated" und mit dem Zeitstempel vom Zeitpunkt, als der neue Schlüssel in das Key Set aufgenommen wurde, versehen.

Beispiel dekodierte (signed_jwks_uri) signed_jwks.jws

01|<HEADER>.{
02|   "keys": [
03| {
04|    "kid": "01981609-b701-789b-a5f4-4a24bcd0d347",
05| "alias": "puk_idp_sig",
06| "use": "sig",
07| "kty": "EC",
08| "crv": "BP-256",
09|   "x": "pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
10| "y": "qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
11| "x5c": [
12|   "<Zertifikat im Base64 ASN.1 DER-Encoding>"
13| ]
14| },
15| {
16| "kid": "01982cab-c519-7890-9d21-edecac5b591a",
17|   "alias": "puk_idp_enc",
18| "use": "enc",
19|   "kty": "EC",
20|   "crv": "BP-256",
21| "x": "FP8L87ijwzRoELmSouPSrzhYO3BfmXKNDvJlrI1b8Bc=",
22| "y": "pUOnVot6NYYs6_xKluDOB30-BuWwvoxVd2-Ww1Gy5Ao="
23|   },
24| {
25|   "kid": "01981832-c2d6-7c00-ad32-688ed41831e8",
26|   "alias": "puk_idp_enc",
27|   "use": "enc",
28|   "kty": "EC",
29|   "crv": "BP-256",
30|   "x": "pkU8LlTZsoGTloO7yjIkV626aGtwpelJ2Wrx7fZtOTo",
31|   "y": "VliGWQLNtyGuQFs9nXbWdE9O9PFtxb42miy4yaCkCi8",
32|   "deprecated": 1752752527,
33|   },
34| {
35|   "kid": "01981832-f279-738d-b0ba-f803d7638cfb",
36|   "alias": "puk_idp_sig_sek",
37|   "use": "sig",
38|   "kty": "EC",
39|   "alg": "ES256",
40|   "crv": "P-256",
41|   "x": "sk8Cig9IjJqATxrJkWRdw2gJ7Qut7ygToC8o3z2C_IU",
42|   "y": "LGXTzotnGJuMThRp0QWa2HldCfNoxbMh-PownRgAKko"
43|    },
44| {
45|   "kid": "019975cb-c3e7-7e9e-9988-76bb0efd8684",
46|   "alias": "puk_disc_sig",
47|   "alg": "BP256R1",
48|   "x5c" : [
49|   "<Zertifikat im Base64 ASN.1 DER-Encoding>"
50| ]
51|    }
52|   ]
53|}.<SIGNATURE>

Mit Aufnahme des neuen Verschlüsselungsschlüssel (im Beispiel: "01982cab-c519-7890-9d21-edecac5b591a") in die signed_jwks.jws ändert sich die Abbildung in der jwks.json gemäß A_27937-* dahingehend, dass der neue Schlüssel den bisherigen Schlüssel (im Beispiel: "01981832-c2d6-7c00-ad32-688ed41831e8") dort ersetzt.

Beispiel (jwks_uri) jwks.json

01|{
02| "keys": [
03| {
04| "kid": "puk_idp_sig",
05| "use": "sig",
06| "kty": "EC",
07| "crv": "BP-256",
08| "x": "pogLhoK59j_BX7OKqZWQ0GkEckCbr2IJ5HZLRLkXyn8",
09| "y": "qBNddqxoOK_2Vd5ocnuQtP1q_PuRslxfAQjv4E4dReA",
10| "x5c": [
11| "<Zertifikat im Base64 ASN.1 DER-Encoding>"
12| ]
13| },
14| {
15| "kid": "puk_idp_enc",
16| "use": "enc",
17| "kty": "EC",
18| "crv": "BP-256",
19| "x": "FP8L87ijwzRoELmSouPSrzhYO3BfmXKNDvJlrI1b8Bc=",
20| "y": "pUOnVot6NYYs6_xKluDOB30-BuWwvoxVd2-Ww1Gy5Ao="
21| },
22| {
23| "kid": "puk_idp_sig_sek",
24| "use": "sig",
25| "kty": "EC",
26| "alg": "ES256",
27| "crv": "P-256",
28| "x": "sk8Cig9IjJqATxrJkWRdw2gJ7Qut7ygToC8o3z2C_IU",
29| "y": "LGXTzotnGJuMThRp0QWa2HldCfNoxbMh-PownRgAKko"
30| }
31| ]
32|}

Mit Aufnahme des neuen Verschlüsselungsschlüssels (im Beispiel: "01982cab-c519-7890-9d21-edecac5b591a") in die signed_jwks.jws ändert sich auch die Abbildung in der enc_jwk.json gemäß A_27937-* dahingehend, dass der neue Schlüssel den bisherigen Schlüssel (im Beispiel: "01981832-c2d6-7c00-ad32-688ed41831e8") dort ersetzt.

Beispiel (uri_puk_idp_enc) enc_jwk.json

An den Inhalten der sig_jwk.json ändert sich hier nichts, da der Verschlüsselungsschlüssel hier nicht enthalten ist.

Beispiel (uri_puk_idp_sig) sig_jwk.json - unverändert im Vergleich zur Darstellung in Kap. 7.8.1

3 Änderungen in gemSpec_Perf

Der Schlüsselwechselprozess des IDP-Dienstes ist derzeit so gestaltet, dass der Anbieter des IDP-Dienstes eine "harte" Umstellung (hard cutover) mit Vorankündigung (per TI-ITSM-Change) durchführt.

Zukünftig wird in einer Übergangsphase das neu zu verwendende Schlüsselmaterial bereits bekannt gemacht, während das aktuelle Schlüsselmaterial noch genutzt werden kann.

Die Bekanntmachung erfolgt über eine parallel zur existierenden "jwks_uri" im Discovery Document des IDP-Dienstes hinterlegten neuen "signed_jwks_uri". Die Client-Systeme können sich entscheiden, welche Variante für sie besser geeignet ist.
Im neuen E-Mail-Report berichtet der Anbieter des IDP-Dienstes täglich der gematik über die Nutzung der beiden Schnittstellen.

3.1.1 E-Mail-Report IDP-Dienst

neu

A_27774 - E-Mail-Report - Spezifika IDP-Dienst - Lieferung

Der Anbieter IDP-Dienst MUSS täglich für den jeweiligen Vortag einen Report an [reporting@gematik.de] schicken, in dem die aufgetretenen Client-ID-/UserAgent-Kombinationen mit
der Anzahl der Aufrufe der jwks_uri [gem. A_27963-*] im Feld idpdJwksUri [gem. A_27710-*] und der Anzahl der Aufrufe der signed_jwks_uri [gem. A_20458-*] im Feld idpdSignedJwksUri [gem. A_27710-*] berichtet werden.
Der Versand des Reports MUSS mit einem Vorlauf von mindestens 14 Kalendertagen nach Aufforderung der gematik an- oder wieder abgeschaltet werden können.
Das Default-Zeitintervall ist täglich, beginnend mit 00:00:00.
Der Anbieter IDP-Dienst MUSS beim Versand des Reports folgende Vorgaben einhalten:

Zieladresse: [reporting@gematik.de]
Betreff: IDP-Report-ClientId_YYYYDDMM
Reportdatei als Anhang der E-Mail mit dem Dateinamen: IDP-Report-ClientId_YYYYDDMM.json

Die angehängte JSON-Datei MUSS dem vorgegebenen Format [gem. A_27710-*] entsprechen.

Hinweis: Groß- und Kleinschreibung von Betreff und Dateinamen sind einzuhalten! YYYYDDMM sind durch Jahr, Monat und Tag des Berichtsdatums zu ersetzen.
[<=]

A_27710 - E-Mail-Report - Spezifika IDP-Dienst - Format

Der Anbieter IDP-Dienst MUSS die angehängte JSON-Datei der E-Mail [gem. A_27774-*] in folgendem Format verwenden:

{
"date":"<Datum für das die Werte erfasst wurden im konkreten Format: : YYYY-MM-DD>",
"ci": "<CI-ID der abgefragten Produktinstanz gemäß [A_17764-*], als String>",
"idpdJwksUri": [
{

"total": <Anzahl aller anfragenden Clientsysteme mit gleichem useragent, als Integer>,
"clientId" : "<Client-ID vergeben durch die gematik, sofern vorhanden, Datentyp String>",
"useragent": "<User-Agent gemäß Anforderungslage für Clientsysteme am Fachdienst [A_24060-*], Datentyp String>"

}
] ,
"idpdSignedJwksUri": [
{

}

]

}

Hinweis: Die beiden Felder "idpdJwksUri" und "idpdSignedJwksUri" sind jeweils ein Array und für jeden User-Agent zu befüllen.
Sollten die Informationen für die Client-ID nicht vorliegen, gilt für diesen Parameter A_22513-*. [<=]

4 Änderungen in Steckbriefen

4.1 Änderungen in gemProdT_IDP-Dienst_PTV

Anmerkung: Die Anforderungen der folgenden Tabelle stellen einen Auszug dar und verteilen sich innerhalb der Tabelle des Originaldokuments gemProdT_IDP-Dienst_PTV_2.8.0-0_V1.0.0. Alle Anforderungen der Tabelle des Originaldokuments, die in der folgenden Tabelle nicht ausgewiesen sind, bleiben unverändert bestehenden.

Tabelle 1: Anforderungen zur funktionalen Eignung "Produkttest/Produktübergreifender Test"

Afo-ID	Afo-Bezeichnung	Quelle (Referenz)
A_20458-02	Inhalte des Discovery Document	gemSpec_IDP_Dienst
A_27936	Signaturschlüssel des JWK-Schlüsselsets in signiertem Format	gemSpec_IDP_Dienst
A_27937	Konsistente Repräsentation des JWK-Schlüsselsets in zwei Formaten (befristet)	gemSpec_IDP_Dienst

4.2 Änderungen in gemAnbT_IDP-Dienst_ATV

Anmerkung: Die Anforderungen der folgenden Tabelle stellen einen Auszug dar und verteilen sich innerhalb der Tabelle des Originaldokuments gemAnbT_IDP-Dienst_ATV_1.1.0_V1.0.0. Alle Anforderungen der Tabelle des Originaldokuments, die in der folgenden Tabelle nicht ausgewiesen sind, bleiben unverändert bestehenden.

Tabelle 2: Anforderungen zur funktionalen Eignung "Produkttest/Produktübergreifender Test"

Afo-ID	Afo-Bezeichnung	Quelle (Referenz)
A_20458-03	Inhalte des Discovery Document	gemSpec_IDP_Dienst
A_27963	jwks_uri im Discovery Document (befristet)	gemSpec_IDP_Dienst
A_27962	PUK_IDP_SEK und PUK_IDP_ENC uri im Discovery Document (befristet)	gemSpec_IDP_Dienst
A_28376	Inhalte des signierten JWK-Schlüsselsets	gemSpec_IDP_Dienst
A_27940	Einheitliche Schlüssel-Identifikatoren	gemSpec_IDP_Dienst
A_27938	Ergänzung des Parameters „alias“ in signierten JWK-Schlüsselsets	gemSpec_IDP_Dienst
A_27941	Zweifaches Vorkommen von JWK mit gleichem „alias“ im Key-Set während des Übergangszeitraums beim Schlüsselwechsel	gemSpec_IDP_Dienst

Tabelle 3: Anforderungen zur betrieblichen Eignung "Anbietererklärung"

Afo-ID	Afo-Bezeichnung	Quelle (Referenz)
A_28376	Inhalte des signierten JWK-Schlüsselsets	gemSpec_IDP_Dienst
A_28381	signed_JWKS IDP_SIG Schlüssel Verwendung und Nachhaltung	gemSpec_IDP_Dienst
A_28382	signed_JWKS DISC_SIG Schlüssel Verwendung	gemSpec_IDP_Dienst