AS4 Certificate Creation | Produktdokumentation

AS4 Certification Creation Documentation

Für jeden Mandanten müssen Schlüssel & Zertifikate erstellt werden. Diese werden dann für die AS4-Marktkommunikation genutzt.

Der CSR-Service unterstützt den Zertifikat-Erstellung-Prozess. Hier wird das Vorgehen beschrieben.

Domainsicht

Domain View

Voraussetzungen

FSS & HSM installiert.
CSR-Service installiert.

Prozess Übersicht

Es wird zwischen dem initialen und dem Erneuerung-Prozess unterschieden. Der Erneuerung-Prozess muss auch direkt in Anschluss des initialen Prozesses durchgeführt werden.

Darüber hinaus bietet die CSR-Service-API auch die Möglichkeit, selbst-signierte Zertifikate zu erstellen.

Im Folgenden wird vom Bundle gesprochen, da immer 3 “gebündelte” Zertifikate benötigt werden. Diese erfüllen die Aufgaben Signatur, Verschlüsselung und TLS.

Initialer Prozess

Voraussetzung: der Antragsteller hat sich gegenüber der Sub-CA authentifiziert und ist bekannt.

Schlüsselpaar-Bundle erstellen (über CSR-Service API)
CSR-Bundle erstellen (über CSR-Service API)
CSR-Bundle per Mail an Sub-CA übermitteln
Zertifikat-Bundle per Mail von Sub-CA erhalten
Zertifikat-Bundle an FSS übermitteln (über FSS API)

Erneuerung-Prozess

Der Erneuerungsprozess kann vom CSR-Service vollautomatisch ausgeführt werden. Der baldige Ablauf des Zertifikats löst die Erneuerung automatisch aus. Alternativ kann der Prozess über die API gestartet werden.

Voraussetzung: der initiale Prozess wurde erfolgreich durchgeführt.

Schlüsselpaar-Bundle erstellen
CSR-Bundle erstellen
CSR-Bundle per Webservice an Sub-CA übermitteln und sofort
Zertifikat-Bundle per Webservice von Sub-CA erhalten
Zertifikat-Bundle an FSS übermitteln

Erstellen des Schlüssel-Paares

Dieser Schritt ist vollständig enthalten im Script des nächsten Schrittes Erstellen des CSRs.

Zum Erstellen des Schlüsselpaares senden wir einen Post Request an den CSR Service. Dazu nennen wir den Clientnamen und den Alias. Zu beachten ist hierbei bei, dass der Alias entweder mit ENC, SIGN, oder TLS endet. Für alle drei Verwendungszwecke muss ein Schlüsselpaar erstellt werden. Der Alias sollte aus der ILN plus der jeweiligen Endung bestehen.

Die Anfrage (Request) erfolgt über die folgende URL:

POST http://localhost:3333/api/v1/generate/keyPair

Beispiel von POST-Request-Body:

 {
     "storedOnHsm": true,
     "client": {
        "name": "testClient"
      },
    "alias": AS4-PILOT-ENC,
    "algorithm": "ECDSA",
    "ellipticCurve": "brainpoolp256r1",
    "validFrom": "2000-01-01",
    "validTo": "2030-01-01"
}

Der private Schlüssel wird im HSM gespeichert.

Der Admin muss sich temporär den Schlüssel-Alias merken. Dieser wird später beim Zertifikatsupload benötigt.

Zugriff auf das HSM

Die folgende Doku ist leicht

Mit dem KeyCat.jar lässt sich auf Metadaten des privaten Schlüssels im HSM zugreifen. Siehe unter HSM Simulator Integration.

Anforderungen an DNS & AS4-Adresse

Bevor ein Zertifikat / CSR erstellt werden kann, muss die AS4-Adresse & DNS bekannt sein.

Important: Eine nachträgliche Änderung der Adresse / des DNS erfordert zwangsläufig ein Neu-Generieren der Zertifikate.

Important: Es muss sichergestellt sein, dass je Mandant (MPID) ein eigener DNS eingesetzt wird. Es genügt, wenn sich die Subdomäne unterscheidet. Der Port ist nicht Teil des DNS und genügt somit nicht als Unterscheidungskriterium.

Wir empfehlen die MPID als Teil des DNS (z.B. als Subdomäne) zu wählen.

Wir empfehlen unterschiedliche DNS für unterschiedliche Umgebungen (z.B. Test/Prod) zu vergeben.

Important: Bei der Vergabe der Adresse ist darauf zu achten, dass sie auf /as4 endet.

Als Port wird der Standard https Port 443 empfohlen. Gemäß BDEW sind alternativ auch Ports größer 1000 möglich.

Beispiel:

DNS: 9900000000001.test.blue-energy.de
AS4-Adresse: https://9900000000001.test.blue-energy.de/as4

Erstellen des CSRs

Der folgende Vorgang wird durch das Script initial-csr.generate.sh vollständig ausgeführt, vergleichen Sie hierzu den Abschnitt Scripte.

Nachdem das Schlüsselpaar erstellt worden ist, ist der öffentliche Schlüssel mit dem Alias und dem ClientName an den Endpoint zur Zertifikatserstellung im CSR Service zu übergeben.

DNS & AS4-Adresse sind im Script zu konfigurieren. Beachten Sie die Anforderungen an DNS & Adresse. Diese sind im vorherigen Abschnitt beschrieben.

Beachten Sie den öffentlichen Schlüssel im Base64-Format sowie die Details des privaten Schlüssels.

Die Anfrage (Request) erfolgt über die folgende URL: http://localhost:3333/api/v1/generate/csr
Der folgende POST Request ist leicht veraltet und wird in Kürze aktualisiert.
Beispiel von POST-Request-Body:

{
  "client": "99111111",
  "iln": "99111111",
  "email":"email",
  "as4Address":"https://blue-energy.de/99111111/as4",
  "dns":"blue-energy.de",
  "x500SubjectName": {
    "commonName": "99111111.EMT.MAK",
    "country": "DE",
    "street": "street",
    "postalCode": "postal_code",
    "locality": "locality",
    "state": "state"
  }
}

Achten Sie auch auf den Aufbau des commonName.

Als Rückgabe erhalten Sie neben dem CSR-Bundle auch die HSM-Aliase der zugehörigen Schlüssel. Speichern Sie diese ab, sie werden im nächsten Schritt wieder benötigt.

Das CSR-Bundle ist an die Sub-CA zu übergeben.

Zertifikatsupload

Von der Sub-CA erhalten Sie Ihre Zertifikate. Diese sind über die REST-API in den FSS zu laden.

Beim Upload muss neben dem Zertifikat auch der HSM Key Alias mitgegeben werden. Es ist der gleiche Alias zu verwenden, der beim Erstellen des zugehörigen privaten Schlüssels vergeben worden ist.

Für den Upload kann das Script cert-upload verwendet werden, vergleichen Sie hierzu den Abschnitt Scripte.

Upload von Aussteller Zertifikaten

Der Alias von Aussteller-Zertifikaten kann frei gewählt werden. Wir empfehlen den Subject Common Name zu nutzen.

Aussteller-Zertifikate haben keinen eingeschränkten Purpose. Geben Sie bitte deshalb folgenden Purpose an: [SIGN,ENC,TLS].

Zertifikatserneuerung

Die Sub-CAs sehen vor, dass das initiale Zertifikats-Triplet zeitnah erneuert wird.

Hierfür kann die API des CSR-Service genutzt werden: POST /renew/csr. Weitere Details können Swagger entnommen werden.

Für die Erneuerung baut der CSR-Service eine per mutual-TLS gesicherte Verbindung mit dem Webservice der Sub-CA auf.

Darüber hinaus müssen bald ablaufende Zertifikate rechtzeitig erneuert werden. Denn für die Erneuerung ist ein gültiges TLS Zertifikat notwendig.

Upload von Partner-Zertifikaten

Für alle Marktpartner, mit denen kommuniziert wird, die aber keine Mandanten sind, gilt:

Es müssen deren Zertifikate im FSS hochgeladen werden. Ein Zugriff auf die privaten Schlüssel ist nicht nötig.

Als Alias muss ebenfalls die MPID vergeben werden, als Purpose muss korrekt einer der folgenden 3 Werte gewählt werden: ENC / TLS / SIGN.

Aufteilung der Clients nach Mandant & Shared

Wenn Sie dem empfohlenen AS4 Standard folgen, verfügt der FSS mindestens über folgende Clients:

für jeden Mandanten existiert ein eigener Client
es existiert ein mandantenübergreifender geteilter Client für Partner- & Aussteller-Zertifikate

Beim Upload der Zertifikate ist somit zu beachten:

Mandantenzertifikate müssen im Client des Mandanten hochgeladen werden (inkl. der Zertifikateskette dieser Zertifikate) ** Fungiert dieser Mandant auch als Partner (kommuniziert also ein anderer Mandant mit diesem), so müssen Mandantenzertifikate außerdem als Partnerzertifikate im geteilten Client hochgeladen werden (inkl. Zertifikatskette). Hierbei darf keine HSM Referenz gesetzt werden.
Zertifikate der SubCA (zum Beispiel für den Webservice des CSR-Service) müssen im geteilten Client hochgeladen werden.
Partnerzertifikate müssen im geteilten Client hochgeladen werden.

Scripte

Zur Vereinfachung können die Workflows über Shell-Scripte zusammengefasst werden. Die Shell-Scripte der Entwicklung finden Arvato Mitarbeiter hier.

View Me Edit Me