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.

Certificate Signing Request erneuern

Mit diesem Request lassen sich manuell Zertifikatserneuerung anstossen. The serial number is an optional input.

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

{
  "iln": "223342",
  "client": "testClient",
  "serialNumber":"1",
  "subCaAddress": "https://localhost:8085/service"
}

Die wichtigsten Parameter sind:

  • iln : ILN des Zertifikatsinhaber
  • client : HSM Client, Speicherort der Zertifikate
  • serialNumber: Optional, ansonsten automatischer Inkrement
  • subCaAddress: Optional, manueller Eintrag für die SubCA Adresse

Response:

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

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 gestartet werden soll.

# This configuration is for certificate renewal
csr:
  clients: # Clients whose certificates need to be renewed are listed as follows
    - testClient 
    - marketPartner
  renewalInterval: 60 # This is in days

Statt die Clients anzugeben, für die der Prozess ausgeführt werden soll, ist es auch möglich, Clients anzugeben, für die kein Zertifikatserneuerungsprozess durchgeführt werden soll. In diesem Fall werden alle Clients beim FSS abgefragt und die ausgeschlossenen entfernt. Sind weder die Mandanten noch die excludedClients konfiguriert, werden alle im FSS angelegten Clients berücksichtigt. Es ist nicht möglich Clients und ExcludedClients gleichzeitig zu setzen. Sind beide gesetzt, so startet die Applikation nicht.

# This configuration is for certificate renewal
csr:
  excludedClients: # Clients whose certificates do not need to be renewed can be listed if clients above not set
    - sharedClient
    - mailClient
    - undefined
  renewalInterval: 60 # This is in days

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:

#=== SSL Properties ===#
client.ssl.enabled=true
ssl.tenant.id=9901234567999
ssl.client=9901234567999
ssl.trust.client=tlsIssuerClient
  • client.ssl.enabled: true oder false, um TLS zu deaktivieren.
  • ssl.tenant.id: Mandanten-ID (oder normalerweise der Alias, unter dem das TLS-Zertifikat hochgeladen wird).
  • ssl.client: Der Client, unter dem das TLS-Zertifikat hochgeladen wird.
  • ssl.trust.client: Neuer eindeutiger Client, der nur das TLS-Zertifikat (SubCA) der SubCA speichert – um zwischen Mandanten- und Partner-SubCA-Zertifikaten zu unterscheiden.

Falls TLS genutzt werden soll, muss der FSS erreichbar sein. 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 & Schlüssel verfügbar sein.

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

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.

AEP AS4 - Environment Setup

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.

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

Die wichtigen vorzunehmende Einstellungen sind:

  • fss.server.api.url ist die URL zum FSS Dienst
  • cert.renewal.enabled aktiviert die automatische Zertifikatserneuerung.
  • cert.renewal.cron gibt das Interval an für die automatische Zertifikatserneuerung.
  • csr.clients listet die clients für die eigenen Zertifikate zu finden sind.

Allgemeine Hinweise zur Konfiguration finden Sie hier.

View Me   Edit Me