CSR Service Dokumentation

Dieser Service ist ein innovativer Service, der sich auf die Erstellung und Verwaltung von Key-Pairs und Zertifikaten spezialisiert hat.

REST Endpoints:

Folgende Aufgaben lassen sich über REST abfragen:

  • Schlüsselpaar erzeugen
  • Certificate Signing Request initialisieren
  • Certificate Signing Request erneuern
  • Zertifikate (selbstsignierte) erstellen
  • Zertifikate uploaden
  • Certificate Signing Request downloaden

Darüber hinaus bietet die API Server-Health Informationen an. Ein KontextPath Präfix kann über folgende Property konfiguriert werden: server.servlet.contextPath. Der Port lässt sich über folgende Property konfigurieren: server.port=8080.

Schlüsselpaar erzeugen

Dieser Request erzeugt ein Schlüsselpaar für jeden der drei Anwendungsfälle Verschlüsselung, Signatur und TLS. Die privaten Schlüssel werden im HSM abgelegt, während der öffentliche Schlüssel über die Response erhalten werden kann. Dieser Request wird auch für die CSR (Certificate Signing Request) abgesetzt.

Request /as4-crypto-csr/api/v1/generate/keypairs:

{
    "client": "testClient",
    "iln": "332243",
    "validFrom": "2000-01-01",
    "validTo": "2030-01-01",
    "algorithm": "ECDSA",
    "ellipticCurve": "brainpoolp256r1",
    "storedOnHsm": true
}

Die wichtigsten Parameter sind:

  • client : HSM Client, Speicherort der Zertifikate
  • iln : ILN des Zertifikatsinhaber
  • validFrom : Beginn der Gültigkeit des Keypairs
  • validFrom : Ende der Gültigketi des Keypairs

Response:

[
  {
    "privateKey": {
      "alias": "332243-202309011704-ENC",
      "clientName": "testClient",
      "algorithm": "ECDSA"
    },
    "publicKey": "MFowFAYHKoZIzj0CAQYJKyQDAwIIAQEHA0IABFVuvASnjIuxUQSbF48EtzTVIJclqShIz/6VmP6X4mIXM3YjvKx2erbRq7+HxxCaQLF/fehUtUqL+Dq9mLOvOwE=",
    "keyPurpose": "ENC",
    "error": null
  },
  {
    "privateKey": {
      "alias": "332243-202309011704-SIGN",
      "clientName": "testClient",
      "algorithm": "ECDSA"
    },
    "publicKey": "MFowFAYHKoZIzj0CAQYJKyQDAwIIAQEHA0IABGbSsNQvH8rD9SbnOj+FKuLbCQ76hHnvvmP7KUAO5chfe9QgSV+2GvjULmZstmSzsBTlz/uwsWS/gFOa3st2vkQ=",
    "keyPurpose": "SIGN",
    "error": null
  },
  {
    "privateKey": {
      "alias": "332243-202309011704-TLS",
      "clientName": "testClient",
      "algorithm": "ECDSA"
    },
    "publicKey": "MFowFAYHKoZIzj0CAQYJKyQDAwIIAQEHA0IABIDLv26gkwa6T1nBGaa+aa43IXVHb1XtxNGjoDEwlpEFTMfNtaNyWdoYKhLwxL9WHdH7/QbWulpah4Nh4jBoU7E=",
    "keyPurpose": "TLS",
    "error": null
  }
]

Zertifikate erstellen

Mit diesem Request wird ein Zertifikat erstellt, welches dazu den jeweiligen privaten Schlüssel aus dem HSM verwendet, welcher bereits zuvor erstellt worden ist. Allerdings dient dieser Aufruf nur für die Erstellung für Testzertifikate, die nicht durch eine Sub-CA bestätigt sind.

Request /as4-crypto-csr/api/v1/generate/certificates:

{
  "iln": "332243",
  "client": "testClient",
  "purpose": "TLS",
  "email": "info@test.de",
  "as4Address": "http://test.de/as4-inbound-endpoint/as4",
  "dns": "http://test.de",
  "x500SubjectName": {
    "commonName": "AS4-PILOT.EMT.MAK",
    "country": "DE",
    "serialNumber": "1",
    "street": "Joachim-Jungius-Straße 9",
    "postalCode": "18059",
    "locality": "Rostock",
    "state": "Mecklenburg-Vorpommern"
  }
}

Die wichtigsten Parameter sind:

  • client : HSM Client, Speicherort der Zertifikate
  • iln : ILN des Zertifikatsinhaber
  • purpose : Angabe des Verwendungszwecks TLS, ENC, SIGN
  • as4Address: Adresse des AS4 Services
  • dns : Domain des AS4 Services
  • commonName: Namensschema nach BSI

Response:

[
  {
    "cert": "MIICsDCCAlegAwIBAgIGAYpRM5rSMAoGCCqGSM49BAMCME4xFjAUBgNVBAMMDVNNLU5MSS1TdWIuQ0ExCjAIBgNVBAUTATAxCzAJBgNVBAYTAkRFMRswGQYDVQQKDBJTTS1OTEktVGVzdC1QS0ktREUwHhcNMjMwODMxMjIwMDAwWhcNMjUwODMxMjIwMDAwWjCB1zEaMBgGA1UEAwwRQVM0LVBJTE9ULkVNVC5NQUsxFzAVBgNVBAoMDlNNLVRlc3QtUEtJLURFMSAwHgYDVQQLDBczMzIyNDMtMjAyMzA5MDExNTEyLUVOQzELMAkGA1UEBhMCREUxCjAIBgNVBAUTATExIjAgBgNVBAkMGUpvYWNoaW0tSnVuZ2l1cy1TdHJhw59lIDkxDjAMBgNVBBEMBTE4MDU5MRAwDgYDVQQHDAdSb3N0b2NrMR8wHQYDVQQIDBZNZWNrbGVuYnVyZy1Wb3Jwb21tZXJuMFowFAYHKoZIzj0CAQYJKyQDAwIIAQEHA0IABD4ZWsU5bIMgslx913kODnJrybsvVF3mzcnN2/8sJ61EA5gIhJfplvhaK5OY8LQQbE5C4pAeAtfgtWfOyo0v75ejgZUwgZIwDgYDVR0PAQH/BAQDAgMoMEAGA1UdEQQ5MDeBDGluZm9AdGVzdC5kZYYnaHR0cDovL3Rlc3QuZGUvYXM0LWluYm91bmQtZW5kcG9pbnQvYXM0MB0GA1UdDgQWBBTGlgbNPe+1x5+FsPIOZbCo145RiDAfBgNVHSMEGDAWgBT/5x9SXTQO7Y82w7kbwMc+7vKDAjAKBggqhkjOPQQDAgNHADBEAiAC6eapORdXpQsWza58GAU67jzqMMhJ2pMjhqUuCKCKtQIgAMhp3pP1bMv00M5VujWqJONuTOQzke0dG0+wTq4B6HA=",
    "message": "Certificate of name: 332243-202309011512-ENC-Cert.der has been successfully created"
  },
  {
    "cert": "MIICsjCCAligAwIBAgIGAYpRM6/eMAoGCCqGSM49BAMCME4xFjAUBgNVBAMMDVNNLU5MSS1TdWIuQ0ExCjAIBgNVBAUTATAxCzAJBgNVBAYTAkRFMRswGQYDVQQKDBJTTS1OTEktVGVzdC1QS0ktREUwHhcNMjMwODMxMjIwMDAwWhcNMjUwODMxMjIwMDAwWjCB2DEaMBgGA1UEAwwRQVM0LVBJTE9ULkVNVC5NQUsxFzAVBgNVBAoMDlNNLVRlc3QtUEtJLURFMSEwHwYDVQQLDBgzMzIyNDMtMjAyMzA5MDExNTEyLVNJR04xCzAJBgNVBAYTAkRFMQowCAYDVQQFEwExMSIwIAYDVQQJDBlKb2FjaGltLUp1bmdpdXMtU3RyYcOfZSA5MQ4wDAYDVQQRDAUxODA1OTEQMA4GA1UEBwwHUm9zdG9jazEfMB0GA1UECAwWTWVja2xlbmJ1cmctVm9ycG9tbWVybjBaMBQGByqGSM49AgEGCSskAwMCCAEBBwNCAASjbLaS0xFPgPQgWWFxLFJz4gPWHVw1mSf2xh4j1aBvrXKTqeAXh2h9NG1biX1ZhpysKwCTkL/eOh1joGUfYo/oo4GVMIGSMA4GA1UdDwEB/wQEAwIHgDBABgNVHREEOTA3gQxpbmZvQHRlc3QuZGWGJ2h0dHA6Ly90ZXN0LmRlL2FzNC1pbmJvdW5kLWVuZHBvaW50L2FzNDAdBgNVHQ4EFgQU/rln9Dsam70+DD22/ROvKy0RqMUwHwYDVR0jBBgwFoAU/+cfUl00Du2PNsO5G8DHPu7ygwIwCgYIKoZIzj0EAwIDSAAwRQIgVj3OLWP2GZAd5o808A8X3pysSulDYSNUavnGHsL1N2gCIQCK2t+2+a6rLzegNiOXROfgSKHTFoPYpc+6fBEGr8XDCQ==",
    "message": "Certificate of name: 332243-202309011512-SIGN-Cert.der has been successfully created"
  },
  {
    "cert": "MIIC4zCCAomgAwIBAgIGAYpRM7AYMAoGCCqGSM49BAMCME4xFjAUBgNVBAMMDVNNLU5MSS1TdWIuQ0ExCjAIBgNVBAUTATAxCzAJBgNVBAYTAkRFMRswGQYDVQQKDBJTTS1OTEktVGVzdC1QS0ktREUwHhcNMjMwODMxMjIwMDAwWhcNMjUwODMxMjIwMDAwWjCB1zEaMBgGA1UEAwwRQVM0LVBJTE9ULkVNVC5NQUsxFzAVBgNVBAoMDlNNLVRlc3QtUEtJLURFMSAwHgYDVQQLDBczMzIyNDMtMjAyMzA5MDExNTEyLVRMUzELMAkGA1UEBhMCREUxCjAIBgNVBAUTATExIjAgBgNVBAkMGUpvYWNoaW0tSnVuZ2l1cy1TdHJhw59lIDkxDjAMBgNVBBEMBTE4MDU5MRAwDgYDVQQHDAdSb3N0b2NrMR8wHQYDVQQIDBZNZWNrbGVuYnVyZy1Wb3Jwb21tZXJuMFowFAYHKoZIzj0CAQYJKyQDAwIIAQEHA0IABCwvgMt8i9VH8Kz5M2VXANB7CSQ30lqGVjWsomKJOSuxAyL2tQP60ZOPY17F+eoMQMhC7fAuRsGjTfIdjUZhf3qjgccwgcQwDgYDVR0PAQH/BAQDAgeAMCAGA1UdJQEB/wQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjBQBgNVHREESTBHgQxpbmZvQHRlc3QuZGWGJ2h0dHA6Ly90ZXN0LmRlL2FzNC1pbmJvdW5kLWVuZHBvaW50L2FzNIIOaHR0cDovL3Rlc3QuZGUwHQYDVR0OBBYEFOLFtHUIlzxbib8LSmp5x/FaKdhpMB8GA1UdIwQYMBaAFP/nH1JdNA7tjzbDuRvAxz7u8oMCMAoGCCqGSM49BAMCA0gAMEUCIQCg41xF5twLJUXqTL0XjSU9qyawPjuaNTPSZatL3bL29wIgfpuyYTV9vT2dUhLn+rjBZEpq0sbo/S84xQulhSAmB70=",
    "message": "Certificate of name: 332243-202309011512-TLS-Cert.der has been successfully created"
  }
]

Zertifikate hochladen

Dieser Aufruf dient zum manuellen Hochladen von Fremdzertifikaten, d. h. den Zertifikaten der Marktpartner.

Request /as4-crypto-csr/api/v1/upload/certificate

{
  "alias": "223343",
  "clientName": "testClient",
  "fileName": "332243-202309011512-SIGN-Cert.der",
  "allowDuplication": false,
  "active": true,
  "purposes": "ENC"
}

Die wichtigsten Parameter sind:

  • alias : Der Alias entspricht der ILN
  • clientName: HSM Client, Speicherort der Zertifikate
  • fileName : Name der Zertifikatsinhaber welche hochgeladen werden soll
  • purposes : Verwendungszweck des Zertifikates

Response: Certificate 332243-202309011512-SIGN-Cert.der successfully uploaded

Certificate Signing Request initialisieren

Die Kommunikation zwischen verschiedenen Systemen und Partnern basiert auf der Verwendung von Zertifikaten, die eigene initiale Zertifikatsanfrage beginnt mit diesem Request. Anschließend muss diese Anfrage, auch CSR genannt, als Datei heruntergeladen werden und per verschlüsselter Email verschickt werden. Für den Download dient der nächste vorgestellte Request.

Request /as4-crypto-csr/api/v1/generate/csr:

{
  "iln": "223343",
  "client": "testClient",
  "email": "info@test.de",
  "as4Address": "http://test.de/as4-inbound-endpoint/as4",
  "dns": "http://test.de",
  "x500SubjectName": {
    "commonName": "AS4-PILOT.EMT.MAK",
    "country": "DE",
    "serialNumber": "1",
    "street": "Joachim-Jungius-Straße 9",
    "postalCode": "18059",
    "locality": "Rostock",
    "state": "Mecklenburg-Vorpommern"
  }
}

Die wichtigsten Parameter sind:

  • client : HSM Client, Speicherort der Zertifikate
  • iln : ILN des Zertifikatsinhaber
  • as4Address: Adresse des AS4 Services
  • dns : Domain des AS4 Services
  • commonName: Namensschema nach BSI

Response:

{
    "certSigningRequest": "MIIF9wYJBA...",
    "hashValue": "R6PreCSW+A7k3G0C9APu2w6C72r4Z/BSWSmgHBRKBzI=",
    "hsmAliases": [
        "223343-202309011521-ENC",
        "223343-202309011521-TLS",
        "223343-202309011521-SIGN"
    ],
    "filename": "223343-202309011521-Csr.der"
}

Certificate Signing Request downloaden

Eine erstellte Zertifikatsanfrage lässt sich hiermit auch als Datei erhalten, um diese über eine Email weiter verschicken zu können.

Request /as4-crypto-csr/api/v1/download/csr?filename=223343-202309011521-Csr.der. Response ist eine Datei, gespeichert im aktuellen Arbeitsordner.

Signiertes Certificate Signing Request erstellen

Mit diesem Request lassen sich signierte CSR-Bundles erstellen.

Request /as4-crypto-csr/api/v1/generate/renew/csr:

{
  "iln": "223342",
  "client": "testClient",
  "serialNumber":"1"
}

Die wichtigsten Parameter sind:

  • iln : ILN des Zertifikatsinhaber
  • client : FSS Client, Speicherort der Zertifikate
  • serialNumber: Optional, ansonsten automatischer Inkrement

Wird der Endpunkt aufgerufen, geschickt folgendes:

  • es wird ein neues CSR-Bundle auf Basis des alten Bundles erstellt
  • das neue Bundle wird durch das alte Zertifikat signiert
  • es wird eine Verbindung zum Sub-CA Webservice zum Ausstellen eines neuen Zertifikats aufgebaut. Die Verbindung wird per mTLS unter Nutzung des alten Zertifikats hergestellt.
  • das neue Zertifikat wird in den FSS geladen

Response:

{
  "certSigningRequest": "MIIItgYJBA...",
  "hashValue": "bRaSEjMdSDpd17gJvBxfEYnYfot6Z+dF5xX950IAFGs=",
  "hsmAliases": [
    "223342-202309011531-ENC",
    "223342-202309011531-TLS",
    "223342-202309011531-SIGN"
  ],
  "filename": "223342-202309011531-Csr.der"
}

Für diesen Endpunkt ist ebenfalls ein Script verfügbar.

Certificate Signing Request erneuern

Der obige Endpunkt /as4-crypto-csr/api/v1/generate/renew/csr kann genutzt werden, um existierende Zertifikate zu erneuern.

Optional können weitere Parameter beim API Aufruf ergänzt werden, um Werte innerhalb des CSRs zu ändern. Hiezu gehören:

  • email
  • as4Address
  • dns
  • x500SubjectName

CSR-Bundle durch anderen Mandanten signieren lassen

Falls für den Mandanten des CSR-Bundles (noch) keine passenden Zertifikate existieren, kann man den aufwendigen initialen Prozess vermeiden, indem man das CSR-Bundle durch einen anderen Mandanten signieren lässt. Dazu wird der Endpunkt /as4-crypto-csr/api/v1/generate/renew/csr genutzt. Der Aufruf erfolgt analog zum obigen Beispiel, jedoch werden weitere Parameter mitgeben.

  • signerIln: Alias des Zertifikats, welches zum Signieren & für TLS genutzt wird
  • signerClient: FSS Client, an dem das Zertifikat gespeichert ist. Kann weggelassen werden, falls der signerClient mit der signerIln identisch ist.

Weiterhin müssen alle Werte zur Konfiguration des Inhalts des CSRs ergänzt werden. Dazu gehören:

  • email
  • as4Address
  • dns
  • x500SubjectName

Verbindung zur Sub-CA skippen

Falls die Verbindung zur Sub-CA nicht hergestellt werden kann, kann die Verbindung zur Sub-CA übersprungen werden. Dazu wird der Endpunkt /as4-crypto-csr/api/v1/generate/renew/csr genutzt. Der Aufruf erfolgt analog zum obigen Beispiel, jedoch wird der Parameter skipSubCa=true mitgegeben. Als Ergebnis wird nun einzig das signierte CSR-Bundle erstellt.

Certificate Revocation Request

Um den Sub-CA-Anforderungen gerecht zu werden, ist es ein Muss, Zertifikate widerrufen/sperren zu können. Zum Beispiel sollen Ersstzertifikate nach der Ausstellung von Folgezertifikaten widerrufen werden können. Diese Funktionalität erstellt eine Sperranforderung, die aus den zu sperrenden Zertifikaten und einem gültigen CRL-Grund besteht. Damit die Methode funktioniert, müssen sowohl neue Zertifikate als auch Erstzertifikate in das FSS hochgeladen werden. Wenn die Sub-CA-Adresse bekannt ist, kann diese angegeben werden zur API-Anfrage, andernfalls wird die Sub-CA-Adresse aus dem Zertifikat extrahiert. Die Anfrage wird über den Sub-CA-Webservice an die Sub-CA gesendet.

Request /as4-crypto-csr/api/v1/revoke/certificates:

{
  "iln": "9901234567999",
  "client": "testClient",
  "ski": "bb58d38bad32b83130c2a7834f64016a432649a4, e38b5e9b811d15c6ce3b1e7e2e0a29e82fb42bb6, 1e641907829b6397da2ad92aad597795349e212d",
  "crlReason": "cessation_of_operation",
  "subCaAddress": "https://localhost:8085/service"
}

Response:

{
  "certRevocationRequest":"MIIFCgYJBAB...",
  "subCaResult": "success_request_accepted"
}

Automatische Zertifikatserneuerung

Über einen Cron Job lässt sich auch eine automatische Zertifikatserneuerung aktivieren:

## Certificate renewal
cert.renewal.enabled=false
## seconds, minutes, hours, day of the month, month, day of week
cert.renewal.cron=0 0 2 * * *

Über eine application.yml kann das Zeitintervall angegeben werden, ab wann ein Zertifikat erneuert werden soll. Das heißt, wie lange es maximal noch gültig ist. Es ist außerdem möglich, Clients anzugeben, für die der Zertifikatserneuerungsprozess nicht gestartet werden soll oder Clients anzugeben, für die dieser gestartet werden soll. Hier ist zu beachten, dass nicht beides gleichzeitig konfiguriert werden kann.

# This configuration is for certificate renewal
# clients and excludedClients are optional but can not be configured at the same time
# If both are configured, the application will not start
# If neither is configured, all clients from fss will be renewed
# https://b2bbp.next-level-help.org/as4_crypto_csr.html#automatische-zertifikatserneuerung
csr:
  #clients: # Clients whose certificates need to be renewed are listed as follows
  #  - testClient
  #  - marketPartner
  excludedClients: # Clients whose certificates do not need to be renewed can be listed as follows
    - sharedClient
    - mailClient
  renewalInterval: 60 # This is in days

Adressen der Webservices der Sub-CAs

Für die Zertifikatserneuerung baut der CSR-Service eine Verbindung mit dem Webservice der jeweiligen Sub-CA auf.

Die Adressen der Webservices der Sub-CAs können über die application.yml Property subcaUrl konfiguriert werden.

TLS Configuration

Um Anfragen wie CSR- und Sperranfragen von Zertifikaten weiterzuleiten, muss die TLS-Kommunikation zum Aufruf der Webdienste der SubCA aktiviert sein. Um TLS zu aktivieren, werden die folgenden Eigenschaften verwendet:

client:
  ssl:
    enabled: true
fss:
  server:
    api:
      url=http://fss:2222/fss/api/v1
ssl:
  trust:
    client: shared-client
  • client.ssl.enabled: true, um TLS zu aktivieren.
  • ssl.trust.client: FSS-Client, der TLS-Zertifikate der SubCAs (inkl. Zertifikatskette) speichert.
  • fss.server.api.url: Falls TLS genutzt werden soll, muss der FSS erreichbar sein, vergleichen Sie hierzu die Doku zur Anbindung des FSS. Bereits zur Bootzeit des Service muss der FSS sowie das HSM vollständig erreichbar sein. Weiterhin müssen zur Bootzeit bereits alle benötigten Zertifikate verfügbar sein.

Darüber hinaus wird eine Mandantenbezogene Konfiguration für mTLS benötigt:

mTLS Mandantenkonfiguration

Der CSR-Service unterstützt mTLS als Client. Beim Aufruf an einen Server ist er in der Lage ein Zertifikat des eigenen Mandanten mitzuschicken. Der Service unterstützt parallel mehrere Mandanten.

Es gibt zwei Wege, über die die Mandanten konfiguriert weren können. Automatisch über die FSS-Clients oder manuell per Konfiguration. Es kann immer nur eine der beiden Konfigurationsmöglichkeiten genutzt werden. Der parallele Einsatz beider Konfigurationen ist nicht möglich.

automatische Mandantenkonfiguration

Folgende Konvention wird vorausgesetzt: zu jedem Mandanten existiert ein FSS-Client = Mandant-Id. Auf dieser Basis kann der CSR-Service die Mandanten ermitteln.

Üblicherweise verfügt der FSS darüber hinaus über weitere Clients, z.B. den shared-client. Diese können wie folgt per application.yml ignoriert werden:

clients:
    excluded-from-tenants:
    - shared-client
    - undefined

manuelle Mandantenkonfiguration

Die Mandanten können manuell über die application.yml konfiguriert werden. Da dies redundant ist, empfehlen wir stattdessen jedoch die automatische Mandantenkonfiguration. Die manuelle Konfiguration wird wie folgt durchgeführt:

tenants:
- id: 9903111000003
  client: 9903111000003-deprecated
- id: 9907647000008
  • tenants[i].id: Mandanten-ID.
  • tenants[i].client: Der FSS-Client, unter dem der private Schlüssel des Mandanten gepflegt wird. Falls nicht angegeben, wird angenommen dass der Client gleich der Mandanten-ID ist.

Hardware Anforderungen

Eine Service-Instanz erfordert mindestens 512 MB RAM.

Wir empfehlen 0,2 CPU-Kerne je Instanz.

Logs werden auf die Festplatte geschrieben, entsprechend muss genügend Speicherplatz vorhanden sein.

Abhängigkeiten

Der Service greift auf eine SQL Datenbank zu, um Seriennummern der Zertifikate zu speichern. Der Speicherverbrauch ist sehr gering.

Der Service nutzt die REST API des Security Server FSS. Der FSS muss im Hintergrund auf ein HSM zugreifen können.

Datenbank

Der CSR-Service benötigt eine SQL Datenbank (z.B. Postgres). Im Vorfeld muss ein Schema angelegt worden sein. Die Tabellen werden automatisch vom Microservice angelegt (via flyway).

Die Datenbank-Anbindung kann über die application.properties Datei wie folgt konfiguriert werden:

# Postgres
datasource.url=jdbc:postgresql://as4-crypto-csr-database/csr?currentSchema=csr
datasource.username=postgres
datasource.password=change_me
datasource.type=postgres
datasource.schema=csr

spring.jpa.show-sql=false
spring.jpa.properties.hibernate.format_sql=true

Datenbank und Schema müssen vorher bereits angelegt worden sein, z.B. mit folgendem Script für Postgres:

#!/bin/bash

set -e

psql -v ON_ERROR_STOP=1 <<-EOSQL
    -- create database
    CREATE database csr;
EOSQL

psql -v ON_ERROR_STOP=1 --dbname csr <<-EOSQL
    -- create schema
    CREATE SCHEMA csr;
    SET search_path TO csr;
EOSQL

Zugriff zur FSS REST API

Der CSR-Service muss auf den FSS zugreifen können. Dies kann wie folgt in den application.properties konfiguriert werden:

## FSS
fss.server.api.url=http://fss:2222/fss/api/v1
fss.page.size.value=100

Keycloak

Falls der FSS per Keycloak abgesichert ist, muss entsprechend auch am CSR-Service Keycloak konfiguriert werden.

Durch die Konfiguration von Keycloak werden außerdem die REST-Endpunkte des CSR-Service abgesichert.

Weitere Details zur Konfiguration der Keycloak Anbindung finden Sie hier.

In Keycloak können die Mandanten, auf die der User Zugriff hat, eingeschränkt werden. Weitere Details entnehmen Sie der Doku.

AEP AS4 - Environment Setup

Environment Variablen

Um die Zertifikatserneuerung des CSR-Service zu nutzen, müssen folgende JDK Java Options gesetzt werden:

-Djdk.tls.namedGroups=brainpoolP384r1,brainpoolP256r1,secp384r1,secp256r1

Komponenten und Installation:

Die für den CSR-Service benötigten Komponenten sind wie folgt:

  • HSM
  • FSS:
    1. Benutzeroberfläche (UI)
    2. Back-End-API
    3. SQL-Datenbank
    4. Keycloak

Um AS4 Cryptography CSR optimal zu nutzen, stellen Sie bitte sicher, dass alle folgenden Voraussetzungen erfüllt sind:

  1. Laufende HSM-Instanz
  2. HSM Slot konfiguriert
  3. Laufende FSS-Anwendung

HSM Slot Setup

Details hierzu finden Sie in der HSM Dokumentation.

Optionale Proxy-Konfiguration

Dieses Feature befindet sich noch in Entwicklung.

Es ist möglich, die Anwendung mit einem Proxy zu verbinden und Anfragen an die SubCa über einen Proxy zu routen. Wenn eine grundlegende Benutzer- und Passwortauthentifizierung erforderlich ist, kann diese ebenfalls konfiguriert werden.

#=== Proxy Properties ===#
proxyEnable=false
proxyAddress=
proxyPort=
proxyUser=
proxyPassword=

Falls der Proxy benötigt wird, muss die Eigenschaft proxyEnable auf true gesetzt werden. Die proxyAddress gibt die Addresse (Host) an, unter welcher der Proxy verfügbar ist. Wenn der Proxy beispielsweise unter localhost läuft, wird 127.0.0.1 eingetragen. Sollte keine Authentifizierung mit User und Passwort erforderlich sein, können diese Eigenschaften leer bleiben.

Optionale URL für die Zertifikatsverlängerung

Es ist möglich, die SubCa-URL zu definieren, die für den automatischen Zertifikatserneuerungsprozess verwendet wird.

Der Aufbau der Konfiguration ist wie folgt:

  1. Der allgemeineName stellt den gemeinsamen Namen des Ausstellers des Partnerzertifikats oder den allgemeinen Namen des Sub-CA-Subjekts des Ausstellerzertifikats dar
  2. web service-url stellt die URL des SubCa-Dienstes dar

application.yml:

csr:
  certificateAuthorities:
    -
      commonName: TestCommonName
      webServiceUrl: https://localhost:8085/service
    -
       commonName: TestCommonName_2
       webServiceUrl: https://localhost:8085/service_2

Logging

Falls Sie die Soap-Requests im Log ausgeben möchten, konfigurieren Sie folgende Property:

logging.level.org.apache.cxf=DEBUG

AMQP

Prüfereignisse wie Schlüsselerstellung und Erst- und Erneuerungserstellung (CSR) können generiert und über ein Message-Broker-System an den REVISION MANAGER service weitergeleitet werden. Um AMQP zu aktivieren, sind die folgenden Eigenschaften erforderlich

#=== AMQP ===#
spring.autoconfigure.exclude=
spring.cloud.stream.binders.rabbit.defaultCandidate=true

# Disable serviceBus
spring.cloud.azure.servicebus.enabled=false
spring.cloud.stream.default-binder=rabbit

## RabbitMQ
spring.main.allow-bean-definition-overriding=true
spring.rabbitmq.host=rabbitmq3
spring.rabbitmq.port=5672
spring.rabbitmq.username=guest
spring.rabbitmq.password=${RABBITMQ_PASSWORD}

## Producer Properties
spring.cloud.stream.bindings.csrEventProducer-out-0.destination=${csrEventExchangeName}
spring.cloud.stream.rabbit.bindings.csrEventProducer-out-0.producer.routing-key-expression=${csrEventRoutingkeyExpression}
spring.cloud.stream.rabbit.bindings.csrEventProducer-out-0.producer.exchange-type=${csrEventProducerExchangeType}

csrEventExchangeName=csr.event
csrEventRoutingkeyExpression='default'
csrEventHeaderName=tenant
csrEventProducerExchangeType=topic

So aktivieren Sie AMQP für die Überwachung von Ereignissen über den Revision Manager-Dienst:

spring.autoconfigure.exclude - muss auf einen leeren Wert gesetzt werden

spring.cloud.stream.binders.rabbit.defaultCandidate - wahr oder falsch, je nachdem, ob Rabbitmq verwendet wird oder nicht

spring.cloud.azure.servicebus.enabled - true oder false, wenn Azure Service Bus verwendet wird

spring.cloud.stream.default-binder - rabbit or servicebus

CSR Audit Event

Dazu gehören die Schlüsselerstellung und die CSR-Erstellung. Daten zu diesen Ereignissen werden nun aufgezeichnet

Um die Audit-Ereignisse zu konsumieren: queues, exchanges, bindings müssen erstellt werden. Dies kann beispielsweise durch manuelle Konfiguration in der definition.json von Rabbitmq erfolgen.

Exchange Name sollte sein: csr.event

Default routing:

für default routing, Die folgende Eigenschaft wird auf festgelegt:

csrEventRoutingkeyExpression=’default’

Tenant-based routing:

csrEventRoutingkeyExpression=headers.tenant

Anhang: Gesamtkonfiguration

Im Standard verteilt sich die Konfiguration auf zwei Konfigurationsdateien application.properties sowie application.yml. Diese enthält vordefinierte Default Werte und wird durch die Docker Umgebung bereitgestellt.

application.properties:


## FSS
fss.server.api.url=http://fss:2222/fss/api/v1
## Page size for fss requests
fss.page.size.value=100

# Postgres
datasource.url=jdbc:postgresql://as4-crypto-csr-database/csr?currentSchema=csr
datasource.username=postgres
datasource.password=${CSR_DATABASE_PASSWORD}
datasource.type=postgres
datasource.schema=csr

application.yml:

# This configuration is for certificate renewal
# clients and excludedClients are optional but can not be configured at the same time
# If both are configured, the application will not start
# If neither is configured, all clients from fss will be renewed
# https://b2bbp.next-level-help.org/as4_crypto_csr.html#automatische-zertifikatserneuerung
csr:
  #clients: # Clients whose certificates need to be renewed are listed as follows
  #  - testClient
  #  - marketPartner
  excludedClients: # Clients whose certificates do not need to be renewed can be listed as follows
    - sharedClient
    - mailClient
  renewalInterval: 60 # This is in days

#=== AMQP ===#
spring.autoconfigure.exclude=
spring.cloud.stream.binders.rabbit.defaultCandidate=true

# Disable serviceBus
spring.cloud.azure.servicebus.enabled=false
spring.cloud.stream.default-binder=rabbit

## RabbitMQ
spring.main.allow-bean-definition-overriding=true
spring.rabbitmq.host=rabbitmq3
spring.rabbitmq.port=5672
spring.rabbitmq.username=guest
spring.rabbitmq.password=${RABBITMQ_PASSWORD}

## Producer Properties
spring.cloud.stream.bindings.csrEventProducer-out-0.destination=${csrEventExchangeName}
spring.cloud.stream.rabbit.bindings.csrEventProducer-out-0.producer.routing-key-expression=${csrEventRoutingkeyExpression}
spring.cloud.stream.rabbit.bindings.csrEventProducer-out-0.producer.exchange-type=${csrEventProducerExchangeType}

csrEventExchangeName=csr.event
csrEventRoutingkeyExpression='default'
csrEventHeaderName=tenant
csrEventProducerExchangeType=topic

Die wichtigen zusätzlich vorzunehmende Einstellungen, wenn der Scheduler zur Zertifikatserneuerung verwendet werden soll:

  • cert.renewal.enabled aktiviert die automatische Zertifikatserneuerung.
  • cert.renewal.cron gibt das Interval an für die automatische Zertifikatserneuerung.

Allgemeine Hinweise zur Konfiguration finden Sie hier.

View Me   Edit Me