AqBanking und AqHBCI sind eine Familie von OpenSource-Bibliotheken, die Online-Banking-Funktionen anbieten. AqBanking und AqHBCI gemeinsam ergeben eine Implementierung des deutschen Online-Banking-Protokolls HBCI.

Inhalt

1. Einleitung

AqBanking ist eine freie Open Source Bibliothek für Finanzanwendungen, geschrieben von Martin Preuss in der Programmiersprache C. Es lässt sich sowohl auf Linux, den BSD-Systemen, MacOSX und Windows/MinGW kompilieren.

• Aktuelle stabile Version aqbanking: Siehe http://www.aqbanking.de

• Aktuelle stabile Version gwenhywfar: Siehe http://www.aqbanking.de

Die Information auf dem Rest dieser Wiki-Seite beziehen sich maximal auf aqbanking-2.6.1 (veröffentlicht 8.7.2007) und gwenhywfar-2.3.2 (veröffentlicht 8.7.2007); seitdem ist der Text praktisch nicht mehr aktualisiert worden.

AqBanking wird bereits von wichtigen Anwendungen verwendet, darunter GnuCash, Pecunia QBankManager und KMyMoney2 (bisher nur Umsatzabruf).

Seit April 2010 gibt es außerdem die Anwendung AqFinance (siehe http://www2.aquamaniac.de/sites/aqfinance/index.php), welche immer die jeweils aktuellsten Versionen der AqBanking-Familie enthaelt. Diese Anwendung laeuft unter Linux, Windows und MacOSX und wird mit einem grafischen Installer ausgeliefert. Die Linux-Version kann außerdem im laufenden Betrieb auf die jeweils neueste Version aktualisiert werden.

Die AqBanking-Familie ist der Nachfolger von OpenHBCI. Das gleiche Autorenteam hat sich zu diesem Umstieg entschlossen, da in der AqBanking-Familie ein größerer Funktionsumfang und eine breitere Verwendungsmöglichkeit realisiert werden konnte. Die Weiterentwicklung von OpenHBCI wurde daher im Laufe des Jahres 2004 eingestellt. Das Know-How der Autoren ist nun hier in AqBanking zu finden.

2. Kontakt

2.1. Homepages

• http://www.aqbanking.de/ Homepage des Haupt-Entwicklers

2.2. Mailinglisten

• Für Fragen zu AqBanking kann die Mailingliste http://lists.aqbanking.de/cgi-bin/mailman/listinfo/aqbanking-user genutzt werden. Zusätzliches Archiv auch auf http://dir.gmane.org/gmane.comp.finance.aqbanking.devel .

(Die Mailingliste ist "subscriber-only", um Spam zu vermeiden.)

3. Bestandteile von AqBanking

AqBanking besteht aus mehreren Anteilen:

3.1. Onlinebanking

AqBanking bietet eine generelle API für im Onlinebanking übliche Aufträge (Umsatzabruf, Kontostände abfragen, Überweisungen, Lastschriften etc). Diese Aufträge werden dabei nicht von AqBanking selber ausgeführt, sondern von Banking-Modulen. Das in Deutschland wichtigste Modul ist AqHBCI.

3.2. Importer/Exporter

Die Bibliothek enthält bereits einige Im-/Exporter für gebräuchliche Dateiformate:

• SWIFT
• CSV (vollständig Benutzer-definierbar)
• DTAUS
• OpenHBCI1-Format
• ERI (in den Niederlanden verwendetes Format)
• OFX/OFC
• Q43 (in Spanien gebraeuchliches Dateiformat)

3.3. Banken- und Länderinformationen

AqBanking enthält eine Datenbank mit finanzbezogenen Informationen über verschiedene Länder:

• internationaler und lokaler Name des Landes
• internationaler und lokaler Name der Währung
• ISO-4217 Code der Währung

• ISO-3166-1 numerischer Code des Landes (z.B. 280 für Deutschland)

• ISO-3166-1 zwei-Zeichencode des Landes (z.B. DE für Deutschland)

AqBanking enthält außerdem Informationen zu den Banken verschiedener Länder, derzeit:

• ca 20.000 deutsche Banken (inclusive HBCI-Server-Adressen der meisten Banken)
• ca 25.000 US-Banken (inclusive OFX-Server-Adressen einiger Banken)
• ca 3.600 Schweizer Banken
• ca 2.300 österreichische Banken

Diese Informationen schließen die Bankleitzahl/Bankstammzahl/Routing Number der Bank ein, z.T. den BIC-Code, sowie Namen und teilweise Ort der Bank.

4. Onlinebanking-Module

AqBanking liefert alle derzeit verfügbaren Module mit.

4.1. HBCI

HBCI ist das deutsche Homebanking-Computerinterface. Dieses Protokoll wird von den meisten deutschen Banken unterstützt. Dieses Modul unterstützt mehrere Sicherheitsmedien:

• Selbsterzeugte Schlüsseldateien von AqBanking und OpenHBCI werden unterstützt (sogenannter RDH-Modus) (Allerdings können Schlüsseldateien, die von AqBanking neu erstellt wurden, nur von der allerletzten OpenHBCI-Version 0.9.18 gelesen werden, und auch das nur bei neu erstellten Schlüsseldateien bis aqbanking-1.2.x, siehe hier. Anders herum ist die gleichzeitige Verwendung aber weiterhin möglich, also die von OpenHBCI erstellten Schlüsseldateien von AqBanking und OpenHBCI abwechselnd zu verwenden).

• PIN/TAN wird unterstützt.
• DDV-Chipkarten werden unterstützt.
• RSA-Chipkarten werden unterstützt

• Proprietäre Schlüsseldateien (Schlüsseldisketten) von Software anderer Hersteller (z.B. Quicken, Moneyplex) werden dagegen nicht unterstützt. In dieser Bibliothek werden die HBCI-Versionen 2.01, 2.1 und teilweise 2.2 unterstützt.

4.2. EBICS

EBICS ist ebenfalls ein deutsches Online-Banking-Protokoll, welches im Gegensatz zu HBCI vor allem im professionellen Bereich eingesetzt wird. Seit AqBanking4 ist eine Version des Programms AqBanking-CLI mit EBICS-Unterstützung erhältlich.

4.3. OFX DirectConnect

Dieses Protokoll wird vor allem in den USA und Kanada sowie offenbar im Vereinigten Königreich verwendet.

Eine Anleitung zur Einrichtung ist auf Englisch hier zu finden.

5. Installation

5.1. Aktuelle Version

Sofern man in irgendeiner der obengenannten Anwendungen AqBanking verwenden will, braucht man seit aqbanking-1.3.0 folgende Pakete in dieser Reihenfolge:

1. gwenhywfar

2. ktoblzcheck

3. optional für Chipkarten: LibChipCard

4. aqbanking

(Hinweis: Bitte anhand des Veröffentlichungdatums kontrollieren, dass die heruntergeladenen Versionen ungefähr zur selben Zeit veröffentlicht worden sind. Andernfalls bestehen ggf. subtile Inkompatibilitäten.)

Darüber hinaus sind keine weitere Pakete notwendig; alle möglicherweise optionalen Teile können beim Installieren von AqBanking mit den configure-Optionen --with-backends (für die Backend-Module, die auf die Bank-Server zugreifen) und --with-frontends (für die verschiedenen Schnittstellen zu den Anwendungen) ausgewählt werden. In der Voreinstellung wird AqBanking alle optionalen Teile installieren. Mögliche Argumente, wenn man nur HBCI und GnuCash verwenden will, wären dann:

./configure --with-backends=aqhbci --with-frontends="cbanking qbanking"

Wenn man dagegen z.B. KMyMoney mit HBCI und OFX-Direct-Connect verwenden will, könnte man folgendes angeben:

./configure --with-backends="aqhbci aqofxconnect" --with-frontends="cbanking qbanking kbanking"

Im Einzelnen werden folgende Backends mitgeliefert:

Und folgende Frontends (wobei mit "frontend" nur die Schnittstelle zu den tatsächlichen Anwendungen gemeint ist, nicht die Anwendungen selber):

(Anmerkung: Bei den instabilen Test-Versionen 2.9.x sind diese Bestandteile nur in Teilen enthalten und insbesondere kein "aqbanking-tool" verfügbar; es ist noch unklar, welche der genannten Module und Programme auch in der endgültigen 3.x Version enthalten sein werden.)

5.2. Schrittweise Installationsanleitung

(Systemunabhängiger Beispielablauf - noch in Arbeit) Zuerst die nötigen Pakete herunterladen:

wget http://switch.dl.sourceforge.net/sourceforge/aqbanking/aqbanking-2.2.0.tar.gz
wget http://surfnet.dl.sourceforge.net/sourceforge/gwenhywfar/gwenhywfar-2.3.1.tar.gz
wget http://puzzle.dl.sourceforge.net/sourceforge/ktoblzcheck/ktoblzcheck-1.11.tar.gz

Dann entpacken und installieren:

tar xfz gwenhywfar-2.3.1.tar.gz
cd gwenhywfar-2.3.1
./configure
make
make install

Wenn beim "configure" eine Fehlermeldung wegen fehlendem libssl oder libcrypto auftaucht: Das distributionseigene "openssl-devel" Paket installieren Dann das Paket zur Überprüfung von KTO und BLZ nummern installieren (hier neueste Version einsetzen):

tar xfz ktoblzcheck-1.11.tar.gz
cd ktoblzcheck-1.11
./configure
make
make install

Und schließlich die eigentliche Bankingsoftware:

tar xfz aqbanking-2.2.0.tar.gz
cd aqbanking-2.2.0
./configure --with-backends="aqhbci" --with-frontends="cbanking"
make
make install

Mit dieser Angabe von Backend und Frontend wird die Minimalversion installiert, nur für Commandline Betrieb. Jetzt mal probeweise aqbank<tab> eingeben, und wenn z.B. aqbanking-tool abgeboten wird, hat vermutlich alles geklappt.

6. Benutzung Kommandozeilen-Tools

6.1. aqbanking-tool

Ab aqbanking-1.2.0 existiert ein Kommandozeilen-Tool für einfache Online-Banking-Aufträge. Dieses Tool ist im Tarball von aqbanking enthalten.

Zur Dokumentation lese man das README im Verzeichnis src/tools/aqbanking-tools/ des Tarballs. Eine etwas ältere Kopie kann man hier ansehen

Zusätzlich dazu findet sich unter http://openlab.radion.org/lab/Konsolenbasiertes_Online_Banking_mit_Linux noch ein detailiertes HOWTO, welches alle Schritte, Optionen und weitere Möglichkeiten einfach darstellt.

6.2. Wie benutzt man das aqhbci-tool

Ab aqbanking-1.3.0 existiert ein Kommandozeilen-Tool für die Einrichtung des AqHBCI-Zugangs. Dieses Tool ist im Tarball von aqbanking enthalten.

Für dieses Tool gibt es eine eigene Wiki-Seite unter AqBanking/aqhbci-tool.

Ab da kann man dann bei erfolgreichem Ablauf das aqbanking-tool verwenden (siehe Abschnitt oben).

7. Fragen und Antworten

Längere Fragen sollten bitte auf der Mailingliste zum Projekt gestellt werden. Bis auf weiteres wird hierfür noch immer die Mailingliste des AqBanking-Projektes verwendet: http://lists.aqbanking.de/cgi-bin/mailman/listinfo/aqbanking-user Auf dieser Seite können gerne kurze Fragen gesammelt werden, aber Logfiles etc. sollten zuerst auf der Mailingliste diskutiert werden. Danke.

7.1. Abfrage der Kennung beim Einrichten scheitert an einem Syntax-Fehler

Wer bei der Einrichtung beim Abfragen der Systemkennung Probleme nach Eingabe der PIN hat, sollte sich vergewissern, dass er eine PIN mit korrekter Länge verwendet. Zumindest das Web-Interface der DKB akzeptiert bei der Anmeldung eine PIN mit 6 Zeichen, obwohl nur 5 ausgewertet werden. Versucht man mit dieser 6-stelligen PIN eine Anmeldung beim HBCI-Server, wird diese abgelehnt und im Log erscheint ein "9140 - Syntaxfehler" in folgendem Zusammenhang:

15:38:26 HTTP-Status: 200 OK
15:38:27 Response received
15:38:27 HBCI: 9010 - Nachricht ist komplett nicht bearbeitet. (M)
15:38:27 HBCI: 9110 - Unbekannter Aufbau. (M)
15:38:27 HBCI: 9800 - Dialog abgebrochen. (M)
15:38:27 HBCI: 9140 - Syntaxfehler. (S)
15:38:27 Dialog aborted by server

Die Anmeldung mit der 5-stelligen PIN behebt den Fehler.

Das selbe Problem hat man u.a. auch bei der DiBa mit längeren PINs, hier bekommt man aber die Fehlermeldung, dass die Antwort nicht kodiert werden kann. Seit 27. Oktober 2007 ist das Problem in der neuesten aqhbci-Version aber wohl behoben (lt Beitrag von Martin Preuss in Aqbanking-devel).

7.2. 9210 DTA-Berechtigung fehlt

Beim Absenden von Überweisungs- oder Lastschriftaufträgen kommt die Fehlermeldung HBCI: 9210 - DTA-Berechtigung fehlt (S). Was tun?

AqBanking bietet die Wahlmöglichkeit, ob Aufträge entweder als Einzelaufträge (teurer) oder als Sammelaufträge (billiger, aber weniger Details im Kontoauszug) eingereicht werden. Diese Fehlermeldung besagt, dass man Sammelaufträge eingereicht hat, aber die Bank nur Einzelaufträge akzeptiert. Abhilfe steht im folgenden Abschnitt, "Sammelüberweisung statt Einzelüberweisung".

7.3. Sammelüberweisung statt Einzelüberweisung

AqBanking bietet die Wahlmöglichkeit, ob Aufträge entweder als Einzelaufträge (teurer) oder als Sammelaufträge (billiger, aber weniger Details im Kontoauszug) eingereicht werden. Die Sammelüberweisungen / Sammelaufträge sind als Voreinstellung gesetzt. Wenn man das auf die andere Möglichkeit umstellen will, geht das so:

1. Im Konfigurationsmanager durchklicken zu "Konto/Ändern/HBCI" und dort "Einzelüberweisung statt Sammelüberweisung bevorzugen" markieren.

2. Oder in der Datei ~/.banking/settings.conf im Abschnitt für das entsprechende Konto: provider { [...] zu den AccountFlags "preferSingleTransfer" hinzufuegen (also char AccountFlags="preferSingleTransfer" setzen).

Ersteres ist eher empfohlen, da sich das Format der Konfigurationsdatei aendern kann. -- MartinPreuss 2006-01-20 14:53:00

In älteren Versionen (vor 1.9.0):

1. Entweder In der Datei ~/.banking/backends/aqhbci/settings.conf im Abschnitt für die entsprechende Bank und den entspr. Benutzer: customer { [...] den Wert int preferSingleTransfer="0" auf int preferSingleTransfer="1" ändern.

   • Zur Pfadangabe der Konfigurationsdatei: Seit aqbanking-1.9.1 wird nicht mehr eine backend-spezische settings.conf verwendet. Stattdessen werden alle Einstellungen, auch für alle backends, aussschließlich in der einzigen Datei ~/.banking/settings.conf gespeichert. Die settings.conf unterhalb von .banking/backends/*/ können also gelöscht bzw. umbenannt werden, um keine Mehrdeutigkeiten mehr aufkommen zu lassen. -- ChristianStimming 2007-01-18 12:05:35

2. Alternativ im Konfigurationsassistenten durchklicken zu "Users"/"Benutzer" -> <user wählen> -> "Expert Actions"/"Experten-Aktionen" -> "Edit"/"Bearbeiten" -> <Customer/Kunde wählen> -> | "Edit"/"Bearbeiten" -> "Prefer single Transactions over multi transfers"/"Einzelüberweisung anstelle Sammelüberweisung bevorzugen" aktivieren. -- ChristianStimming 2005-10-11 08:11:20

7.4. Antwort konnte nicht kodiert werden: Umlaute im Verzeichnispfad

Bei Aqbanking mit HBCI und Schlüsseldatei hatte jemand das Problem, schon bei der Abfrage der Kontenliste nur die Fehlermeldung "Antwort konnte nicht kodiert werden" zu bekommen. Auf der Konsole standen folgende Fehlermeldungen:

3:2006/08/11 10-15-53:gwen(27317):fslock.c: 114: open(/bla/bla/Aq_voba_12345.key.lck): Datei oder Verzeichnis nicht gefunden
3:2006/08/11 10-15-53:gwen(27317):ct_file.c: 364: Could not lock file
3:2006/08/11 10-15-53:aqhbci(27317):medium.c: 396: Could not open crypt token (-70)
3:2006/08/11 10-15-53:aqhbci(27317):hbci.c: 515: Could not mount medium (-21)
3:2006/08/11 10-15-53:aqhbci(27317):jobqueue.c: 426: Could not encode message (-21)

Es stellte sich heraus, dass das Problem daran lag, dass die Schlüsseldatei in einem Verzeichnis mit Umlauten im Verzeichnisnamen lag. Problembehebung: Schlüsseldatei in einem Verzeichnispfad ohne Umlaute abspeichern.

7.5. Neue HBCI-Karte verwenden

Alle paar Jahre wird eine HBCI-Schlüsselkarte ungültig und muss durch eine neue ersetzt werden. AqBanking (das u.a. auch von GnuCash verwendet wird) ist darauf noch nicht eingerichtet; bis dahin muss die Löschung der alten Karte von Hand in der entsprechenden Konfigurationsdatei vorgenommen werden. Das geht so:

1. Datei ~/.banking/settings.conf sichern (z.B. mit cp settings.conf settings.conf.bak)

2. Datei ~/.banking/settings.conf in einem Texteditor öffnen

3. Innerhalb des Abschnitts media{ ... }  sollten sich ein oder mehrere medium{ ... }  finden. Dort das richtige medium{}  identifizieren und die Zeile mit der Variable "mediumName" suchen. Der Wert der Variable sollte der Kartennummer entsprechen. Die Kartennummer muss durch die Nummer der neuen Karte ersetzt werden, führende Nullen im alten Variablenwert müssen wieder übernommen werden.

4. AqBanking sollte jetzt in der Lage sein die neue Karte zu verwenden. Wenn nicht sollte die Datei ~/.banking/settings.conf sicherheitshalber wieder mit der Sicherungskopie überschrieben werden und anderweitig Hilfe gesucht werden, z.B. auf der AqBanking Mailingliste (siehe Punkt 2.2).

7.6. Benutzer löschen

Im HBCI-Einrichtungsassistent war für längere Zeit der Knopf "Benutzer löschen" noch nicht implementiert (ist jetzt aber verfügbar seit aqbanking-2.2.9). Bis dahin musste die Löschung eines überflüssigen Benutzers in der entsprechenden Konfigurationsdatei vorgenommen werden. Das geht so:

1. Datei ~/.banking/settings.conf sichern (z.B. mit cp settings.conf settings.conf.bak)

2. Datei ~/.banking/settings.conf in einem Texteditor öffnen

3. Innerhalb des Abschnitts users{ ... }  sollten sich mehrere user{ ... }  finden. Dort den richtigen user{}  identifizieren und den Abschnitt ersatzlos entfernen.

4. Beim nächsten Start des HBCI-Einrichtungsassistent sollte der überflüssige Benutzer dann verschwunden sein.

7.7. HBCI über einen Proxy

Frage: Wie kann man HBCI mit aqbanking über einen Proxy benutzen? Antwort: In AqBanking selber ist das bisher nicht implementiert; es gibt aber Anleitungen, wie man das mit einem kleinen Hilfsprogramm trotzdem einrichten könnte. Siehe http://lists.gnucash.org/pipermail/gnucash-de/2006-January/003764.html und http://lists.gnucash.org/pipermail/gnucash-de/2005-July/003170.html .