AS4 Crypto Operations Dokumentation

Dieser Service ist eine Spring Boot-Anwendung, die AS4-Nachrichten aus RabbitMQ empfängt und verarbeitet, führt kryptografische Operationen wie Signieren, Verschlüsseln, Verifizieren und Entschlüsseln durch. Anschließend werden die verarbeiteten Nachrichten an die Ausgabe-Warteschlange weitergeleitet.

Zertifikate werden aus dem FSS geladen. Schlüsselbezogene Operationen werden über den FSS an das HSM delegiert.

Hardware Anforderungen

Eine Service-Instanz erfordert mindestens 1024 MB RAM.

Wir empfehlen 0,6 CPU-Kerne je Instanz.

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

Abhängigkeiten

Der Service greift auf einen Message-Broker zu, um Nachrichten zu empfangen und zu versenden.

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

REST API

Die API bietet Server-Health Informationen an. Hierfür wird Actuator verwendet.

Der Port lässt sich über folgende Property konfigurieren: server.port=8080

Actuator

Dies ist der Haupt-API-Link für Actuator: http://localhost:8096/actuator/health

DockerEnvironmentDetails

Docker und seine zugehörigen Dateien sind im Modul as4-cryptography-environment von as4-microservices-bundle/docker-compose verfügbar.

AMQP Routing Konfiguration

Falls Sie das Standard Routing nutzen, muss das Routing nicht weiter konfiguriert werden. Wenn Sie Ihr Routing anpassen möchten, lesen Sie die folgende Dokumentation.

Funktionsbeschreibung der kryptografischen Vorgänge

  • Folgende APIs sind verfügbar:

  1. Sign/Encrypt AS4 Workflow

    Queue-Name:

    input: as4.encrypt.sign.default

output: as4.outbound.default

dlq: as4.encrypt.sign.default.dlq

  2. Verify/Decrypt AS4 Workflow

    Queue-Name:

    input: as4.verify.decrypt.default

output: as4.receipt.create.default

dlq: as4.verify.decrypt.default.dlq

  3. Sign AS4 Receipt Workflow

    Queue-Name:

    input: as4.sign.default

output: as4.send.receipt.<dynamic-queue-address>

   - Wichtig ist, dass der Exchange, die Queues und die entsprechenden Bindings für as4.send.receipt vor dem Start der AS4 Crypto Operations erstellt werden müssen, da es sonst sein kann, dass Nachrichten verloren gehen. Eine entsprechende Dokumentation zum Anlegen der Queues ist [hier](https://b2bbp.next-level-help.org/as4_ms_rabbitmq.html) dokumentiert

dlq: as4.sign.default.dlq

  4. Verify AS4 Receipt Workflow

    Queue-Name::

    input: as4.verify.default
   	
output: as4.receipt.parse.default
   	
dlq: as4.verify.default.dlq

Sign/Encrypt AS4 Workflow

  • Consumer Queue: as4.encrypt.sign
  • Input consumed by Crypto-Operations

  • Request payload example:

     {
    "as4Id": "1000",
    "fromPartyId": "9907647000008",
    "toPartyId": "9903111000003",
    "tenant": "9907647000008",
    "partner": "9903111000003",
    "direction": "OUTBOUND",
    "sector": "ELECTRICTY",
    "as4Profile": "CEF",
    "serviceId": "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service",
    "actionId": "http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
    "address": "b2b@b2b",
    "as4MessageData": "LS0tLS0tPV9QYXJ0XzFfMTgkFnRSD5JICAAANCi0tLS0tLT1fUGFydF8xXzE4OTI5ODgyOTkuMTY3NDAxNjAwNDkxNy0t"
 }
  • Producer Queue: as4.outbound.default
  • Output produced by Crypto-Operations

  • Response payload example:

     {
   "as4Id":"1000",
   "fromPartyId":"9907647000008",
   "toPartyId":"9903111000003",
   "as4MessageData":"LS0tLS0tPV9QYXJ0XzBfNjgn0NCi0tLS0tLT1fUGFydF8wXzYwNDQyMTE3OC4xNjgwMDc5OTczMzcxLS0=",
   "tenant":"9907647000008",
   "partner":"9903111000003",
   "sector":"ELECTRICTY",
   "as4Profile":"CEF",
   "serviceId":"http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service","actionId":"http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
   "signatureStatusCodes":[200],
   "signatureReport":{
         "certificateSki":["8e98ac4ea4ad199799dfbc576754d203288663dc"],
         "algorithms":["http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256","http://www.w3.org/2001/10/xml-exc-c14n#","http://www.w3.org/2001/10/xml-exc-c14n#"],
         "verifications":null
         },
   "cryptStatusCodes":[200],
   "cryptReport":{
             "certificateSki":["795551e3c525d6d54abe1b46662885385e1ddcf3","c9374ce5bd73c56a92f6657dc04b3be475cdf860"],
             "algorithms":["http://www.w3.org/2009/xmlenc11#aes128-gcm","http://www.w3.org/2001/04/xmlenc#kw-aes128","http://www.w3.org/2009/xmlenc11#ECDH-ES","http://www.w3.org/2009/xmlenc11#ConcatKDF","http://www.w3.org/2001/04/xmlenc#sha256"],
             "verifications":null
            },
   "address":"b2b@b2b",
   "direction":"OUTBOUND"

}

Konfiguration des Routings auf Basis des bdewDocumentType

Um Nachrichten gezielt zu routen, kann das Routing auf Basis des bdewDocumentType konfiguriert werden. Dies ermöglicht eine flexible Steuerung, über verschiedene Exchanges in Abhängigkeit vom Dokumenttyp.

Der Routing-Mechanismus muss explizit über die folgenden Eigenschaften in der application.properties konfiguriert werden:

sign.and.encrypt.as4.message.producer.exchange=as4.outbound
sign.and.encrypt.as4.message.producer.headerName=bdewDocumentType
sign.and.encrypt.as4.message.producer.headerValues=exampledocumenttype

Nachrichten, die mit einem der in headerValues definierten bdewDocumentType-Werte gesendet werden, laufen nicht mehr über das Standardrouting, sondern werden über den entsprechend konfigurierten Exchange weitergeleitet.

Verify/Decrypt AS4 Workflow

  • Consumer Queue: as4.verify.decrypt.default
  • Input consumed by Crypto-Operations

  • Request payload example:

     {
 "as4Id": "1000",
 "delivered": "2023-03-27T09:38:53.331+00:00",
 "deliveredReport": "delivered",
 "fromPartyId": "9907647000008",
 "toPartyId": "9903111000003",
 "tenant": "9903111000003",
 "partner": "9907647000008",
 "direction": "INBOUND",
 "sector": "ELECTRICTY",
 "as4Profile": "CEF",
 "serviceId": "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service",
 "actionId": "http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
 "as4MessageData": "LS0tLS0tPV9QYXJ0XzBgn0NCi0tLS0tLT1fUGFydF8wXzYwNDQyMTE3OC4xNjgwMDc5OTczMzcxLS0="
}
  • Producer Queue: as4.receipt.create.default
  • Output produced by Crypto-Operations

  • Response payload example:

     {
   "as4Id":"1000",
   "fromPartyId":"9907647000008",
   "toPartyId":"9903111000003",
   "as4MessageData":"LS0tLS0tgn0NCi0tLS0tLT1fUGFydF8wXzYwNDQyMTE3OC4xNjgwMDc5OTczMzcxLS0=",
   "tenant":"9903111000003",
   "partner":"9907647000008",
   "sector":"ELECTRICTY",
   "as4Profile":"CEF",
   "serviceId":"http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service",
   "actionId":"http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
   "signatureStatusCodes":[200],
   "signatureReport":{
   "certificateSki":["8e98ac4ea4ad199799dfbc576754d203288663dc"],
   "algorithms":["http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256","http://www.w3.org/2001/10/xml-exc-c14n#","http://www.w3.org/2001/10/xml-exc-c14n#"],
   "verifications":null
   },
   "cryptStatusCodes":[200],
   "cryptReport":{
   "certificateSki":["c9374ce5bd73c56a92f6657dc04b3be475cdf860"],
   "algorithms":["http://www.w3.org/2009/xmlenc11#aes128-gcm","http://www.w3.org/2001/04/xmlenc#kw-aes128","http://www.w3.org/2009/xmlenc11#ConcatKDF","http://www.w3.org/2001/04/xmlenc#sha256"],
   "verifications":null
   },
   "delivered":"2023-03-27T09:38:53.331+00:00",
   "deliveredReport":"delivered",
   "direction":"INBOUND",60J3ZUH8NJAwOUxdrl7xA66yItOgnZHpENDqr7rl+1VDRzNPrWyLdD89/kFnRSD5JICAAA="
 }

Sign AS4 Receipt Workflow

  • Consumer Queue: as4.sign.default
  • Input consumed by Crypto-Operations

  • Request payload example:

     {
   "as4Id":"12325",
   "businessId":"123",
   "delivered":"2023-03-27T09:38:53.331+00:00",
   "deliveredReport":"delivered",
   "fromPartyId":"9907647000008",
   "toPartyId":"9903111000003",
   "tenant":"9907647000008",
   "partner":"9903111000003",
   "sector":"ELECTRICTY",
   "as4Profile":"CEF",
   "serviceId":"http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service",
   "actionId":"http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
   "statusCode":"200",
   "as4MessageData":"LS0tLS0tPkFnRSD5JICAAANCi0tLS0tLT1fUGFydF8xXzE4OTI5ODgyOTkuMTY3NDAxNjAwNDkxNy0t"
 }
  • Producer Exchange: as4.send.receipt
  • Producer Queue: as4.send.receipt.
    • Wichtig ist, dass der Exchange, die Queues und die entsprechenden Bindings für den Producer vor dem Start der AS4 Crypto Operations erstellt werden müssen, da es sonst sein kann, dass Nachrichten verloren gehen. Eine entsprechende Dokumentation zum Anlegen der Queues ist hier dokumentiert
  • Output produced by Crypto-Operations

  • Response payload example:

     {
   "as4Id":"12325",
   "fromPartyId":"9907647000008",
   "toPartyId":"9903111000003","
   as4MessageData":"LS0tLS0tPV9QWdFIPkkgIAAA0KLS0tLS0tPV9QYXJ0XzFfNDIzMDQ0ODc3LjE2ODAwODE1NDYyOTUtLQ==",
   "tenant":"9907647000008",
   "partner":"9903111000003",
   "sector":"ELECTRICTY",
   "as4Profile":"CEF","serviceId":"http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service","actionId":"http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
   "signatureStatusCodes":[200],
   "signatureReport":{
   "certificateSki":["8e98ac4ea4ad199799dfbc576754d203288663dc"],
   "algorithms":["http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256","http://www.w3.org/2001/10/xml-exc-c14n#","http://www.w3.org/2001/10/xml-exc-c14n#"],
   "verifications":null
   },
   "businessId":"123",
   "statusCode":"200",
   "delivered":"2023-03-27T09:38:53.331+00:00",
   "deliveredReport":"delivered"
 }

    Das Überspringen des receipt-Signierungsprozesses in den As4-Crypto-Operations kann nun durch die Property skip-receipt-signing=true eingeschaltet, bzw. durch skip-receipt-signing=false ausgeschaltet werden. Der default ist false!

    skip-receipt-signing=false

Verify AS4 Receipt Workflow

  • Consumer Queue: as4.verify.default
  • Input consumed by Crypto-Operations

  • Request payload example:

    {
   "as4Id": "12325",
   "businessId": "123",
   "delivered": "2023-03-27T09:38:53.331+00:00",
   "deliveredReport": "delivered",
   "fromPartyId": "9907647000008",
   "toPartyId": "9903111000003",
   "tenant": "9903111000003",
   "partner": "9907647000008",
   "sector": "ELECTRICTY",
   "as4Profile": "CEF",
   "serviceId": "http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service",
   "actionId": "http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
   "statusCode": "200",
   "as4MessageData": "LS0tLS0tPV9QYXJ0XzFfNDQWdFIPkkgIAAA0KLS0tLS0tPV9QYXJ0XzFfNDIzMDQ0ODc3LjE2ODAwODE1NDYyOTUtLQ=="
}
  • Producer Queue: as4.receipt.parse.default
  • Output produced by Crypto-Operations

  • Response payload example:

    {
   "as4Id":"12325",
   "fromPartyId":"9907647000008",
   "toPartyId":"9903111000003",
   "as4MessageData":"LS0tLS0QWdFIPkkgIAAA0KLS0tLS0tPV9QYXJ0XzFfNDIzMDQ0ODc3LjE2ODAwODE1NDYyOTUtLQ==",
   "tenant":"9903111000003",
   "partner":"9907647000008",
   "sector":"ELECTRICTY",
   "as4Profile":"CEF",
   "serviceId":"http://docs.oasis-open.org/ebxml-msg/ebms/v3.0/ns/core/200704/service",
   "actionId":"http://docs.oasis-open.org/ebxml-msg/as4/200902/action",
   "signatureStatusCodes":[200],
   "signatureReport":{
   "certificateSki":["8e98ac4ea4ad199799dfbc576754d203288663dc"],
   "algorithms":["http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256","http://www.w3.org/2001/10/xml-exc-c14n#","http://www.w3.org/2001/10/xml-exc-c14n#"],
   "verifications":null
   },
   "businessId":"123",
   "statusCode":"200",
   "delivered":"2023-03-27T09:38:53.331+00:00",
   "deliveredReport":"delivered"
}

Max Concurrency - Parallelität

Für jeden Consumer ist es möglich die Eigenschaft max-concurrency zu setzen. Diese definiert die maximale Anzahl von gleichzeitigen Verarbeitungsthreads, die für einen Consumer gestartet werden können. Der Default steht für jeden Consumer auf 50.

spring.cloud.stream.rabbit.bindings.signAndEncrypt-in-0.consumer.max-concurrency=50
spring.cloud.stream.rabbit.bindings.sign-in-0.consumer.max-concurrency=50
spring.cloud.stream.rabbit.bindings.verify-in-0.consumer.max-concurrency=50
spring.cloud.stream.rabbit.bindings.decryptAndVerify-in-0.consumer.max-concurrency=50

Auto-Scaling des AS4 Inbound Endpoints

Ist das Spring Profil scaling im AS4 Inbound Endpoint aktiv, so ist es zwingend erforderlich, dass dieses auch in den AS4 Crypto Operations aktiviert wird.

spring.profiles.active=scaling

Mehr dazu in der Dokumentation des AS4 Inbound Endpoints. Zudem ist zu beachten, dass die Eigenschaft spring.cloud.stream.rabbit.bindings.signProducer-out-0.producer.routing-key-expression NICHT in der application.properties gesetzt sein darf.

Multi-Tenant-Unterstützung

Die AS4 Crypto Operations wurden verbessert, um Multi-Tenant-Umgebungen zu unterstützen. Sie ermöglicht jetzt das Signieren, Überprüfen, Verschlüsseln und Entschlüsseln von AS4-Nachrichten für mehrere Mandanten.

Funktionen:

  1. Signieren: Der Dienst kann eine AS4-Nachricht für einen bestimmten Mandanten mit seinem zugehörigen Signatur-Zertifikat signieren.
  2. Überprüfung: Der Dienst kann eine AS4-Nachrichtensignatur für jeden Mandanten mit einem gemeinsamen Überprüfungszertifikat überprüfen.
  3. Verschlüsselung: Der Dienst kann eine AS4-Nachricht für einen bestimmten Mandanten mit einem gemeinsamen Verschlüsselungszertifikat verschlüsseln.
  4. Entschlüsselung: Der Dienst kann eine AS4-Nachricht für einen bestimmten Mandanten mit seinem zugehörigen Entschlüsselungszertifikat entschlüsseln.

Der Kunde kann die Multi-Tenant-Konfiguration wie folgt (in einer YML-Datei) durchführen:

  • Beispiel:

            fssTenantClients:
         - client: client1
           tenants:
            - 9900000000011
            - 9900000000012
         - client: client2
           tenants:
            - 9900000000021
        fssSharedClient: shared-client

Die Konfiguration der einzelnen Tenant-Clients ist optional! Falls eine manuelle Konfiguration nicht gewünscht ist, müssen die verschiedenen fssTenantClients nicht konfiguriert werden.Es wird dann davon ausgegangen, dass der FSS-Client der Tenant-ILN entspricht. Wenn der fssSharedClient nicht konfiguriert ist, werden die Zertifikate ebenfalls von den jeweiligen Tenant-ILN´s geladen. Die Konfiguration kann wie folgt (in einer YML-Datei) durchgeführt werden:

  • Beispiel:

               fssSharedClient: shared-client

Für die Multi-Mandantenfähigkeit ist es notwendig, für den sign-and-encrypt Producer des Outbound Workflows und den sign-Producer des Inbound Workflows die Nachrichten anhand der Mandanten zu routen. Dafür muss jeweils der Headername auf tenant gesetzt werden. Für die Headervalues ist eine Liste aller Mandanten anzugeben.

Somit kann für den Outbound Workflow die Nachricht anhand des Mandanten an den richtigen AS4 Outbound Sender geroutet werden. Für den Inbound Workflow wird das erstellte Receipt anhand des Mandanten an die richtigen AS4 Inbound Endpoints geroutet.

Dies kann wie im folgenden Beispiel erfolgen. .

  • Beispiel:

    sign.and.encrypt.as4.message.producer.headerName=tenant
sign.and.encrypt.as4.message.producer.headerValues=9903111000003,9900794000004

sign.as4.message.producer.headerName=tenant
sign.as4.message.producer.headerValues=9903111000003,9900794000004

Überspringen der Signaturverifizierung eines Receipts

Mit der Eigenschaft skip-receipt-verification ist es möglich die Verifizierung der Signatur von Receipts zu überspringen. Der Default ist ‘false’. Um die Verifizierung zu überspringen, muss die Property auf ‘true’ gesetzt werden.

skip-receipt-verification=true

Anhang: Gesamtkonfiguration

Im Standard verteilt sich die Konfiguration auf zwei Konfigurationsdateien application.properties sowie application.yml.

Folgende Konfiguration reicht in einem Standard-System aus:

application.properties:


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

#==== RabbitMQ
spring.rabbitmq.host=rabbitmq3
spring.rabbitmq.port=5672
spring.rabbitmq.username=guest
spring.rabbitmq.password=${RABBITMQ_PASSWORD}

application.yml:

client-tenant:
  fssSharedClient: shared-client

Cache Update

Zertifikate werden intern gecached. Dieser Cache muss regelmäßig aktualisiert werden. Dies ist notwendig um z.B. den änderbaren Sperrlistenstatus aktuell zu halten.

Der Cache wird automatisch auf zeitlicher Basis aktualisiert, per Default alle 6 Stunden.

Das Zeitinterval der automatischen Aktualisierung für Zertifikat-Caches kann über die Eigenschaft clear-certificate-cache konfiguriert werden. Hierbei handelt es sich um einen Cron-Ausdruck. Beispiel:

#         day of week ------------+
#               month ----------+ |
#        day of month --------+ | |
#                hour ------+ | | |
#              minute ----+ | | | |
#              second --+ | | | | |
#                       | | | | | |
clear-certificate-cache=0 0 6 * * *

Weitere Details zur Cron-Konfiguration finden Sie in der Spring-Doku.

AMQP Retry

Für alle 4 Arbeitsabläufe sign/encrypt/verify/decrypt, aufgrund einer nicht verfügbaren API- und REST-Verbindung, d.h. FSS oder HSM ist ausgefallen.Nachrichten können so konfiguriert werden, dass sie mehrmals wiederholt werden. Die Eigenschaft für die Anzahl der Wiederholungsversuche ist:

consumer.max.attempts=3

Dadurch wird sichergestellt, dass die Verbraucherwarteschlange die Nachricht dreimal wiederholt

Um das Intervall (ms) zwischen den einzelnen Wiederholungsversuchen zu konfigurieren, lautet die Eigenschaft:

consumer.retry.interval=2000

Die Standardwerte (ohne Konfiguration) sind 3 und 1000 ms für die oben genannten Eigenschaften.

Use Partner Address from Certificate

Um die Partneradresse aus dem Zertifikat zum Weiterleiten der SOAP-Nachricht zu verwenden, aktivieren Sie die folgende Eigenschaft.

useAddressFromCertificate=true

Der Standardwert ist ‘false’

Auch wenn die Adresse von der in der AS4-Datenbank gespeicherten Adresse abweicht, wird ein certificate.store.event erstellt, um die Adresse zu aktualisieren.

Crypto Error Codes

Encryption

Status/Error Code
Successful 200
Unavailable API 1280

Signature

Status/Error Code
Successful 200
Unavailable API 1380

Decryption

Status/Error Code
Successful 200
Unavailable API 1180
Encryption Missing 1200

Verification

Status/Error Code
Successful 200
Unavailable API 1480
Signature Missing 2400
Certificate expired 2410
Market Partner certificate not trusted 2540
Missing Issuer 2510
Missing RootCA 2500
Required hash algorithms not used 2441
Required sign algorithms not used 2442
Sender mismatch 2460

Allgemeine Hinweise zur Konfiguration finden Sie hier.

View Me   Edit Me