HBCI4Java - Open-Source HBCI-Client- und Server-Bibliothek für Java

Was ist HBCI4Java

HBCI4Java ist eine freie Open-Source-Bibliothek für die Entwicklung von HBCI-fähigen Client-Anwendungen in Java. Die Software ist unter der GPL lizensiert.

HBCI4Java-Server ist ein Framework (ebenfalls Open-Source) für die Entwicklung eines eigenen HBCI-Servers. Es implementiert bereits einen Großteil des eigentlichen HBCI-Protokolles, ein "eigener HBCI-Server" muss prinzipiell nur noch die Daten zur Laufzeit bereitstellen und auf eingehende Aufträge reagieren. Auch das Server-Framework ist (ebenso wie der schon enthaltene Demo-Server) unter der GPL lizensiert und steht damit nicht ohne weiteres für die Entwicklung kommerzieller Produkte zur Verfügung.

Die HBCI4Java-Komponenten wurden (fast) vollständig in Java entwickelt. Aus diesem Grund lassen sich mit diesen Bibliotheken plattformunabhängige HBCI-Client- und -Server-Anwendungen implementieren.

Features

Es folgt der Inhalt der Datei FEATURES aus den HBCI4Java-Archiven:

* Unterstützung der Version HBCI-2.01 bis HBCI-2.2 sowie FinTS-3.0

* Unterstützung von dateibasiertem RDH-Verfahren, PIN/TAN-Verfahren (seit 
  FinTS-3.0 auch das Zweischritt-Verfahren) und chipkartenbasierten DDV-
  Verfahren, dabei Unterstützung von Kartentypen 0 und 1, Chipkartenleser 
  Klassen 1-3 (benötigt CTAPI-Treiber) sowie Biometrieeinheit (nur Reiner-SCT)

* Unterstützung von SIZ-RDH-Schlüsseldateien und RDH-2-Schlüsseldateien
  (StarMoney, GENOlite, VR-Networld, ProfiCash, ...)
  
* direkte Unterstützung von OpenHBCI-Schlüsseldateien für RDH-Zugänge

* Unterstützung der folgenden HBCI-Geschäftsvorfälle:
  - Einzelüberweisungen
    . normale (Ueb)
    . Umbuchung (Umb)
    . Spendenüberweisungen (Donation)
    . BZÜ-Überweisungen (UebBZU)
  - Auslandsüberweisungen
  - Sammelüberweisungen (MultiUeb),
    Sammellastschriften (MultiLast)
    (jeweils HBCI4Java-eigener DTAUS-Generator vorhanden)
  - Verwalten von terminierten Überweisungen
    . einreichen (TermUeb), auflisten (TermUebList), 
      bearbeiten (TermUebEdit) und löschen (TermUebDel)
  - Verwalten von Daueraufträgen
    . einreichen (DauerNew), auflisten (DauerList), 
      bearbeiten (DauerEdit) und löschen (DauerDel)
  - Einreichen von Lastschriften (Last)
  - Widerrufen von Lastschriften (StornoLast)
  - Verwalten von Festgeldanlagen
    . zur Zeit nur Abfrage von Konditionen (FestCondList) und Auflisten von
      bestehenden Festgeldanlagen (FestList[All])
  - Abfrage von Kontoinformationen
    . Saldenabfragen (SaldoReq[All])
    . Abholen von Umsatzinformationen (Kontoauszug) (KUms[All|New])
    . Abholen von Kontostammdaten (AccInfo)
    . Abholen von Informationen zu ausgegebenen Karten (Cardlist)
  - Abholen und Senden verschiedener Informationen und Nachrichten
    (CustomMsg, InfoList, InfoOrder)
  - Auswertung des bankinternen Statusprotokolls (Status)
  - Anzeigen von Informationen zu TAN-Listen (nur bei PIN/TAN-Verfahren)
    (TANList)
  - Abholen von Wertpapierdepot-Informationen (WPDepotList)
  
  - es werden u.U. einige weitere Geschäftsvorfälle unterstützt, für die 
    zur Zeit noch keine Highlevel-Unterstützung implementiert ist, 
    aber als Lowlevel-GVs lassen sich diese benutzen

* Erzeugen von Aufträgen:
  - Lowlevel-Interface: *schnelles* Implementieren neuer GVs möglich,
    starke Kontrolle über alle GV-Parameter und Ergebnisdaten
  - Highlevel-Interface: anwendungsorientierte Schnittstelle zum
    Erzeugen von Aufträgen und zum Auswerten von Ergebnisdaten

* einfacher Zugriff auf Job-bezogene Statusinformationen einer
  HBCI-Antwortnachricht

* einfache Identifizierung von erzeugten Aufträgen und überprüfen
  deren Status' im Statusprotokoll

* Zuordnung von Bankleitzahlen zu Kreditinstituts-Bezeichnungen

* diverse Tools zum Auslesen/Bearbeiten der DDV-Chipkarte, zum Erzeugen
  eines INI-Briefes, zum Bearbeiten der Passports (Sicherheitsmedien), usw.
  
* Batch-Tool für automatisierte Abarbeitung von HBCI-Jobs, die in einer
  Textdatei definiert werden können

* Schlüsselverwaltung:
  - Sperren von Nutzerschlüsseln
  - Neugenerieren von Nutzerschlüsseln
  - Setzen von Nutzerschlüsseln auf vorgegebene Werte 

* dynamisches Ändern von Kernel-Parametern zur Laufzeit

* verfolgen der HBCI-Kernel-Aktivitäten durch Callbacks möglich 

* dynamische Anpassungen an HBCI-Server mit "Fehlern" in der 
  Implementation des HBCI-Standards

* Callback-Mechanismus für die Kommunikation zwischen HBCI-Kernel
  und Anwendung, um unabhängig von der Laufzeitumgebung (Applikation,
  Servlet, Applet, mit oder ohne GUI usw.) zu sein
  
* Möglichkeit, bestimmte von HBCI4Java erkannte Fehler im HBCI-Dialog
  zu ignorieren (für die Entwicklungsphase von Anwendungen)
  
* Demo-Applet bzw. Java WebStart Anwendung verfügbar

* Einsatz in multithreaded Anwendungen möglich


* automatische Auswertung der BPD:
  - automatisches Benutzen der jeweils höchsten unterstützten
    Version eines Geschäftsvorfalls
  - automatisches Erzeugen zusätzlicher Nachrichten, wenn max.
    Anzahl von GVs pro Nachricht überschritten wird
  - automatisches Überprüfen, ob bestimmte Einschränkungen bzgl.
    eines zu erzeugenden Auftrages eingehalten wurden
  - automatisches Erkennen, ob ein bestimmter Geschäftsvorfall
    von der Bank überhaupt angeboten wird
  - bei PIN/TAN-Verfahren: automatische Erkennung von Geschäftsvorfällen,
    die eine TAN benötigen

* automatisches Überprüfen der verwendeten Kontonummern anhand
  der für die jeweilige Bank zu verwendenden Prüfzifferverfahren 

* automatisches Aktualisieren der BPD und UPD beim Wechsel der 
  für die Dialoge benutzten HBCI-Version

* automatisches Konvertieren und Parsen von Datums- und Zeitangaben
  in bzw. von Locale-spezifischen Formaten

* für jedes Sicherheitsmedium wird optional automatisch die damit zuletzt 
  benutzte HBCI-Version verwendet  

* passwortgeschützte Sicherheitsmedien

* Speichern von (geänderten) Zugangsdaten auf der Chipkarte 
  (für DDV-Passports) möglich (wird teilweise für Initialisierung
  der Benutzerkennung benötigt)

* sauberes Fehlerbehandlungs- und Status-System

* Erzeugen noch nicht existierender bzw. Initialisieren nicht 
  initialisierter Sicherheitsmedien (=Passports) zur Laufzeit und 
  ohne zusätzlichen Programmcode innerhalb der HBCI-Anwendung
  (Beispiel siehe org.kapott.hbci.tools.AnalyzeReportOfTransactions)

* automatisches Erzeugen zusätzlicher HBCI-Nachrichten, wenn
  in einer Antwortnachricht nicht alle verfügbaren Antwortdaten
  enthalten sind --> Abholen der restlichen Daten

* völlig automatisches Aktualisieren von BPD, UPD und Institutsschlüsseln

--- Details der Implementation von HBCI4Java

* lauffähig auf allen Plattformen mit Java Runtime Environment 1.4+,
  für Chipkartensupport wird zusätzlich Unterstützung von dynamischen
  Bibliotheken benötigt.

* austauschbare integrierte HBCI-Spezifikation (XML-Format),
  damit leicht Anpassung an neue Versionen bzw. Debugging möglich
  
* I18N-Support für Deutsch und Englisch (noch nicht für alle Texte)

* modulares System für folgende Komponenten, ermöglicht einfaches
  Hinzufügen weiterer Module:
  - Kommunikationspfade (Standard-HBCI, PIN/TAN (HTTPS))
  - Kommunikationsfilter (Base64)
  - Datentypen für Datenelemente
  - Highlevel-Support für Geschäftsvorfälle
  - intern verwendete HBCI-Spezifikation
  - Sicherheitsmedien (=Passports: RDH mit Datei, DDV mit Chipkarte,
    PIN/TAN mit Datei)
  - Module für Anpassung an "fehlerhafte" HBCI-Server

Einsatzmöglichkeiten

Leider wird HBCI oft nur als eine Alternative für das Homebanking angesehen, welches viele Banken auch über ein Web-Frontend oder mit Hilfe proprietärer Software anbieten. Doch mit HBCI lassen sich viel weitergehende Anwendungen realisieren:

Viele Banken ermöglichen es ihren Kunden, über ein Web-Frontend Bankgeschäfte abzuwickeln ("Electronic Banking" oder "Internet Banking"). Dieser Vorgang kann auch mit HBCI realisiert werden (z.B. über ein Java-Applet oder über einen Java-WebStart-Client). Damit würde die Entwicklung der zusätzlichen Schnittstelle WebServer - BankBackendSysteme entfallen, weil alle geschäftlichen Transaktionen über die (schon vorhandene) HBCI-Schnittstelle einlaufen würden.
Einsatz als Bezahlsystem, wie es im z.B. Online-Handel benötigt wird. Zurzeit gibt es eine ganze Reihe Bezahlsysteme auf dem Markt. Bei der Integration solcher Bezahlsysteme in einen Online-Shop treten oft Probleme auf. Mit HBCI4Java steht eine Schnittstelle zu einem weiteren Bezahlsystem zur Verfügung, welches sich sehr gut in verschiedenen Systemen benutzen lässt.

Dieses Bezahlsystem kam bereits in der Java-basierten Online-Bibliothek eVerlage zum Einsatz, was auch auf der CeBIT 2002 und CeBIT 2003 vorgestellt wurde. Das eVerlage-Projekt gibt es leider nicht mehr, auf den Seiten von Berlios wird aber an einer Neuauflage als Open-Source-Projekt gearbeitet.

Für weitere Informationen zum Thema "HBCI als Bezahlsystem" eine Email an hbci4payment@kapott.org schicken.
Einsatz in Finanz-Software (Finanzbuchhaltung, Haushaltplaner, Abrechnungssysteme, usw.): Allein durch die Integration der beiden HBCI-Geschäftsvorfälle Überweisung und Kontoauszug abholen lässt sich die Arbeit mit dieser Software-Kategorie stark vereinfachen. Fällige Zahlungen müssen nicht mehr manuell bzw. mit Hilfe einer zusätzlichen Software ausgelöst werden, statt dessen kann diese Funktionalität direkt integriert werden. Auch der Import von Daten aus Kontoauszügen muss nicht mehr über separate Softwareprodukte bzw. gar von Hand erfolgen, sondern kann durch den Einsatz von HBCI vereinfacht werden.

Da HBCI noch viel mehr Geschäftsvorfälle als diese beiden ermöglicht, ist die Funktionsvielfalt (fast) nur durch die Kreativität des Entwicklers beschränkt.

Viele Anwendungen aus diesem Bereich geben bereits vor, electronic Banking zu unterstützen. In der Regel bedeutet das lediglich, dass diese Anwendungen Daten erzeugen und importieren können, die mit einer Dritt-Software (meist eine proprietäre Software von der eigenen Bank) mit der Bank ausgetauscht werden müssen. Eine direkte Integration von HBCI-Funktionen in diese Software-Kategorie kann zu erheblichen Effizienzsteigerungen bei der Arbeit mit dieser Software bedeuten.

Gerade die Realisierung als Software-Bibliothek ohne bereits fest integrierten Code für die Interaktion mit dem Anwender ermöglicht auch den Einsatz in nicht-interaktiven Systemen (Backend-Systeme von WebShops, automatisierte Abrechnungssysteme usw.).
Neuere HBCI-Versionen ermöglichen auch die Abwicklung von Wertpapiergeschäften. Damit lässt sich also auch speziell auf dieses Gebiet orientierte Software entwickeln. Der Vorteil der Verwendung von HBCI ist weiterhin, dass diese Software nicht auf eine spezielle Bank (oder Broker) zugeschnitten werden muss.
HBCI4Java enthält zusätzlich das Framework für einen eigenen HBCI-Server (ebenfalls als Software-Bibliothek realisiert). Außer den Vorteilen, die ein eigener HBCI-Server für Entwickler von HBCI-Software bietet, können damit auch völlig andere Systeme realisiert werden, die eine schon vorhandene HBCI-Infrastruktur nutzen (z.B. eine Nutzerauthentifikation mit Hilfe von HBCI-Schlüsseln).
Durch die freie Verfügbarkeit von HBCI4Java lassen sich viele Anwendungen, die es nur als kommerzielle Produkte gibt, auch als plattformunabhängige Open-Source-Lösungen realisieren.

Status

Zur Zeit ist folgender Entwicklungsstand erreicht:

Implementation vollständig in Java - mit Ausnahme eines kleinen Teils zum Ansprechen des Chipkartenterminals sowie für das Laden und Speichern von SIZ-RDH-Schlüsseldateien in C++. Der Zugriff auf Chipkarten kann inzwischen auch über das javabasierte OpenCard-Framework abgewickelt werden.
Vollständige Implementierung des HBCI-Protokoll-Frameworks
Unterstützung der Sicherheitsverfahren
- RDH-1 und RDH-2 (asymmetrische Schlüssel) auf dem Medium "Datei"
- DDV-1 (symmetrische Schlüssel) auf dem Medium "Chipkarte" (Typ 0 und 1)
- PIN/TAN (Erweiterung von HBCI 2.2 in Richtung FinTS 3.0)
- PIN/TAN (FinTS-3.0) inklusive Zweischritt-Verfahren (iTAN, Sm@art TAN plus, mobileTAN, smsTAN, usw.)
Unterstützung aller Chipkartenleser (Klassen 1, 2 und 3), für die eine CTAPI-Treiber- bibliothek oder ein PC/SC-Treiber für die Zielplattform verfügbar ist.
Unterstützung der Schlüsseldateiformate des SIZ bzw. RDH-2 (StarMoney, GENOlite, VR-NetWorld, ProfiCash usw.) sowie des (alten) OpenHBCI-Formates
Unterstützung der meisten o.g. Geschäftsvorfälle (z.Zt. außer Wertpapiergeschäft) in den HBCI-Versionen 2.01, 2.1, 2.2, HBCIplus sowie FinTS 3.0
multiuserfähig, d.h. der Kernel kann von mehreren Clients gleichzeitig benutzt werden, ein Client kann auch gleichzeit mehrere HBCI-Verbindungen (zu mehreren Banken) benutzen
Fertiges Framework zur Implementation eines entsprechenden HBCI-Servers, Referenzimplementation für einen HBCI-Server enthalten
Client-API wurde sehr stark in Richtung Geschäftsverkehr abstrahiert, so dass keinerlei Kenntnisse über das zugrunde liegende Protokoll (HBCI) nötig sind, um diese Bibliothek zu benutzen
Es steht ein interaktiver Editor für die Bearbeitung der Passports (=Schlüsseldateien) zur Verfügung.
Für eine Liste der unterstützten Geschäftsvorfälle siehe Sektion Features.

Dokumentation

NEU! Inzwischen steht auch wallstreet9 als Demo-Applet zur Verfügung. Die neueste Version von wallstreet9 lässt sich inzwischen sowohl als Standalone-Anwendung starten (Download in der Download-Area) als auch als Applet einbinden.

An dieser Stelle sei auf die API-Dokumentation verwiesen, die auch eine Beschreibung für die Benutzung von HBCI4Java enthält. Diese API-Dokumentation bezieht sich auf die Snapshots, die in der Download-Sektion zu haben sind. Die Dokumentation zu den jeweiligen "offiziellen" Releases sind in den Paketen selbst enthalten.

Es folgen einige Informationen zu den Interna von HBCI4Java:

Folgende Teile der Umsetzung der Spezifikation wurden als austauschbare/nachladbare Module realisiert:
- Sicherheitsmechanismen (DDV, RDH, PIN/TAN, Schlüsseldateien von Drittsoftware) - dadurch kann leicht Unterstützung für weitere Sicherheitsverfahren hinzugefügt werden, ohne dass davon andere Codeteile betroffen sind
- Kommunikationspfade (zur Zeit Client/Server via TCP/IP und HTTP/SSL für PIN/TAN) - damit ist es möglich, sehr einfach zusätzliche Kommunikationspfade zu implementieren. Das wird besonders interessant, da in einer der nächsten Spezifikationen von FinTS auch andere Kommunikationsverfahren (z.B. via Email oder durch Tunnelung über andere Protokolle) möglich sein sollen.
- Engine zum Generieren und Parsen von HBCI-Nachrichten - die eigentliche Syntax-Definition der HBCI-Nachrichten ist über alle HBCI-Versionen im wesentlichen gleich, so dass hier eine einzige Engine benutzt wird. Diese ist trotzdem als eine Art PlugIn realisiert, da in kommenden Versionen des Standards die "Nachrichtensyntax" komplett auf XML umgestellt werden soll.
- Spezifikation der einzelnen HBCI-Versionen - die Beschreibungen der einzelnen HBCI-Versionen liegen intern als XML-Syntaxbeschreibung vor, wobei es für jede HBCI-Version genau eine solche XML-Spezifikation gibt.
  
  Da in allen HBCI-Versionen prinzipiell alle möglichen Versionen aller Geschäftsvorfälle unterstützt werden können (das steht zwar bis Version 2.1 so nicht in der Spezifikation, ist aber Praxis), ist die Spezifikation der Geschäftsvorfälle ausgelagert. Nur die Spezifikation der administrativen Teile ist tatsächlich für jede HBCI-Version separat vorhanden.
  
  Der HBCI-Kernel benutzt nur die XML-Syntaxbeschreibung zum Generieren und Analysieren von Nachrichten. Damit ist er völlig versionsunabhängig, und es können sehr einfach neue HBCI-Versionen unterstützt werden.
- FrontEnd-Klassen für Geschäftsvorfälle - Für viele Geschäftsvorfälle existieren sogenannte FrontEnd-Klassen, die die GV-spezifischen Daten so kapseln, dass die HBCI-interne Datenstruktur für den Anwender (=den Entwickler, der HBCI4Java benutzt) nicht mehr sichtbar ist. Der HBCI-Kernel selbst weiß nichts über diese FrontEnd-Klassen, sie werden statt dessen einfach bei Bedarf über den Java-Reflection-Mechanismus benutzt.
  
  Alle Geschäftsvorfälle können prinzipiell auch über ein einheitliches Interface benutzt werden, welches etwas weniger Komfort bietet. Das hat den Nachteil, dass die für diesen GV benötigten Daten bzw. auch die jeweiligen Antwortdaten nicht mehr so anwenderfreundlich "vorgekaut" werden. Der Vorteil ist, dass mit diesem Mechanismus alle Geschäftsvorfälle benutzt werden können, die zumindest in der Syntax-Beschreibung der GVs aufgeführt sind (das Hinzufügen von GV-Syntaxbeschreibungen geht sehr schnell (je nach Komplexität und Versionsvielfalt des GVs zwischen 25 und 150 Zeilen XML-Beschreibung), das Schreiben der FrontEnd-Klassen ist i.d.R. aufwändiger).
  
  Die vom jeweiligen HBCI-Server unterstützten Versionen eines Geschäftsvorfalls werden automatisch vom HBCI-Kernel erkannt und die jeweils neueste für die Nachrichtengenerierung benutzt.
- Module für Anpassung an bestimmte Banken - einige HBCI-Server-Implementationen bzw. einige Banken-Backend-Systeme generieren bzw. erwarten Nachrichten, deren Syntax nicht völlig HBCI-konform ist. Damit solche "Unzulänglichkeiten" nicht direkt im HBCI-Kernel behandelt werden müssen, arbeitet der Kernel immer mit streng HBCI-konformen Nachrichten, die kurz vor dem Versenden bzw. direkt nach dem Empfang durch eine spezielle Pipeline geschickt werden, um die Nachricht an die "Besonderheiten" des jeweils verwendeten HBCI-Servers anzupassen.
- HBCI-Server-Module - da auch ein HBCI-Server im Endeffekt nichts anderes tut als HBCI-Nachrichten zu analysieren und zu generieren wurde der HBCI-Kernel so "allgemein" gehalten, dass damit inzwischen auch eine HBCI-Server-Implementation realisiert wurde. Die dafür benötigten Erweiterungen in der Logik (Erkennung eingehender Nachrichten, Nutzerverwaltung, Callback-Mechanismen zum Anbinden eines Backend-Systems) sind als separate Module zuschaltbar. Durch die Versionsunabhängigkeit des HBCI-Kernels selbst ist auch der HBCI-Server, der diesen Kernel mitbenutzt, relativ unabhängig von der (den) HBCI-Version(en), die er anbieten soll.
  
  Dieser Codeteil ist jetzt öffentlich verfügbar (HBCI4Java-Server)

Ausblick

Folgendes ist für die nächste Zukunft geplant: