KIM-Konten: Technik und Fehlersuche

Diese Hilfeseite ergänzt die Bildschirmhilfe zu KIM-Konten um technische Hintergründe und Hinweise für Fehlersuche und Systemkonfiguration. Für weitere Informationen siehe KIM-Konten.

Technische Einordnung

Für KIM sind vier Ebenen zu unterscheiden:

Ebene Bedeutung
charly charly ist die KIM-Anwendung mit der Oberfläche für KIM-Konten und KIM-Nachrichten.
KIM-Clientmodul Das externe KIM-Clientmodul stellt die technische Verbindung zwischen charly und dem KIM-Provider her.
KIM-Provider Der KIM-Provider stellt KIM-Dienst, Postfächer und die zugehörige Infrastruktur bereit.
TI-Umgebung Zur TI-Umgebung gehören insbesondere Konnektor, Kartenterminal, SMC-B und HBA.
Hinweis: charly verbindet sich für KIM nicht direkt mit dem KIM-Provider, sondern mit dem externen KIM-Clientmodul.

 

Technische Voraussetzungen

Technische Umgebung außerhalb von charly

Für die KIM-Nutzung müssen die folgenden externen Komponenten und Dienste grundsätzlich vorhanden und betriebsbereit sein:

Tipp: Das Fachportal der gematik bietet u.a. eine Liste aller zugelassenen Komponenten und Dienste.

Voraussetzungen in charly

 

Verbindung zwischen charly und KIM-Clientmodul

So arbeitet charly mit dem KIM-Clientmodul zusammen

charly enthält die KIM-Anwendung, also die Oberfläche zum Verwalten des KIM-Kontos sowie zum Senden und Empfangen von KIM-Nachrichten. Für die technische Verbindung zum KIM-Provider wird zusätzlich ein externes KIM-Clientmodul benötigt. charly verbindet sich daher nicht direkt mit dem KIM-Provider, sondern mit dem KIM-Clientmodul. Die Angaben im Bereich Clientmodul-Verbindung müssen deshalb immer aus der Konfiguration dieses KIM-Clientmoduls übernommen werden.

Hinweis: Das KIM-Clientmodul erhalten Sie von Ihrem KIM-Provider. Installieren und konfigurieren Sie das KIM-Clientmodul entsprechend der Dokumentation Ihres KIM-Providers auf dem System, auf dem es für charly erreichbar ist.
Hinweis: Die in charly hinterlegten Zertifikate gehören zur Verbindung zwischen charly und dem KIM-Clientmodul. Relevant sind also die Zertifikate, mit denen sich das KIM-Clientmodul gegenüber charly ausweist oder mit denen sich charly gegenüber dem KIM-Clientmodul authentifiziert. Es geht an dieser Stelle nicht um Zertifikate des Konnektors.

Clientmodul-Verbindung eintragen

Übernehmen Sie für die Felder POP3, SMTP, Port, POP3-Benutzername und SMTP-Benutzername die Angaben aus dem KIM-Clientmodul. Maßgeblich ist immer die dort konfigurierte Verbindung zwischen charly und dem KIM-Clientmodul.

Verwenden Sie dabei genau das im KIM-Clientmodul vorgesehene Protokoll:

Wenn im KIM-Clientmodul TLS aktiviert ist, müssen Protokoll, Port und gegebenenfalls Zertifikate in charly dazu passen. Verwenden Sie für die Clientmodul-Verbindung möglichst den Hostnamen, der im Zertifikat des KIM-Clientmoduls eingetragen ist. Eine feste IP-Adresse verwenden Sie nur dann, wenn diese im Zertifikat ebenfalls hinterlegt ist oder die TLS-Konfiguration dies ausdrücklich zulässt. localhost oder 127.0.0.1 verwenden Sie nur dann, wenn das Clientmodul tatsächlich auf demselben System wie charly läuft und die TLS-Konfiguration auch dafür passt.

Häufig werden für TLS-Verbindungen die Standard-Ports 995 für POP3 und 465 für SMTP verwendet. Maßgeblich sind aber immer die Ports, die im KIM-Clientmodul tatsächlich konfiguriert sind.

Hinweis: Unter macOS können Ports mit einer Portnummer < 1024 vom KIM-Clientmodul nicht verwendet werden. Konfigurieren Sie dort für POP3 und SMTP freie Portnummern > 1024 und übernehmen Sie diese Werte anschließend in charly.

Wann werden CA-Zertifikat und Clientzertifikat benötigt?

Konfiguration des KIM-Clientmoduls Erforderliche Angaben in charly
Ohne TLS Verwenden Sie pop3:// und smtp://. Zertifikate werden nicht benötigt.
TLS ohne Client-Authentifizierung Verwenden Sie pop3s:// und smtps://. Ein CA-Zertifikat kann erforderlich sein, wenn charly das Zertifikat des KIM-Clientmoduls nicht bereits vertrauen kann.
TLS mit Client-Authentifizierung Verwenden Sie pop3s:// und smtps://. Zusätzlich ist ein Clientzertifikat erforderlich. Je nach Aufbau des KIM-Clientmoduls wird außerdem ein CA-Zertifikat oder die passende Zertifikatskette benötigt.

Das CA-Zertifikat dient dazu, dass charly die Server-Seite des KIM-Clientmoduls prüfen kann. Je nach Clientmodul ist dies das Server-Zertifikat des KIM-Clientmoduls selbst oder das ausstellende CA-Zertifikat beziehungsweise die dazugehörige Zertifikatskette.

Das Clientzertifikat laden Sie nur dann hoch, wenn das KIM-Clientmodul für eine TLS-Verbindung mit Client-Authentifizierung konfiguriert ist. Das Zertifikat muss den privaten Schlüssel enthalten. In charly wird dafür ein PKCS#12-Container im Format .p12 verwendet.

Multikonnektor-Setup und Konnektor-ID

Das Multikonnektor-Setup ist nur relevant, wenn Ihr KIM-Clientmodul für eine Umgebung mit mehreren Konnektoren konfiguriert ist. In einer Einzelkonnektor-Konfiguration bleibt der Schalter deaktiviert.

Wenn der im KIM-Clientmodul hinterlegte POP3- oder SMTP-Benutzername bereits eine Konnektor-ID enthält, übernimmt charly diese Angabe automatisch und aktiviert den Schalter.

Die Konnektor-ID ist kein frei wählbarer Wert in charly. Verwenden Sie bei manueller Eingabe nur die Konnektor-ID, die im KIM-Clientmodul für den gewünschten Konnektor hinterlegt ist.

Aktivieren Sie das Multikonnektor-Setup nicht vorsorglich. Tragen Sie in das Feld Konnektor-ID keine Konnektorbezeichnung, keinen Hostnamen und keine Seriennummer ein, wenn diese Werte nicht ausdrücklich so im KIM-Clientmodul konfiguriert wurden.

 

Zusammenspiel mit Konnektor und Kartenumgebung

Für das Verständnis der Gesamtumgebung kann zusätzlich wichtig sein, dass das externe KIM-Clientmodul nicht nur mit charly und dem KIM-Provider zusammenarbeitet, sondern je nach Umgebung auch mit dem Konnektor, dem Kartenterminal und den zugehörigen Karten.

Diese technische Kette wird nicht vollständig in charly konfiguriert. In charly pflegen Sie die Verbindung zum KIM-Clientmodul sowie die kontobezogenen Angaben. Die Einrichtung des KIM-Clientmoduls selbst, seine technische Anbindung an Konnektor und Kartenumgebung sowie weitere TI-bezogene Randbedingungen gehören zur übrigen Systemumgebung.

 

Technische Ports in der Systemumgebung

Für KIM sind zwei Portgruppen zu unterscheiden: die Ports der Verbindung zwischen charly und dem externen KIM-Clientmodul sowie weitere Ports der charly-Systemumgebung.

Portgruppe Typische Standardports Einordnung
Verbindung charly / KIM-Clientmodul bei TLS häufig 995 für POP3 und 465 für SMTP Diese Ports tragen Sie für das jeweilige KIM-Konto in charly ein. Maßgeblich ist immer die Konfiguration des KIM-Clientmoduls; einzelne Clientmodule können abweichende Ports verwenden. Siehe Wie lauten die Standard-URLs der bei der solutio GmbH & Co. KG getesteten Clientmodule und Provider?.
charly-Systemumgebung 10443 für den SSL-Proxy, 14711 für den Messaging-Service (HTTP), 14712 für den Messaging-Service (STOMP) Diese Ports betreffen nicht die fachliche Verbindung zum KIM-Provider. Sie können aber in der Systemkonfiguration relevant sein, z.B. wenn Portkonflikte oder Firewall-Regeln geprüft werden müssen.

Die folgenden Hinweise und Anleitungen betreffen diese zusätzliche Systemkonfiguration von SSL-Proxy und Messaging-Service.

Falls einer oder mehrere der erforderlichen Ports für KIM bereits belegt sind, konfigurieren Sie diese um:

 

Hinweis: Sofern keine neuere charly-Version vorliegt, aktualisiert der charly-Updater ausschließlich den charly-Java-Server und nimmt dabei die Port-Änderungen vor. Falls eine neuere charly-Version verfügbar ist, aktualisiert der charly-Updater zusätzlich die charly-Version.

Voraussetzungen

  • Der charly-Updater liegt auf dem charly-Server (Download Windows bzw. Download macOS).
  • Der charly-Server verfügt über eine Internetverbindung.

  • Das Ausführen des charly-Updaters ist vorbereitet:

    1. Schalten Sie alle charly-Arbeitsplätze (Clients) aus.
    2. Schließen Sie auf dem charly-Server alle Programme.
    3. Führen Sie auf dem charly-Server eine Datensicherung durch.
    4. Starten Sie den charly-Server neu.
    5. Melden Sie sich mit Administratorrechten am charly-Server an.
    6. Deaktivieren Sie auf dem charly-Server den Virenscanner für den Zeitraum des Updates.

Vorgehensweise

  1. Starten Sie den charly-Updater.
  2. Folgen Sie den Anweisungen des charly-Updater-Assistenten bis zu der Maske für die Konfiguration der Ports für den SSL-Proxy sowie für den messaging-Service.
  3. Ändern Sie den bzw. die Ports.

  4. Folgen Sie weiter den Anweisungen des charly-Updater-Assistenten.

    • Der charly-Updater führt die Port-Änderungen für die Services durch.
  1. Öffnen Sie auf dem Server folgendes Verzeichnis:
    <charly-Installationspfad>\Solutio\Server\ncjs\
  2. Legen Sie in diesem Verzeichnis das Verzeichnis „conf2“ und darin das Verzeichnis „messaging“ an:
    <charly-Installationspfad>\Solutio\Server\ncjs\conf2\messaging\
  3. Legen Sie in dem Verzeichnis „messaging“ eine Textdatei an und benennen Sie diese mit „application.yml“.

  4. Kopieren Sie die folgende Einstellung in die application.yml:

    de.solutio.ncjs.messaging.broker.stomp.port:14712

  5. Ändern Sie den Port.

  6. Damit der messaging-Service die fertig bearbeitete application.yml verwendet, muss der messaging-Service neu gestartet werden:

      1. Navigieren Sie in die Perspektive  Administration >  Systemstatus >  Komponenten.
      2. Klicken Sie in der Tabelle bei der Komponente auf den Menü-Button .
      3. Wählen Sie die Option  Neu starten.
      4. Klicken Sie auf den Button  Neu starten.
  7. Prüfen Sie, ob der messaging-Service gestartet ist.

 

FAQ zu Beispielwerten und Fehlersuche

Clientmodule

Hinweis: Verwenden Sie bei einer TLS-Konfiguration möglichst den Hostnamen, der im Zertifikat des KIM-Clientmoduls eingetragen ist. Eine feste IP-Adresse verwenden Sie nur dann, wenn diese im Zertifikat ebenfalls hinterlegt ist oder die TLS-Konfiguration dies ausdrücklich zulässt. localhost oder 127.0.0.1 verwenden Sie nur dann, wenn das KIM-Clientmodul tatsächlich auf demselben System wie charly läuft und die TLS-Konfiguration auch dafür passt.
  Clientmodul POP3 mit TLS Clientmodul SMTP mit TLS
AKQUINET pop3s://<IP-Adresse des KIM-Clientmodul-Hostsystems>:995 smtps://<IP-Adresse des KIM-Clientmodul-Hostsystems>:465
Arvato
T-Systems
CGM pop3s://<IP-Adresse des KIM-Clientmodul-Hostsystems>:8995 smtps://<IP-Adresse des KIM-Clientmodul-Hostsystems>:8465

Provider

  POP3 SMTP
AKQUINET mail.akquinet.kim.telematik:995 mail.akquinet.kim.telematik:465
Arvato mail.arv.kim.telematik:995 mail.arv.kim.telematik:465
CGM <spezifische-mail-domain>:995 <spezifische-mail-domain>:465
T-Systems lb-mail.eqxffm.tsi.kim.telematik:995 lb-mail.eqxffm.tsi.kim.telematik:465
Meldung oder Situation Prüfung
Connect failed Prüfen Sie Host, Port und Protokoll. Häufige Ursachen sind ein falscher Hostname, eine falsche IP-Adresse, ein falscher Port oder pop3s/smtps, obwohl das KIM-Clientmodul ohne TLS arbeitet. Bei TLS sollte der verwendete Hostname zum Zertifikat des KIM-Clientmoduls passen. Verwenden Sie localhost oder 127.0.0.1 nicht, wenn das Clientmodul auf einem anderen System läuft.
certificate_unknown(46) charly vertraut dem vom KIM-Clientmodul präsentierten Zertifikat nicht. Prüfen Sie, ob das richtige CA-Zertifikat beziehungsweise Server-Zertifikat des KIM-Clientmoduls hochgeladen wurde.
Unable to construct a valid chain oder Unable to find certificate chain Die Zertifikatskette ist unvollständig oder es wurde das falsche Zertifikat hochgeladen. Häufig fehlt ein Intermediate-Zertifikat oder es wurde nur ein Einzelzertifikat statt der für das KIM-Clientmodul benötigten Vertrauenskette verwendet.
TLS mit Client-Authentifizierung ist im KIM-Clientmodul aktiviert, in charly aber kein Clientzertifikat hinterlegt Die Verbindung kann trotz korrekter Host- und Portdaten scheitern. Hinterlegen Sie in charly das passende Clientzertifikat im Format .p12.
In charly ist ein Clientzertifikat hinterlegt, das KIM-Clientmodul erwartet aber keine Client-Authentifizierung oder ein anderes Zertifikat Die TLS-Konfiguration passt auf beiden Seiten nicht zusammen. Stimmen Sie Konfiguration und Zertifikate in charly und im KIM-Clientmodul aufeinander ab.
Das Clientzertifikat lässt sich hochladen, funktioniert aber nicht Prüfen Sie, ob die Datei den privaten Schlüssel enthält. Ein reines Zertifikat ohne privaten Schlüssel reicht für die Client-Authentifizierung nicht aus.