Zum Hauptinhalt springen

Prüfung eines Security Event Token (SET)

Onlinedienste kontrollieren, ob der Zustelldienst eine Einreichung erhalten hat. Dazu rufen sie vom Zustelldienst das Ereignisprotokoll zu dem Vorgang ab, zu dem die Einreichung gehört. In diesem Protokoll dokumentiert der Zustelldienst in Form eines Security Event Token (SET), ob die Einreichung im Zustelldienst angekommen ist.
Im Folgenden ist beschrieben, in welcher Hinsicht Sie ein SET prüfen: Wurde zur Signierung dieses SETs ein zulässiges Verfahren verwendet? Wurden die kryptografischen Vorgaben eingehalten? Stammt dieses SET tatsächlich vom Zustelldienst oder Empfänger?

Hinweis

Wenn Sie ein SDK von FIT-Connect verwenden, dann können Sie sich auf den Aufruf der Schnittstelle zum SDK konzentrieren, weil die SDKs von FIT-Connect viele Details automatisch intern umsetzen, wie auch das Prüfen von SETs. Sie finden eine Beschreibung der SDKs im Hauptmenü unter "SDKs".

Prüfung eines Security Event Tokens​

Um eine vollständige Prüfung eines Security Event Tokens durchzuführen, MUSS zwingend sowohl die Einhaltung der (kryptografischen) Vorgaben als auch die Signatur geprüft werden. Die Prüfung der Signatur des SET ist abhängig vom ausstellenden System (Zustelldienst, Verwaltungssystem oder Onlinedienst). Aus technischer Sicht sollte auch das unter $schema angegebene SET-Payload-Schema validiert werden. Dies wird z. B. auch schon vom zuständigen Zustelldienst gemacht. Aktuell ist die Angabe eines SET-Payload-Schemas aber noch optional und kann nicht existieren. Dies wird in unspezifizierter Zukunft deprecated und alle SETs müssen ein valides SET-Payload-Schema verwenden und angeben. In dem Fall, dass das SET-Payload-Schema nicht angegeben ist, müssen trotzdem die kryptografischen Vorgaben bzw. die kryptografische Signatur validiert werden.

Warnung

Sowohl die Prüfung der kryptografischen Vorgaben, als auch die Prüfung der kryptografischen Signatur darf KEINESFALLS ausgelassen werden.

Prüfung der Einhaltung von kryptografischen Vorgaben und der Struktur​

Alle generierten Security Event Tokens MÜSSEN den Vorgaben aus RFC 7519 entsprechen und über folgende Header-Attribute verfügen:

FeldInhaltErläuterung
typsecevent+jwtWird gemäß RFC 8417, Abschnitt 2.3 auf den festen Wert "secevent+jwt" gesetzt.
algPS512Zur Signaturerstellung wird der Signaturalgorithmus RSASSA-PSS mit SHA-512 und MGF1 mit SHA-512 verwendet. Vorgabe gemäß BSI TR-02102 in der Version 2021-01 (Stand 24. März 2021).
kidKey-ID des zugehörigen Public KeysDie Key-ID des Public Key, mit dem die Signatur des JWT geprüft werden kann.

In der Payload des signierten SET MÜSSEN die folgenden standardisierten Felder gesetzt sein (Temporäre Ausnahme $schema):

FeldInhaltErläuterung
$schemaURL Referenz auf das verwendete SET-Payload-SchemaGibt das SET-Payload-Schema an, dem das SET entspricht. Dieses Schema wird auch vom Zustelldienst validiert.

Das Schema kann zur client-seitigen Validierung der SET Payload von der referenzierten URL bezogen werden. Auch eine client-seitige Validierung durch statisch hinterlegte Schema-Versionen ist möglich, solange die von uns vorgegebenen Versionen unterstützt werden. Mit diesem Schema stellt auch der Zustelldienst seine SETs aus.

jtiUUID des TokenDie JWT ID ist eine eindeutige ID des SET bzw. JWT. Es wird eine zufällige UUID verwendet.
issID des Token IssuersDiese 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.
iatTimestamp (UNIX-Format)Zeitpunkt der Ausstellung des SET.
subURI, die den Gegenstand des SET identifiziertDas Subject eines SET ist eine Kombination aus dem Schlüsselwort submission und der Id submissionId der Resource.
txnURI, die den Vorgang identifiziertAls "Transaction Identifier" wird die Vorgangsreferenz caseId angegeben.
eventsJSON-Objekt der Events in diesem Event-TokenDas Objekt events enthält genau ein Ereignis 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 kann leer sein oder weitergehende Informationen beinhalten (Siehe Ereignisse)
SET Beispiel
SET Header
{
  "typ": "secevent+jwt",
  "alg": "PS512",
  "kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980",
}
SET Payload
{
  "$schema": "https://schema.fitko.de/fit-connect/set-payload/1.0.0/set-payload.schema.json",
  "jti": "8538165b-9ce3-4097-871d-5b9581a3b4d9",
  "iss": "40847c29-06aa-40e2-bf28-c29884c694c4",
  "iat": 1622796532,
  "sub": "submission:02bf1d9f-282d-4abf-810a-c4104baf0afe",
  "txn": "case:452b5ee6-35df-441a-bd39-6141723cf914",
  "events": {
    "https://schema.fitko.de/fit-connect/events/accept-submission": {
      "authenticationTags": {
        "metadata": "XFBoMYUZodetZdvTiFvSkQ",
        "data": "UCGiqJxhBI3IFVdPalHHvA",
        "attachments": {
          "0b799252-deb9-42b0-98d3-c50d24bbafe0": "rT99rwrBTbTI7IJM8fU3El",
          "25abf553-0e53-43b9-a14a-1581b32a9ee5": "i7226HEB7IchCxNuh7lCiu",
          "046a9fa5-bed6-494b-aab6-d41056c6db79": "d48LxeolRdtFF4nzQibeYO"
        }
      }
    }
  }
}

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch einen Aufruf der SDK-Methode GetStatusForSubmissionAsync() der Klasse Sender automatisch mit abgedeckt:

sender.GetStatusForSubmissionAsync(sentSubmission);

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Codebeispiele - examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

Signaturprüfung eines vom Zustelldienst ausgestellten SET​

Um die Signatur eines SET zu überprüfen, welches vom Zustelldienst ausgestellt wurde, ist es notwendig auf die verwendeten Schlüssel zugreifen zu können. Der Zustelldienst stellt ein JSON Web Key Set (JWKS) öffentlich zugänglich über den Endpunkt GET /.well-known/jwks.json bereit. Ein Beispiel für ein JWKS ist in folgendem Ausschnitt dargestellt:

{
  "keys": [
    {
      "alg": "PS512",
      "e": "AQAB",
      "key_ops": [
        "verify"
      ],
      "kid": "6508dbcd-ab3b-4edb-a42b-37bc69f38fed",
      "kty": "RSA",
      "n": "65rmDz943SDKYWt8KhmaU…ga16_y9bAdoQJZRpcRr3_v9Q"
    },
    {
      "alg": "PS512",
      "e": "AQAB",
      "key_ops": [
        "verify"
      ],
      "kid": "14a70431-01e6-4d67-867d-d678a3686f4b",
      "kty": "RSA",
      "n": "wnqKgmQHSqJhvCfdUWWyi8q…yVv3TrQVvGtsjrJVjvJR-s_D7rWoBcJVM"
    }
  ]
}

Mit diesem JWK Set kann die Signatur eines Security Event Tokens überprüft werden. Hierfür muss der Schlüssel mit der passenden kid aus dem Header des SET’s im JWK Set gesucht werden. Nach Abschluss der Prüfung aller kryptografischen Vorgaben kann mit diesem und einer entsprechenden Bibliothek eine Signaturprüfung durchgeführt werden.

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch einen Aufruf der SDK-Methode GetStatusForSubmissionAsync() der Klasse Sender automatisch mit abgedeckt:

sender.GetStatusForSubmissionAsync(sentSubmission);

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

Hinweis

In der Stage- und Produktivumgebung ist das vom Zustelldienst für die Signatur der SET genutzte Schlüsselpaar über ein Zertifikat aus der Verwaltungs-PKI abgesichert (Attribut x5c des JWK). Für eine vollständige Prüfung der Authentizität der augestellen SET SOLLTE daher – analog zur Prüfung der öffentlichen Schlüssel im Rahmen der Verschlüsselung – eine Zertifikatsprüfung durchgeführt werden.

Signaturprüfung eines vom empfangenden System ausgestellten SET​

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.

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
SET Header
{
  "typ": "secevent+jwt",
  "alg": "PS512",
  "kid": "dd0409e5-410e-4d98-85b6-f81a40b8d980",
}
SET Payload
{
  "iss": "https://api.fitko.de/fit-connect/",
  "iat": 1622796532,
  "jti": "0BF6DBF6-CE7E-44A3-889F-82FE74C3E715",
  "sub": "submission:F65FEAB2-4883-4DFF-85FB-169448545D9F",
  "events": {
    "https://schema.fitko.de/fit-connect/events/accept-submission": {}
  },
  "txn": "case:F73D30C6-8894-4444-8687-00AE756FEA90"
}

Abruf des JWK zur Gültigkeitsprüfung des SET​

Mit der submissionId kann über den Endpunkt GET /v1/submissions/{submissionId} die zugehörige destinationId ermittelt werden. Hier ist das konkret der Wert 92f2f581-c89d-44a5-b834-1fe3f6fa48d5. Dabei können nur Submissions im Status Submitted oder Forwarded abgerufen werden.

Abfrage der destinationId einer Submission
GET /v1/submissions/F65FEAB2-4883-4DFF-85FB-169448545D9F
{
  "destinationId": "92f2f581-c89d-44a5-b834-1fe3f6fa48d5",
  // ...
}

Mit den zwei Informationen kid und destinationid kann nun der JWK zur Signaturprüfung abgerufen werden:

Beispiel: Abruf des JWK eines Zustellpunktes
$ KID=...
$ SUBMISSION_API=https://submission-api-testing.fit-connect.fitko.dev
$ DESTINATION_ID=...
$ curl -X GET \
    "$SUBMISSION_API/v1/destinations/$DESTINATION_ID/keys/$KID"
---
{
  "kty": "RSA",
  "e": "AQAB",
  "keyops": ["verify"],
  "x5c": [
    "LS0tLS1CRUdJTiBDRVJU...jN1NGKzQKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo="
  ],
  "x5t": "MTg6NTU6RUY6ME...MEM6QzM6ODQ6QjA6MkE6RkMK",
  "kid": "787f3a1c-7da7-44d7-9b79-9783b1ea9be8",
  "alg": "PS512",
  "n": "sX2DX7rG5BoJd23...FlxHZt8T6ZqjRa1QcFnkq3_M4-tk"
}

Validierung des SET mit Hilfe des JWK​

Die Verifikation des SET mit dem eben abgerufenen JWK ist – nach Abschluss der Prüfung aller kryptografischen Vorgaben – 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.

Diese Funktionalität wird durch das .NET-SDK bereits intern umgesetzt und ist durch einen Aufruf der SDK-Methode GetStatusForSubmissionAsync() der Klasse Sender automatisch mit abgedeckt:

sender.GetStatusForSubmissionAsync(sentSubmission);

Der Quellcode oben ist ein Auszug aus dem Projekt ConsoleAppExample, das im Repository Examples von FIT-Connect hinterlegt ist. Eine Beschreibung des .NET-SDKs finden Sie im Hauptmenü unter "SDKs > .NET-SDK".

Hinweis

In der Stage- und Produktivumgebung ist das von empfangenden Systemen (Subscriber) für die Signatur der SET genutzte Schlüsselpaar über ein Zertifikat aus der Verwaltungs-PKI abgesichert (Attribut x5c des JWK). Für eine vollständige Prüfung der Authentizität der ausgestellten SET SOLLTE daher – analog zur Prüfung der öffentlichen Schlüssel im Rahmen der Verschlüsselung – eine Zertifikatsprüfung durchgeführt werden.