FSS & HSM - Zentrale Features

Private Schlüssel werden im HSM gespeichert.

Zertifikate werden im FSS gespeichert.

FSS Installation

Der FSS ist als Docker Image verfügbar. Eine Installationsanleitung inkl. FSS-UI ist unter folgendem Link zu finden: FSS Installation

Für die Absicherung des FSS API per oauth2 wird der Einsatz von Keycloak als Authorization-Server empfohlen.

Zur besseren Lastverteilung kann der FSS auch als Cluster betrieben werden. Hierfür muss die FSS Cluster Communication konfiguriert werden.

FSS REST API

Konfiguration des FSS erfolgt teilweise über die REST API des FSS. Die API ist auch für bestimmte Operationen zu nutzen, z.B. der Upload eines Zertifikats.

Weitere Details zur FSS REST API können über swagger abgerufen werden: https://<server>/fss/api/swagger-ui/index.html.

Unterstützende Scripte zum Zugriff auf die FSS REST API können hier (intern) gefunden werden.

Sperrlistenstatus im FSS

Der BDEW fordert, dass zu jedem Zertifikat der Sperrlistenstatus regelmäßig ermittelt wird. Ein Zertifikat mit fehlendem/unbekannten/gesperrten Sperrlistenstatus darf nicht benutzt werden.

Der Sperrlistenstatus der Zertifikate wird über den FSS abgebildet, Details dazu finden Sie hier.

Hierfür ist es nötig, Sperrlisten regelmäßig abzurufen. Dies kann über die B2B und ihren CrlDownloadScheduler erfolgen.

Für Testsysteme mit selbstsignierten Testzertifikaten sind spezielle Teststrategien (intern) notwendig.

Anbindung HSM an FSS

Der FSS ist in der Lage auf das HSM zuzugreifen. Hierfür muss das HSM zunächst im FSS konfiguriert werden. Die Konfiguration erfolgt über die FSS REST API.

Zunächst muss die HSM Serveradresse konfiguriert werden. Hierfür ist folgende API zu nutzen: POST /fss/api/v1/hsms, Body:

{
    "hsm": {
        "name": "descriptive name",
        "deviceAddress": "Port@Server"
    }
}

Als Adresse kann ein Loadbalancer vor dem HSM Cluster angegeben werden. Alternativ können mehrere HSM Adressen Komma-separiert zum Betrieb im Failover-Modus angegeben werden.

Die zugehörige automatisch generierte HSM ID kann über folgende REST-API abgerufen werden: GET /fss/api/v1/hsms

Eine HSM Anbindung kann wie folgt entfernt werden: DELETE /fss/api/v1/hsms/<hsmId>

Beim Zugriff auf das HSM muss der FSS auf das /tmp Verzeichnis lesend & schreibend zugreifen. Falls der Zugriff eingeschränkt ist, kann das Verzeichnis wie folgt angepasst werden:

JAVA_OPTS="-Djava.io.tmpdir=/tmp"

Um die Anbindung abzuschließen, muss die Mandantentrennung berücksichtigt werden. Diese wird im nächsten Abschnitt erläutert.

Die HSM Anbindung kann nach Konfiguration der Mandantentrennung wie folgt getestet werden: GET /fss/api/v1/hsms/validation.

Dieser Endpunkt prüft den Zugriff auf das HSM mit Hilfe des dem Mandanten (Client) zugeordneten Users. Der zugehörige Slot wird über den Endpunkt nicht getestet.

Anbindung HSM an FSS kann über Systemeigenschaften weiter konfiguriert werden. Die folgende Liste von Eigenschaften und deren Standardwert sind:

Beispielkonfiguration:

JAVA_OPTS: "-DHSM_MIN_EVICTABLE_IDLE_MILLIS=360000 -DHSM_MIN_IDLE_CONNECTIONS_PER_SLOT=8 -DHSM_MAX_IDLE_CONNECTIONS_PER_SLOT=8 -DHSM_POOL_EVICTION_PERIOD=180000 -DHSM_MAX_POOLED_CONNECTIONS=1000"

DHSM_MIN_EVICTABLE_IDLE_MILLIS: Dieser Wert bestimmt, wann Verbindungen spätestens getrennt und neu aufgebaut werden. Dieser Zeitraum muss kleiner sein als die Zeit, nach der die Firewall oder das HSM die Verbindung trennt. Per Default trennt das HSM nach 15 Minuten die Verbindung.

DHSM_POOL_EVICTION_PERIOD: Dieser Wert bestimmt, wie oft der Connection Pool bereinigt wird. Dieser Wert soll kleiner sein als DHSM_MIN_EVICTABLE_IDLE_MILLIS

HSM_MAX_POOLED_CONNECTIONS: hier sollte mit ca 10 Connections je Slot kalkuliert werden.

HSM Timeout Handling

vgl interne Doku.

Mandantentrennung

Ein Mandant im AS4 System bildet einen Marktpartner ab. Der Mandant wird durch die MPID eines Marktpartners repräsentiert.

HSM Mandantentrennung

HSM Mandantentrennung erfolgt über HSM Slots. Ein Slot repräsentiert einen Mandanten.

Eine Möglichkeit zum Anlegen von HSM Slots ist hier (intern) beschrieben.

Zum Überprüfen der angelegten HSM Slots:

• Führen Sie das CryptoServer Administration Tool (intern) (CAT) aus. Das CAT-Tool versucht standardmäßig, eine Verbindung zur HSM-Instanz auf Port 3001 herzustellen.

• Sobald der Slot erstellt wurde, notieren Sie sich die Benutzer-PIN, da diese später benötigt wird. Um dies zu überprüfen, melden Sie sich mit “Login User” an und geben Sie die Benutzer-PIN ein. Eine erfolgreiche Anmeldung sieht wie folgt aus:

  

FSS Mandantentrennung

FSS Mandantentrennung erfolgt über FSS Clients. Ein FSS Client kann einen Mandanten repräsentieren. Als Client-Name ist die MPID des Mandanten zu wählen.

Darüber hinaus kann ein separater Client für übergreifende Zertifikate genutzt werden, z.B. Ausstellerzertifikate & Partnerzertifikate. Als name ist hier shared-client zu wählen.

Ein Client wird über die REST API des FSS angelegt: POST /fss/api/v1/clients, Body:

{
	"name": "MPID / shared-client",
	"description": "optional, e.g. name & role of marketpartner, AS4"
}

Die zugehörige automatisch generierte Client ID kann über folgende REST-API abgerufen werden: GET /fss/api/v1/clients/<client-name>

Eine Liste aller Clients kann wie folgt angezeigt werden: GET /fss/api/v1/clients

Ein Client kann wie folgt gelöscht werden: DELETE /fss/api/v1/clients/<clientId>

Die FSS Clients, die im Kontext von AS4 eingesetzt werden, dürfen ausschließlich AS4 bezogene Zertifikate enthalten. Falls der FSS darüber hinaus für andere Zwecke genutzt werden soll (z.B. Verwaltung von Mail/AS2 Zertifikaten), so sind dafür separate Clients zu nutzen.

Falls Sie den FSS bisher genutzt haben, ohne explizit Clients zu konfigurieren, so wurden alle Zertifikate im Standard Client undefined hinterlegt. Mehr Details Zur FSS Mandantentrennung finden Sie hier.

Anbindung FSS Client an HSM Slot

Um die Anbindung des FSS ans HSM abzuschließen, müssen die Slots sowie der Bezug zwischen Client & Slot konfiguriert werden. Für jede Client-Slot-Beziehung muss ein Eintrag angelegt werden. Der shared-client wird keinem Slot zugeordnet.

Beim Definieren von Client-Slot Beziehungen sind folgende Aspekte zu berücksichtigen:

• Ein FSS-Client kann maximal einem Slot zugeordnet werden.
• Ein Slot entspricht genau einem Mandanten. Falls mehrere FSS-Clients auf den gleichen Slot zugreifen sollen, müssen alle FSS-Clients zum gleichen Mandanten gehören.

Zum Anlegen einer Client-Slot-Beziehung ist folgende FSS API zu nutzen: POST /fss/api/v1/hsms/slots, Body:

{
	"name": "slot name",
	"username": "slot login",
	"password": "slot password",
	"hsm": {
		"id": "hsm id"
	},
	"client": {
		"name": "MPID"
	}
}

Die konfigurierten Slots können über folgende API geprüft werden: GET /fss/api/v1/hsms/<hsmId>/slots. Die zurückgelieferte ClientId 0 ist zu ignorieren, der Client wird in der Response anhand des ClientName identifiziert.

Ein Slot kann wie folgt entfernt werden: DELETE /fss/api/v1/hsms/slots/<slotId>

HSM Schlüssel Metadaten inspizieren

Starten Sie die KeyCat.jar, die vom HSM Hersteller bereitgestellt wird.

Wenn die HSM-Instanz läuft und der Slot korrekt konfiguriert ist, sollte Folgendes zu sehen sein:

Melden Sie sich beim SLOT_0000 mit dem Benutzer USR_0000 an. Wenn ein Schlüssel erfolgreich gespeichert wurde, sollte der Bildschirm wie folgt aussehen:

Nächste Schritte

Anwendungen verbinden

Folgende Anwendungen greifen auf die FSS REST API zu:

• CSR-Service (CSR Erstellung)
• AS4-Crypto-Operations (Signatur & Verschlüsselung)
• AS4-Outbound-Sender (TLS)
• AS4-Inbound-Endpoint (TLS)

Zertifikate hochladen

Zum Abschluss der Konfiguration ist der FSS mit Zertifikaten zu befüllen.

Partner und Ausstellerzertifikate können über die FSS-UI eingespielt werden. Für Partnerzertifikate ist als Alias die MPID des Partners zu verwenden. Je Partner sind drei Zertifikate hochzuladen. Jedes Zertifikat des Triples erfüllt eine andere Aufgabe: Nachrichten-Signatur, Inhalt-Verschlüsselung & TLS. Der Alias von Ausstellerzertifikaten ist frei wählbar.

Wichtig ist außerdem, dass dem FSS in der Keycloak Konfiguration keine SMPKI Rollen zugewiesen sind. Sollte dies der Fall sein, wird der Alias überschrieben.

Für die Erstellung von Mandantenzertifikaten kann der CSR-Service genutzt werden.