Konsolenbasiertes Online Banking mit Linux

From RADION OpenLAB

[edit] Einleitung

"Das ist leider so nicht möglich" - War und ist in den meisten Fällen die Aussage von Banken, wenn es zur Frage der automatisierten Abholung von Kontoauszugszeilen unter Linux kommt. Seit einem Jahr versuche ich eine Lösung zu finden, damit meine Webplattform sich selbständig mit dem Konto verbindet, neue Zahlungen überprüft und in eindeutigen Fällen direkt einer Bestellung zuordnet und die Bestellung freigibt. Ohne menschliche Interaktion. Immer wieder habe ich frustriert aufgegeben und das Problem nach hinten geschoben. Bis ich irgendwann mal einen wirklich interessierten Mitarbeiter der Sparkasse am Telefon hatte ( der wohl auch einen guten Draht zu seiner eigenen IT besitzt ) und ihm mein Problem abermals schilderte. Er hatte zwar auch keine Lösung, versprach mir aber, mal intern nachzuforschen was es da gibt. Und siehe da, ein paar Tage später klingelt mich besagter Mitarbeiter in der S-Bahn wach. "Versuchen sie es doch mal mit GNUCash" - "Hmm", dachte ich. Wieso eigentlich nicht. Die Fährte habe ich damals fallengelassen, weil ich nichts suchte was eine GUI erfordert, sondern scriptbasiert arbeitet. Auf dem Weg zu GNUCash bin ich irgendwann auf AQMoney gestossen, die Backerei von AQMoney lies sich aber aufgrund der "alten" Abhängigkeit zu openHBCI nicht mehr bewerkstelligen. Nach weiteren Recherchen bei openHBCI fand ich endlich AQBanking, den Nachfolger von openHBCI. Denn AQBanking ist tatsächlich die out-of-the-box Lösung für scriptbasiertes, automatisiertes Online-Banking unter Linux.

[edit] Ziele

[edit] Benötigte Software (Quellen)

Zur Realisierung von automatisiertem Online-Banking unter Linux verwenden wir in diesem HOWTO ausschliesslich OpenSource Software. Die folgenden Pakete werden gebraucht um alle Funktionalitäten abbilden zu können :

[edit] Gwenhywfar

[edit] KtoBLZCheck

KtoBLZCheck ist eine kleine Hilfsbibliothek um deutsche Kontonummern und Bankleitzahlen (BLZ) zu überprüfen.

[edit] AqBanking

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.

AqBanking wird bereits von wichtigen Anwendungen verwendet, darunter GnuCash (ab Version 1.8.10), QBankManager, KMyMoney2 (bisher nur Umsatzabruf) und in der Entwicklerversion Grisbi. Dabei wird QBankManager von Martin Preuß, dem AqBanking-Entwickler, alleine geschrieben und dient daher als Referenzimplementation. Zusätzlich läuft QBankManager mit der neuen Qt4-Version sowohl auf Linux/Unix als auch auf Windows. Darüber hinaus bringt AqBanking das aqbanking-tool mit, welches direktes Arbeiten auf der Konsole ermöglicht.

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 in AqBanking zu finden.

[edit] Building

Die 3 heruntergeladenen Archive sollten sich nun unter /usr/local/src befinden und müssen nun entpackt werden.

[edit] Archive entpacken

$ cd /usr/local/src
$ tar xfvz gwenhywfar-2.3.1.tar.gz
$ tar xfvz ktoblzcheck-1.10.tar.gz
$ tar xfvz aqbanking-2.2.0.tar.gz

[edit] Konfiguration und Kompilieren

Die CFLAGS sollten natürlich an das lokale System angepasst werden. Falls Sie nicht wissen, was CFLAGS sind oder wie diese eingesetzt werden, lassen Sie sie bitte einfach weg.

[edit] von GwenHywfar

Gwen dient als Basisbibliothek für AqBanking und wird deshalb als erstes gebacken.

$ cd gwenhywfar-2.3.1/
$ CFLAGS="-mtune=pentium4 -O3 -pipe -fomit-frame-pointer" ./configure --prefix=/usr
$ make -j4
$ make check
$ make install

[edit] von KtoBLZCheck

Die KtoBLZCheck Bibliothek ist zwar nicht zwingend erforderlich, vereinfacht die tägliche Arbeit bei Überweisungen etc. ungemein. Um die ktoblzcheck.h in AqBanking nutzen zu können, muss sie natürlich ebenfalls vor AqBanking kompiliert worden sein.

$ cd ../ktoblzcheck-1.10

$ CFLAGS="-mtune=pentium4 -O3 -pipe -fomit-frame-pointer" ./configure --prefix=/usr
$ make -j4
$ make check
$ make install

[edit] von AqBanking

Nachdem nun alle erforderlichen Abhängigkeiten erfüllt sein sollten kann nun AqBanking konfiguriert und kompiliert werden. Die hier gezeigten Konfigurationsoptionen reichen um Online-Banking auf der Text-Console nutzen zu können. Wer gerne noch zusätzlich die Kde-, Gnome- oder QT-Module backen möchten, kann sich mit ./configure --help alle entsprechenden Konfigurationsparameter ausgeben lassen.

$ cd ../aqbanking-2.2.0
$ CFLAGS="-mtune=pentium4 -O3 -pipe -fomit-frame-pointer" ./configure --prefix=/usr \
  --with-gwen-dir=/usr --with-frontends="cbanking" --with-backends="aqhbci aqdtaus"

$ make -j2
$ make check
$ make install

[edit] Configuration

[edit] HBCI Informationen des Geldinstitutes recherchieren

Unter dem folgenden Link findet man unter Angabe der BLZ die entsprechenden HBCI relevanten Informationen des jeweiligen Geldinstituts.

Die Ausgabe sollte ungefähr so aussehen :

Die wichtigste Info hierbei ist das Feld PIN/TAN URL. Dieser URL wird in Abschnitt 5.2.3 als Server bei der HBCI Konfiguration als Server angegeben.

[edit] AqHBCI mit PIN/TAN für ein Konto einrichten

[edit] Medium in AqHBCI erzeugen

$ aqhbci-tool addmedium -t pintan

[edit] Medien-Nummer herausfinden

$ aqhbci-tool listmedia

Mit diesem Kommando werden die verfügbaren Medien angezeigt. Die Nummer am Anfang der Ausgabe benötigen wir im nächsten Schritt.

[edit] HBCI-Benutzer anlegen

$ aqhbci-tool adduser -m X -s SERVER-ADRESSE -b BANKLEITZAHL -u BENUTZERKENNUNG [-c KUNDENNUMMER]

Das X ist hier nun die Nummer aus dem vorigen Schritt. Die Kundennummer müssen Sie nur angeben, wenn Ihre Bank Ihnen diese ausdrücklich mitgeteilt hat. Andernfalls verwendet AqHBCI dafür intern die Benutzerkennung.

Als Beispiel :

Die Bank ist die Sparkasse Entenhausen - BLZ 66699911 - die Benutzerkennung ist die 012345678 Der listmedia Befehl hat als Medium die 0 ausgegeben.

$ aqhbci-tool adduser -m 0 -s https://hbci-pintan-rl.s-hbci.de/PinTanServlet -b 66699911 -u 012345678

[edit] Systemkennung abrufen

$ aqhbci-tool getsysid [ -c KUNDENNUMMER]

Die Systemkennung dient der Identifikation des von Ihnen verwendeten Programmes und der Benutzerkennung. Ohne diese Kennung funktioniert kein weiterer Schritt.

[edit] Kontenliste abrufen

$ aqhbci-tool getaccounts [ -c KUNDENNUMMER]

Nicht alle Banken unterstützen dieses Kommando. Wichtig ist hierbei, sich bei möglichen Fehlermeldungen erstmal nicht ins Boxhorn jagen zu lassen. Wenn Fehler beim Aufruf erscheinen, erstmal ignorieren und den nächsten Schritt durchführen, bevor man weitere Debugschritte unternimmt.

[edit] Kontenliste anzeigen

$ aqhbci-tool listaccounts

Werden hier keine Konten angezeigt, unterstützt Ihre Bank vermutlich noch nicht den Abruf der Kontenliste. In diesem Fall bleibt Ihnen derzeit nur die Konten manuell anzulegen (mit dem QT3-Assistenten von AqBanking, z.B. aus QBankManager heraus).

HINWEIS: Bisher haben wir dieses Szenario noch nicht erlebt, alle Konten wurden unter den getesteten Banken aufgelistet. Es gibt daher also keine Erfahrungswerte, was zu tun ist, wenn tatsächlich keine Konten gelistet werden und man wie in diesem HOWTO beschreiben, keine GUI verwendet, sondern die Konten per Hand eintragen muss.

[edit] AqHBCI mit PIN/TAN für mehrere Konten einrichten

Die Einrichtung von mehreren Konten ist nicht ganz so straightforward, wie es die Dokumentation von AqBanking beschreibt. Wir haben deswegen nochmal versucht den Prozess hier im kurzen nochmal als Workflow aufzuschlüsseln :

(XXXXXXXX Bankleizahl/ YYYYYYYYYY UserID)

1ter USER:

$ aqhbci-tool addmedium -t pintan
$ aqhbci-tool adduser -m 0 -s https://hbci-01.hypovereinsbank.de/bank/hbci -b XXXXXXXX -u YYYYYYYYYY
$ aqhbci-tool getsysid
$ aqhbci-tool getaccounts
$ aqhbci-tool listaccounts

n.ter user:

$ aqhbci-tool addmedium -t pintan
$ aqhbci-tool listmedia

die neue MediaNummer 'N'

$ aqhbci-tool adduser -m N -s https://hbci-01.hypovereinsbank.de/bank/hbci -b XXXXXXXX -u YYYYYYYYYY
$ aqhbci-tool getsysid -c YYYYYYYYYY
$ aqhbci-tool getaccounts -c YYYYYYYYYY
$ aqhbci-tool listaccounts

auf -c YYYYYYYYYY achten!

[edit] Erzeugung und Benutzung eines PIN Files

Wenn alle User erstellt sind kann jetzt noch das PINFILE erzeugt werden. Im PINFILE können die PIN's für jeden angelegten Benutzer gespeichert werden um aqbanking-tool einen vollautomatisierten Kontozugriff zu ermöglichen. Dies stellt auf der anderen Seite aber ein Sicherheitsrisiko dar und deshalb sollte die Entscheidung sorgfältig bedacht sein.

Als erster Schritt wird mit AqHBCI ein neues PINFILE erstellt :

$ aqhbci-tool mkpinlist -o ~/.banking/pinfile.pin

Nun muss das PINFILE entsprechend angepasst werden. Dazu wird das PINFILE mit einem editor geöffnet und zeilenweise die PIN's nach jedem User in die bislang leeren "" eingefügt.

$ vi ~/.banking/pinfile.pin

Beispieldatei :

# This is a PIN file to be used with AqBanking
# Please insert the PINs/passwords for the users below

# User "012345678" at "66699911"
"PASSWORD%3A%3APINTAN%2D20040511%2D012345" = "496581"

Nun kann man direkt testen,ob die PIN Eingabe noch notwendig ist oder alles funktioniert hat

$ aqbanking-tool request --balance
$ aqbanking-tool -P ~/.banking/pinfile.pin exec

[edit] HBCI-Rückgabewerte

[edit] Benutzung

Vor der Benutzung des Kommandazeilentools aqbanking-tool sollte man sich genauer mit den Optionen von aqbanking-tool befassen.

[edit] Beispiel auf der Console

Kontoauszug

$ aqbanking-tool request --transactions
$ aqbanking-tool exec --ctxfile=result.ctx
$ aqbanking-tool listtrans --ctxfile=result.ctx --outfile=mytransactions.csv

[edit] Beispielcode zum Aufruf durch PHP

#!/usr/local/bin/php
<?php
 
  $strAQBin   = "/usr/bin/aqbanking-tool";
  $strPFile   = "/path/to/pin.file";
  $strOutFile = "/path/to/transactions.csv";
 
  $strReqListTransCmd = $strAQBin . " request "
                      . "--transactions "
                      . "--fromdate=20010101 "
                      . "--account=12345678";
 
  $strExeListTransCmd = $strAQBin . " -P " . $strPFile . " exec "
                      . "--ctxfile=result.ctx";
 
  $strCnvListTransCmd = $strAQBin . " listtrans "
                      . "--ctxfile=result.ctx "
                      . "--exporter=csv "
                      . "--outfile=" . $strOutFile;
 
  exec ($strReqListTransCmd."> /dev/null 2>&1", $result, $o_exitcode);
 
  if ($o_exitcode != 0) {
    print ("$strReqListTransCmd FAILED because : $result");
    exit  (101);
  }
 
  exec ($strExeListTransCmd."> /dev/null 2>&1", $result, $o_exitcode);
 
  if ($o_exitcode != 0) {
    print ("$strExeListTransCmd FAILED because : $result");
    exit  (102);
  }
 
  exec ($strCnvListTransCmd."> /dev/null 2>&1", $result, $o_exitcode);
 
  if ($o_exitcode != 0) { 
    print ("$strCnvListTransCmd FAILED because : $result");
    exit  (103);
  }  
 
  unlink ("result.ctx");
  chmod  ($strOutFile, 0644);
  print  ("All done, chief");
 
?>

[edit] Erfolgsmeldungen

• Sparkasse, Kamil Wencel 12.08.2006
• HypoVereinbank, Reinhard Lochner, 12.08.2006
• Deutsche Bank und Volksbank Main-Taunus, Ethan Arnold, 07.02.2008
• Sparda-Bank Hamburg, Claas Langbehn, 11.02.2008
• Volksbank Weingarten-Walzbachtal, Andreas Filsinger, 20.02.2008
  • IT Dienstleister ist (wie bei vielen Volksbanken) die Fiducia IT AG Karlsruhe
  • getestet mit AqBanking 2.3.3
• Postbank BLZ 25010030, Björn Böttjer, 02.03.2008
• IT Dienstleister: Fiducia IT AG Aschheim
  • Raiffeisenbank Ingolstadt-Pfaffenhofen-Eichstätt eG, 11.03.2008
• Sparkasse Duisburg 35050000, obengelb GmbH, 12.05.2008, aqbanking-tool_2.2.3-3_i386.deb
• DKB 12030000 - Echi, 30.10.2008 - aqbanking-tool_2.2.3-3_i386.deb
• Sparkasse Amberg-Sulzbach

Falls jemand noch weitere Banken erfolgreich ausprobiert hat, wären wir für Erfolgsmeldungen dankbar. Es ist dann im folgenden einfacher für andere, wenn sie wissen ob es mit der Bank theoretisch funktionieren müsste. Danke allen, die bisher die Funktionen des Wikis auch schreibend benutzt haben ;)

[edit] Mißerfolgsmeldungen

• Volksbank Lübeck (GAD), Claas Langbehn, 13.02.2008

getsysid: Unknown TAN method 922 - das müsste "SmartTAN plus" sein.

getaccounts: Funktioniert nicht, da die Bank die Konten nicht mitteilt.

Hallo Claas, ich muss jetzt was dazu sagen: Ich kann nicht sagen, inwieweit das ganze jetzt noch funktioniert, da aqbanking mittlerweile ein paar versionen weiter ist und die Banken in der zwischenzeit auch viel umgestellt haben. Zusätzlich dazu hat Martin Preuss sich entschieden, aqbanking-tool nicht mehr weiterzuentwickeln, sondern ein Ersatzprodukt "herauszugeben" welches man NUR käuflich erwerben kann.

Siehe auch:

http://www.reaktorblog.de/2008/02/18/aqbanking-tool-gestorben/
http://www.bwurst.org/archives/150-Kurztipp-Automatische-Lastschriften.html

Bookmark this article on your favourite social bookmarking site