HÄVG-Prüfmodul Anleitung

Hinweis

Die vorliegende, modernisierte Version des HÄVG-Prüfmoduls (vormals als HPM Next bezeichnet) ist mit Q3/2023 zur HPM-Standardversion geworden. Es wird in der vorliegenden Anleitung als HPM oder HÄVG-Prüfmodul referenziert.

Das bisherige HÄVG-Prüfmodul, nachfolgend HPM Legacy genannt, erhält keine großen Funktionserweiterungen und wird nur noch in einer Übergangszeit mit den Quartals-Datenupdates versorgt.

Weiterführende Dokumentation zum HPM Legacy finden Sie in der HPM-Legacy-Hilfestellung.

Einführung

Das modernisierte HÄVG-Prüfmodul (HPM) steht nun im Regel- und Standardbetrieb bereit. Es bietet die bekannten HPM-Schnittstellen, jedoch wurde die Software von der Architektur her geändert.

Bitte beachten Sie insbesondere Hinweise zur Installation und zur neuen HTTP-Authentifizierung.

Interne Begrifflichkeiten

HPM-Bezeichnungen (ab Q3/2023)

• HPM: Die vormals als HPM Next bezeichnete modernisierte Version des HPM wird mit dem erfolgten flächendeckenden Rollout HPM genannt.
• HPM Legacy: Die vormals im Einsatz befindliche Standard-Version des HÄVG-Prüfmoduls, die für eine Übergangszeit als Fallback bereitsteht, wird HPM Legacy genannt.

In dieser Anleitung benutzen wir die Bezeichnungen “Shell” (HPM Executable) und “Fachservice”/“Service” innerhalb des modernisierten HPM-Produkts. Die folgende Grafik stellt die Architektur des HPM Legacy und des modernisierten HPM (ehemals HPM Next) gegenüber.

Abrufort und Inhalt der Installationspakete

Das HPM wie auch das HPM Legacy stehen über das AKA-Portal zum Abruf bereit. Sollten Sie Fragen zum Zugang oder zur Installation haben, melden Sie sich bitte per E-Mail an support@haevg-rz.de.

Inhalte

• installer.executable - z.B. HAEVG_Pruefmodul_2023Q3_Installer_Windows_x64.exe
• HPM_Anleitung.pdf – Die Anleitung zum HPM

Installation

-flagName (für Boolesche Werte)
-flagName=flagWert (für Boolesche und Integer Werte)
-flagName="flagWert" (für String Werte)

Nicht erlaubt: -flagName flagWert 

Standardinstallation - Schneller Start

Windows

Aufruf des Installers (HAEVG_Pruefmodul_2023Q3_Installer_Windows_x64.exe) mit Administratorrechten:

.\HAEVG_Pruefmodul_2023Q3_Installer_Windows_x64.exe -silent

Linux

Aufruf des Installers (HAEVG_Pruefmodul_2023Q3_Installer_Linux_x64.bin) mit Administratorrechten:

./sudo HAEVG_Pruefmodul_2023Q3_Installer_Linux_x64.bin -silent

macOS

Aufruf des Installers (HAEVG_Pruefmodul_2023Q3_Installer_macOS_x64.app) mit Administratorrechten:

./sudo HAEVG_Pruefmodul_2023Q3_Installer_macOS_x64.app -silent

Installationsverhalten

Bei Aufruf des Installers wird das System nach einem bereits installierten HPM untersucht:

a) Sollte ein zuvor installiertes HPM Legacy erkannt werden

• werden die HPM-Legacy-Dateien entfernt
• werden existierende Systemdienste des HPM Legacy deinstalliert
• wird die HPM-Legacy-Konfiguration (Ports und Flags usw.) übernommen
• wird das HPM als Dienst/Service im System installiert

b) Sollte ein zuvor installiertes HPM erkannt werden

• werden die HPM-Dateien entfernt
• werden existierende Systemdienste des HPM gestoppt und nach Installation gestartet
• wird die HPM-Konfiguration (Ports und Flags usw.) übernommen
• wird das HPM als Dienst/Service im System installiert
• Flags mit Konfigurationsdaten, z.B. -frontendPort oder -online, können verwendet werden, um vorhandene Werte in der Konfiguration zu überschreiben.

c) Sollte kein installiertes HPM erkannt werden

• wird das HPM mit einer Standardkonfiguration
• oder wahlweise, sofern per Flag angegeben, mit der mitgegebenen Konfiguration installiert.
• wird das HPM als Dienst/Service im System installiert

Hinweise zu fehlschlagenden Installationen

Das Setzen der Berechtigungen des Konfigurationsordners führt in manchen Fällen zum Abbruch der Installation. In solchen Fällen empfehlen wir, den ganzen Konfigurationsordner manuell zu löschen und anschließend die Installation erneut zu starten. Achtung: Wenn Sie keine Standardkonfiguration verwenden, sollten Sie die Konfigurationsdatei vorher sichern.

Besonderheiten

Ausgabe des interaktiven Installers bei alten Windows-Servern

Die Ausgabe in der Konsole kann verzerrt/unleserlich ausfallen. Dies verhindert nicht die erfolgreiche Installation, am besten per Flag -silent Installationen starten.

Mac/Linux Installer und Ausführungsrechte

Nach Download des Mac/Linux-Installers müssen der Installerdatei Ausführungsrechte erteilt werden (chmod +x), damit die Installation gestartet werden kann.

Code Signing

Unter Windows und macOS sind alle Installationsdateien signiert (bzw. notarisiert unter macOS).

Festplatten-Vollzugriff bei macOS nach Neuinstallation

Auf macOS muss nach einer Neuinstallation dem HPM der Festplatten-Vollzugriff gewährt werden.

Installationsmodi

Wichtig: Testsysteme/-installationen übermitteln keine Echtdaten

Wird bei der Installation das “-test”-Flag verwendet oder “IstTestsystem” in der Konfigurationsdatei auf “true” gesetzt, so handelt es sich um eine Testinstallation (o. Testsystem). Das bedeutet, dass sämtliche Daten als Testdaten interpretiert werden und keine Übertragung von Echtdaten an das HÄVG-Rechenzentrum erfolgt.

Interaktiver Modus

Im interaktiven Modus werden die Parameter bei dem User erfragt. Standardwerte können mit übernommen werden.

Jegliche weitere Konfiguration kann nach der Installation über die Konfigurationsdatei vorgenommen werden.

Silent-Modus

Über das Flag -silent kann die Installationsanwendung im nicht interaktiven Modus gestartet werden. Silent bedeutet nicht, dass eine reduzierte Ausgabe stattfindet. Es werden trotzdem minimalistisch Informationen zum Installationsvorgang ausgegeben. In diesem Modus können gleichzeitig andere Flags wie -port oder -installPath gesetzt werden. Ist nur das -silent-Flag gesetzt, wird für die restlichen Optionen ein Standardwert verwendet.

Liste der möglichen Installer Flags:

Wichtig: das Flag -keepLegacy führt zu einem Fehler, wenn ein gleichnamiger Legacy-Dienst installiert ist. Das Flag ist deshalb nur nutzbar, wenn ein manueller Konfigurationsschritt nach der Installation erfolgt. Ein Windows-Dienst muss unter anderem Dienstnamen, als der bestehende HPM Legacy Windows-Dienst, angelegt werden.

Erläuterungen zu Installationsflags

• -configFile: Im Silent-Modus kann eine spezifische Konfigurationsdatei (hpm_config.json) angegebenen werden. Dadurch wird es unnötig, die Parameter -port, -installPath, -online und -test zu verwenden. Bei der Verwendung von -extract und -portable wird -configFile ignoriert, weil eine Standard-Konfiguration verwendet wird.

• -convert: erwartet den Pfad zu einer InstallConfig.xml. Diese wird dann in das Konfigurationsdateiformat des HPM konvertiert und als hpm_config.json im gleichen Ordner abgelegt.

• -extract: erwartet einen Ordnerpfad, welcher ggfs. angelegt wird, und extrahiert alle Dateien des HPM in das Verzeichnis. Das HPM kann dann nach Bedarf von Hand gestartet werden. Kann in Kombination mit dem Flag -env verwendet werden. Aufgrund von deaktivierten Updates ist diese Funktionalität nur für den Testmodus geeignet. Verwenden Sie somit -extract immer in Kombination mit dem Flag -test.

• -portable: erstellt einen temporären Systemordner, in welchen die HPM-Dateien extrahiert werden. Darüber hinaus wird ein Satz freier Ports gesucht (Frontend-Port, Backend-Port, HZV, AMM, EAV) und eine hpm_config.json generiert. Die Konfigurationsdatei wird dann mit den gefundenen freien Ports angereichert und für den Start des HPM verwendet. Da das HPM im portablen Modus keine Updates durchführen kann, wird es hier so gestartet, dass alle Update-Funktionen deaktiviert sind. Aus diesem Grund wird dieser Modus nur im Testmodus, d.h. in Kombination mit dem Flag -test unterstützt. Kann in Kombination mit dem Flag -env verwendet werden.

• -env kann in jedem Installationsmodus genutzt werden, um Umgebungsvariablen anzugeben, welche im Zuge der Installation in die Konfigurationsdatei geschrieben werden. Das Format sieht vor, dass Name und Wert einer Umgebungsvariable durch ein Gleichzeichen getrennt werden. Die Werte selbst dürfen ebenfalls Gleichzeichen enthalten. Mehrere Umgebungsvariablen werden durch Semikola getrennt.

  Beispiel: ./installer.exe -env="name=wert;variable2=ganz_anderer_wert"

Anwendungsbeispiele für Silent-Modus und Sonderflags

Installer mit allen Infos starten

.\hpm-installer.exe -silent -installPath="C:\Programme\HPM" -port=24445 -online

Alternativ mit einer bestehenden Konfigurationsdatei starten (die nicht im Standardverzeichnis liegen muss):

./hpm-installer-linux -silent -configFile="/tmp/hpm_config.json"

Den Installer mit einer vorhandenen Konfiguration starten und spezifische Werte überschreiben:

./hpm-installer-linux -silent -configFile="/tmp/hpm_config.json" -port=7777 -online=false

Eine HPM-Legacy-Konfigurationsdatei (InstallConfig.xml) zu einer neuen hpm_config.json konvertieren (wird im gleichen Ordner abgelegt):

.\hpm-installer.exe -convert="C:\Config\InstallConfig.xml"

Return Codes bei Installation

Deinstallation

Die Deinstallation kann auf mehrere Arten durchgeführt werden:

1. Über den Installer: .\HAEVG_Pruefmodul_2023Q3_Installer_Windows_x64.exe -uninstall
2. Über die installierte HPM-Datei: .\hpm.exe -uninstall

Unter Windows besteht zusätzlich die Möglichkeit, das HPM über die Windows Systemeinstellung “Apps und Features” zu deinstallieren:

Update

Das HPM besitzt einen eigenen Update-Mechanismus, der es dem HPM erlaubt, die eigenen Komponenten der Anwendung zu aktualisieren.
Dies ist immer nur innerhalb einer Quartalsversion möglich.
Für das Aktualisieren der Quartalsversion muss der HPM Installer benutzt werden.

Das HPM umfasst dabei die Koponenten Datenbanken, Fachservices und die HPM Executable (hpm.exe|hpm.app|hpm.bin).
Updates der Datenbanken werden regelmäßig zur Verfügung gestellt. Die anderen Komponenten werden nur bei Bedarf aktualisiert.

Trigger

Es gibt drei Wege, wie die Updatesuche und das Update startet: beim Start des HPM, nächtlich einmalig zwischen 1-4 Uhr und mittels SOAP oder REST Request.

Das HPM wird bei jedem Start einmal nach Updates suchen. Falls ein Update gefunden wird, wird dieses heruntergeladen und vorbereitet.
Nach der erstmaligen Updatesuche wird die Updatesuche jede Nacht maximal einmal im Zeitfenster von 1-4 Uhr durchgeführt.

Zusätzlich kann ein Update auch per Request an das HPM angefordert werden

REST: http:localhost:22220/api/update
SOAP: http:localhost:22220/Service.asmx

Request Body für SOAP:

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
 <soap12:Body>
  <Update xmlns="http://haevg-rz.de/hpm" />
 </soap12:Body>
</soap12:Envelope>

Downtime

Das HPM ist solange voll funktionsfähig, bis alle Updatedateien heruntergeladen und für das Update vorbereitet sind.
Nur zum Zeitpunkt des Updates sind die sonstigen Funktionen des HPMs nicht verfügbar. Die Downtime ist somit so kurz wie möglich gehalten.

Erfolgreiche Updates

Während des Downloads der Updatedateien bleibt das HPM erreichbar. Für die Dauer des Updateprozesses selbst hingegen sind die Fachservices nicht erreichbar. Bei Aktualisierung der HPM Executable wird das HPM neu gestartet. Das Log enthält nach einem erfolgreichen Update den Eintrag

“Update erfolgreich! ‘[Komponente]’ [Aktuelle Version] -> [Neue Version].”

Fehlgeschlagene Updates

Sollte ein Update während des Updates oder nach einer Update-Erfolgsprüfung fehlschlagen, wird versucht, das HPM auf die ursprüngliche Version zurückzusetzen.
Das Log enthält in diesem Fall den folgenden Eintrag:

“Fehler erkannt: [Fehlermeldung] Versuche auf Version [Ursprungsversion] zurückzusetzen.”

Sollte es beim Zurücksetzen des HPMs zu einem unvorhergesehenen Fehler kommen, wenden Sie sich bitte an unseren Support.

Sicherheit

Alle Updates sind signiert und werden vor der Anwendung geprüft.

Voraussetzungen

Es wird bei jedem Start des HPM sowie täglich in der Nacht zwischen 0:00 Uhr und 4:00 Uhr auf Updates geprüft. Damit Updates ausgeführt werden können, muss

• die Erreichbarkeit des Update Servers gewährleistet sein (https://hpm-prod-update.az.haevg-rz.net/update/)
• unter macOS “Full Disk Access” für das HPM aktiviert sein (siehe Abschnitt ‘Festplatten-Vollzugriff bei macOS nach Neuinstallation’).

Konfiguration

Es existiert eine zentrale Konfigurations-Datei (hpm_config.json), welche zur Steuerung der Anwendung, Festlegung der Ports, der zu startenden Fachservices sowie weiterer Einstellungen dient.

hpm_config.json, wie sie nach einer Standardinstallation auf einem Windowssystem aussieht:

{
    "AppInstallPath":"C:\\Program Files\\HÄVG Rechenzentrum AG\\HÄVG-Prüfmodul",
    "IstOnline":true,
    "IstTestsystem":true,
    "BackendPort":22230,
    "FrontendPort":22220,
    "FrontendTLSPort":22225,    

    "BackendTimeoutSeconds":600,
    "LogLevel":0,
    "LogDirectory":"C:\\ProgramData\\HÄVG Rechenzentrum AG\\HÄVG-Prüfmodul",
    "DatabaseDirectory": "C:\\Program Files\\HÄVG Rechenzentrum AG\\HÄVG-Prüfmodul\\Database",
    "TelemetryEndDate": "2023-10-20T00:00:00",
    "Proxy": "http://localhost:999",
    "ServiceMetaInfos":[     
        {
            "Name":            "HZV",
            "ExecutableName":  "HaevgRZ.HPM.HZV.Service",
            "Port":            22240,
            "Path":            ""
        },
        {
            "Name":            "AMM",
            "ExecutableName":  "HaevgRZ.HPM.AMM.Service",
            "Port":            22250,
            "Path":            ""
        },  
        {
            "Name":            "EAV",
            "ExecutableName":  "HaevgRZ.HPM.EAV.Service",
            "Port":            22260,
            "Path":            ""
        }
   ]
}  

Diese Konfiguration kann um Entwicklungsschalter erweitert werden, die nur auf Testsystemen funktionieren

   [...]
   "DevSettings": {
       "HPM_VerwendeEingebettetesEntwicklungsZertifikat": "false",
       "HPM_SkipFachserviceStart": "false",
       "HPM_Maintenance": "true",
       "HPM_DateTimeNow":"2023-06-20T10:00:00",
   }
   [...]

Konfigurationsdatei mit Konfigurationsschema validieren

Mit dem Konfigurationsschema können angepasste oder manuell erstellte Konfigurationsdateien validiert werden.

Validierung in Visual Studio Code aktivieren

In der /.vscode/settings.json Datei kann diese Einstellung hinzugefügt werden und somit die Validierung der Konfigurationsdatei mit der Schema-Datei aktiviert werden.

"json.schemas": [ {
        "fileMatch": [ "*/*hpm_config.json"],
        "url": "./hpm_config.schema.json"
    }]

Validierung mit Powershell (ab 7.4.0)

Test-Json -Path hpm_config.json -SchemaFile hpm_config.schema.json

Konfigurationsschema herunterladen

Info: Diese Datei wir beim Installieren neben die hpm_config.json ins Konfigurationsverzeichnis gelegt.

Flag-Beschreibung

Umgebungsschalter und DevSettings zur Steuerung des Verhaltens

Es existieren weitere Umgebungsvariablen und Einstellungen, welche das Verhalten des HPM beeinflussen. Nehmen Sie daher Änderungen mit Bedacht vor und bitte nur, wenn Sie sich der Folgen der Änderungen bewusst sind. Beachten Sie, dass Sie das HPM neustarten müssen, damit die Änderungen wirksam werden.

Folgende Werte sind verfügbar:

Im HPM Legacy bestand die Möglichkeit der Verwendung einer .env-Datei, um Umgebungsvariablen gesammelt und applikationsspezifisch setzen zu können. Diese Datei wird vom HPM nicht mehr verwendet.

Schnittstellenübersicht HPM

Bisher stellte das HPM SOAP-Methoden zur Kommunikation bereit. Diese werden auch zukünftig verfügbar sein. Zusätzlich gibt es parallel jetzt auch REST-Methoden, welche die gleiche Funktionalität bereitstellen.

Testfälle

Zum Testen der Schnittstelle bieten wir eine Sammlung von Testfällen an, die mit Postman ausgeführt werden können. Diese stehen im AKA-Portal zum Download bereit.

Außerdem können Test-Requests auch über die Swagger-Seiten ausgeführt werden. Die Swagger-Seiten dokumentieren die einzelnen Endpunkte und bieten jeweils einen Testfall an, der ohne Authentifizierung beim HPM ausgeführt werden kann.

Die Swagger-Seiten sind auf der HPM-Infoseite verlinkt.

REST

Jeder Fachservice verfügt über eine eigene OpenAPI-Spezifikation, welche als Swagger-Datei betrachtet werden kann:

• HZV: http://localhost:22240/swagger/index.html

• AMM: http://localhost:22250/swagger/index.html

• EAV: http://localhost:22260/swagger/index.html

Über die Swagger-Seite können direkt auch Test-Requests an das HPM geschickt werden.

Die Pfade, die in Swagger angezeigt werden, müssen für einen Aufruf vom PVS oder Postman heraus angepasst werden:

• Der Port muss auf den FrontendPort des HPMs geändert werden (siehe Konfiguration)
• Der Pfad muss um latest/{Name des Fachservices} angepasst werden.

Als Beispiel vom HZV-Service:

http://localhost:22240/api/versichertenteilnahmen/erklaerungen → verfügbar über HPM mit http://localhost:22220/api/latest/hzv/versichertenteilnahmen/erklaerungen

Die Swaggerseiten sind nur in Testinstallationen erreichbar, nicht in produktiven Installationen.

Übertragung von XML-Inhalten

XML Dokumente müssen bei Verwendung der REST-Schnittstelle URL über ein String Property übertragen werden.

SOAP

Die WSDL für SOAP kann über http://{{HPM_HOST}}:{{HPM_PORT}}/Service.asmx?wsdl (Beispiel: http://localhost:22220/Service.asmx?wsdl) erreicht werden.

Bitte beachten: Der Endpunkt ist “case-sensitive”, die Großschreibung von “Service” ist für den Abruf der wsdl, aber auch für die generelle Nutzung essentiell.

HTTP-Authentifizierung

Die Beschreibung zur HTTP-Authentifizierung finden Sie in der HPM-Anleitung (PDF), die aus dem AKA-Portal bezogen werden kann.

Breaking changes

1. Es gibt bei der SOAP-Schnittstelle wenige Änderungen im Vergleich zum HPM Legacy. Diese betreffen nur das XML-Choice Attribut der WSDL. Hieraus resultiert folgende Liste mit Änderungen:

Methode:  ErzeugeZertifikatArzt

Bisher:
<s:complexType name="ArztIdentifikationType">
   <s:choice>
      <s:element minOccurs="1" maxOccurs="1" name="ArztIdentifikationscode" type="s:string"/>
      <s:element minOccurs="1" maxOccurs="1" name="ArztIdentifikationZertifikat" type="tns:ArztIdentifikationZertifikatType"/>
   </s:choice>
</s:complexType>
 
Jetzt:
<s:complexType name="ArztIdentifikationType">
   <s:sequence>
      <s:element minOccurs="0" maxOccurs="1" name="ArztIdentifikationscode" type="s:string"/>
      <s:element minOccurs="0" maxOccurs="1" name="ArztIdentifikationZertifikat" type="tns:ArztIdentifikationZertifikatType"/>
   </s:sequence>
</s:complexType>
 
Methode: SendeArztbrief

Bisher:
<s:complexType name="ArztbriefEmpfaenger">
   <s:choice>
      <s:element minOccurs="1" maxOccurs="1" name="Bsnr" type="s:string"/>
      <s:element minOccurs="1" maxOccurs="1" name="EmpfaengergruppeIdentifikator" type="s:int"/>
   </s:choice>
</s:complexType>

Jetzt:
<s:complexType name="ArztbriefEmpfaenger">
   <s:sequence>
      <s:element minOccurs="0" maxOccurs="1" name="Bsnr" type="s:string"/>
      <s:element minOccurs="0" maxOccurs="1" name="EmpfaengergruppeIdentifikator" type="s:int"/>
   </s:sequence>
</s:complexType>
 
Methode: SendeTelekonsil

Bisher:
<s:complexType name="TelekonsilEmpfaenger">
   <s:choice>
      <s:element minOccurs="1" maxOccurs="1" name="Lanr" type="s:string"/>
      <s:element minOccurs="1" maxOccurs="1" name="EmpfaengergruppeIdentifikator" type="s:int"/
   </s:choice>
</s:complexType>
 
Jetzt:     
<s:complexType name="TelekonsilEmpfaenger">
   <s:sequence>
      <s:element minOccurs="0" maxOccurs="1" name="Lanr" type="s:string"/>
      <s:element minOccurs="0" maxOccurs="1" name="EmpfaengergruppeIdentifikator" type="s:int"/>
   </s:sequence>
</s:complexType>
 
 
Methode: SendeEinweisungsbrief

Bisher:
<s:complexType name="EinweisungsbriefEmpfaenger">
   <s:choice>
      <s:element minOccurs="1" maxOccurs="1" name="Institutionskennzeichen" type="s:string"/>
      <s:element minOccurs="1" maxOccurs="1" name="EmpfaengergruppeIdentifikator" type="s:int"/>
   </s:choice>
</s:complexType>
 
Jetzt:
<s:complexType name="EinweisungsbriefEmpfaenger">
   <s:sequence>
      <s:element minOccurs="0" maxOccurs="1" name="Institutionskennzeichen" type="s:string"/>
      <s:element minOccurs="0" maxOccurs="1" name="EmpfaengergruppeIdentifikator" type="s:int"/>
   </s:sequence>
</s:complexType>

2. Die SOAP-Schnittstelle unterstützt keine custom Namespaces mehr

3. Die Rückgabeinhalte der SOAP-Methode LiefereHpmInformation und der REST Endpunkt /api/hpminformation weichen vom HPM Legacy ab

   a) Die Version im Format YYYY-Q-NNNN (Beispiel: 2022-4-0337) und nicht mehr QX-YYYY.Z

   b) Die Auflistung der Vertragsidentifikatoren ist entfallen

HPM-Erreichbarkeit

Öffentliches Internet

Da über das HPM u. A. besonders schützenswerte Daten übermittelt werden, ist es von besonderer Wichtigkeit, dass die laufenden HPM-Dienste/-Programme NICHT über das Internet bzw. NUR in Ihrem lokalen Netzwerk erreichbar sind.

HPM-Ports und Prozesse im internen Netzwerk

Damit das HPM Next (und die dazugehörigen Fachservices) für andere Programme in Ihrem Netzwerk erreichbar ist, benötigt das HPM mehrere Ports, unter welchen es aufgerufen werden kann. Diese Ports sind über die Konfigurationsdatei änderbar. Folgende Ports werden vom HPM Next und von den Fachservices standardmäßig verwendet:

• 22220 und 22225 (TLS) HPM aus Sicht des PVS
• Interne Ports (nur über localhost erreichbar, nicht für Fremdbenutzung gedacht):
  • 22230 Interne Kommunikation der Fachservices
  • 22240 Fachservice HZV
  • 22250 Fachservice AMM
  • 22260 Fachservice eAV

Um einen reibungslosen Betrieb zu gewährleisten, stellen Sie bitte vor Start des HPM sicher, dass die eingestellten Ports nicht belegt sind.

Vom Haupt-Prozess des HPM ausgehend wird automatisch dafür gesorgt, dass die Fachservices als Kind-Prozesse gestartet und im Falle eines Absturzes auch automatisch neu gestartet werden.

HPM Verfügbarkeit im internen Netzwerk testen

Ob das HPM und die Fachservices ordnungsgemäß gestartet gewerden konnten und erreichbar sind, kann über die “Health”-Schnittstelle (/api/health) abgefragt werden. Dieser Endpunkt benötigt keine Authentifizierung. Das globale Datenfeld “Verfügbar” hat nur dann den Wert true, wenn alle Endpunkte verfügbar sind. Soll die Verfügbarkeit eines bestimmten Services oder Proxys abgefragt werden, können die jeweiligen Datenfelder der Endpunkt-Objekte abgefragt werden. Ein Beispiel findet sich dazu auch in der OpenAPI-Spezifikation des HPMs.

Installation als Service

Zusätzlich zur Gesamtinstallation des HPM (s. Abschnitt “Installation”) bietet die HPM-Executable die Möglichkeit, per Parameter explizit die Installation als Daemon oder Service durchzuführen, entsprechende Berechtigungen des ausführenden Benutzers vorausgesetzt.

Windows

Die HPM Executable ist zu diesem Zweck um folgende Eingabeparameter erweitert:

• -svc=install - installiert das HPM Next als Service
• -svc=uninstall - deinstalliert den HPM-Next-Service
• -svc=start - startet den das HPM-Next-Service
• -svc=stop - stoppt den das HPM-Next-Service

Eine beispielhafte Ausführung wäre “.\hpm.exe -svc=install”.

Linux

Eine beispielhafte Ausführung wäre “./hpm.bin -svc=install”.

macOS

Eine beispielhafte Ausführung wäre “./hpm.app -svc=install”

Dateiintegrität

Die Dateiintegrität ist mit einer Ed25519-Signatur gewährleistet, zum Überprüfen der Signatur nutzen Sie das Tool minisign.

Beispielhaft das Überprüfen des Archives mit der Datenbank:

minisign.exe -V -m Database.tar -P RWTKQPJTILubVJRZkRf50ToJxQfcTlPnW40t+iJN2ceh9G10lW0wPBES

Erwartete Ausgabe: “Signature and comment signature verified”

HÄVG RZ Public Ed25519 Schlüssel: RWTKQPJTILubVJRZkRf50ToJxQfcTlPnW40t+iJN2ceh9G10lW0wPBES

TLS in der Praxis

Auf den EDV-Systemen der Ärzte werden sensible, schützenswerte Daten von Patienten verarbeitet. Da das HÄVG-Prüfmodul als Datenvermittler auch Teil der Übermittlungsstrecke ist, kann der Datenfluss zwischen den PVS-Systemen und dem HPM innerhalb der Arztpraxis verschlüsselt stattfinden.

Es sind beide Modi (HTTP und HTTPS) parallel verfügbar.

Angelehnt ist die TLS-Implementierung des HPM an die Telematik-Infrastruktur 1.0 der Gematik.

Abrufen des Fingerabdrucks

Es steht ein Endpunkt unter dem Pfad /fingerprint zur Verfügung, um den Fingerabdruck des HPM-Zertifikats abzurufen. Dieser wird sich auf lange Sicht nicht ändern und kann zwischengespeichert werden.

Technischer Rahmen

• minimale TLS-Version: v1.2
• Algorithmus zur Schlüsselgenerierung: ECDSA
• Zertifikat-Signaturalgorithmus: ECDSAWithSHA256

Liste der Cipher Suites

Die untenstehende Liste stellt eine erschöpfende Aufzählung aller verwendeten Cipher Suites für TLS-Version 1.2 dar. Diese unterstützen bei TLS-Version 1.2 Perfect Forward Secrecy.

• TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Bei TLS-Version 1.3 sind die verwendetet Cipher Suites unveränderlich festgelegt und Perfect Forward Secrecy ist in jedem Fall aktiv.

Referenzimplementierungen

Es besteht die Möglichkeit, dem Zertifikat des HPM bedingungslos zu vertrauen, dies wird jedoch nicht empfohlen. Stattdessen kann der Fingerabdruck des HPM-Zertifikats mit ebendem Fingerabdruck verglichen, welcher unter /fingerprint abrufbar ist.

Java

Ein Möglichkeit stellt eine benutzerdefinierte SSLSocketFactory mit einer eingenen Implementierung der Methode checkServerTrusted() der TrustManager-Klasse dar.

public class MyCustomSSLSocketFactory extends SSLSocketFactory {
   SSLContext sslContext = SSLContext.getInstance("TLS");

   public MyCustomSSLSocketFactory(KeyStore truststore) throws NoSuchAlgorithmException, KeyManagementException, KeyStoreException, UnrecoverableKeyException {
      super(truststore);

      TrustManager tm = new X509TrustManager() {
         public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException {
         }

         public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException {
            // hier Fingerprint des Server-Zertifikats mit zuvor
            // abgerufenem Wert vergleichen und ggfs. Exception werfen
         }

         public X509Certificate[] getAcceptedIssuers() {
               return null;
         }
      };

      sslContext.init(null, new TrustManager[] { tm }, null);
   }

   //hier den initial erstellten SSLContext verwenden

   @Override
   public Socket createSocket(Socket socket, String host, int port, boolean autoClose) throws IOException, UnknownHostException {
      return sslContext.getSocketFactory().createSocket(socket, host, port, autoClose);
   }

   @Override
   public Socket createSocket() throws IOException {
      return sslContext.getSocketFactory().createSocket();
   }
}

Verwendet werden kann es so:

KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
trustStore.load(null, null);

MyCustomSSLSocketFactory sf = new MyCustomSSLSocketFactory(trustStore);
sf.setHostnameVerifier(SSLSocketFactory.ALLOW_ALL_HOSTNAME_VERIFIER); // ggfs. anpassen

// ggfs. anpassen
HttpParams params = new BasicHttpParams();
HttpProtocolParams.setVersion(params, HttpVersion.HTTP_1_1);
HttpProtocolParams.setContentCharset(params, HTTP.UTF_8);

// ggfs. anpassen
SchemeRegistry registry = new SchemeRegistry();
registry.register(new Scheme("http", PlainSocketFactory.getSocketFactory(), 80));
registry.register(new Scheme("https", sf, 443));

ClientConnectionManager ccm = new ThreadSafeClientConnManager(params, registry);

HttpClient client = DefaultHttpClient(ccm, params);

C#

static async Task MyMethod(string[] args)
{
   using var handler = new HttpClientHandler();
   handler.ServerCertificateCustomValidationCallback = CheckCert;

   using var client = new HttpClient(handler);
   // ...
}

private static bool CheckCert(HttpRequestMessage requestMessage, X509Certificate2 cert, X509Chain chain, SslPolicyErrors errors)
{
   Console.WriteLine($"Cert Thumbprint: {cert.Thumbprint}");
   return true;
}

Go

var fingerprint string

func main() {

	client := &http.Client{
		Timeout: 10 * time.Second,
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{
				InsecureSkipVerify: true,
				VerifyConnection: func(state tls.ConnectionState) error {
					if len(state.PeerCertificates) == 0 {
						return fmt.Errorf("Server hat kein Zertifikat gesendet")
					}

					cert := state.PeerCertificates[0]
					if GetCertificateFingerprint(cert) != fingerprint {
						return fmt.Errorf("Fingerprint passt nicht")
					}

					// prüfen, ob das Zertifikat zeitlich noch gültig ist
					now := time.Now()
					if cert.NotBefore.After(now) || cert.NotAfter.Before(now) {
						return fmt.Errorf("Zertifikat ist zeitlich nicht mehr gültig")
					}

					return nil
				},
			},
		},
	}

	resp, err := client.Get("http://localhost:22220/fingerprint")
   if err != nil {
		panic(err)
	}
	fp, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	if len(fp) > 0 {
		fingerprint = string(fp)
	}

	resp, err = client.Post("https://localhost:22225/api/hpminformation", "application/json", nil)
	if err != nil {
		panic(err)
	}
	hpmInfo, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
   defer resp.Body.Close()
	fmt.Println(string(hpmInfo))	
}

func GetCertificateFingerprint(x509Cert *x509.Certificate) string {
	sum := sha256.Sum256(x509Cert.Raw)
	return strings.ToLower(hex.EncodeToString(sum[:]))
}

Betrieb des HPM Next mit alternativem Zeitstempel

Für Zulassungen oder andere Szenarien kann es notwendig sein, das HPM in der Zukunft zu betreiben. Hierfür ist die Einstellung in der hpm_config.json “HPM_DateTimeNow” auf das gewünschte Datum zu setzen.

Es ist für das HPM nicht notwendig, dass die Systemzeit geändert wird. Sollte dies allerdings für den Client des HPMs notwendig sein, gibt es zwei mögliche Verfahren:

• Zusätzliche Angleichung der Systemzeit des HPM Servers an den Client
• Anpassung des X-DateTime-Headers bei Requests an das HPM. Die Zeitangabe muss mit der Systemzeit des HPMs übereinstimmen. Der angepasst Header muss dann auch für die Berechnung des BasicAuth-Headers verwendet werden.

HPM Zeit

Über die REST-Schnittstelle /api/timestamp kann die aktuelle Systemzeit des HPMs abgerufen werden. Diese wird beim Setzem des altenativen Zeitstempels “HPM_DateTimeNow” nicht überschrieben. Es wird die tatsächliche Systemzeit zurückgegeben.