AqBanking
Überblick
aqbd ist ein für Linux verfügbares Commando-Zeilen-Tool (und Dämon), das es ermöglicht ...
- ... Umsätze und Salden eines Kontos via AqBanking-HBCI auszulesen. Als Ausgabe erzeugt aqbd CSV-Dateien, die leicht weiterverarbeitet werden können.
- ... Laschriften, die als CSV-Datei vorliegen, via AqBanking-HBCI an die Bank zu übertragen und durchzuführen.
weitere Infos über aqbd ...
- ... basiert 100% auf der Arbeit von Martin Preuss http://www.aquamaniac.de/ und der Bibliothek "AqBanking"
- ... nutzt die neueste Generation des "AqBanking" (Version >=3.3.0)
- ... liegt im C-Quelltext (GPL 3.0 Lizenz) vor
- ... bietet im Zusammenspiel mit Apache2+PHP einen RESTful Webservice an
- ... bietet ein simples Webinterface, das es ermöglich eigene Konto-Daten mit einem Browser weltweit abzurufen
Funktionsweise
Installations-Anleitung (aqbd)
aqbd compilieren
Wir haben beide Packages in das Verzeichnis /usr/src entpackt.
- gwen-Lib installieren
tar xzfz gwenhywfar-3.2.0.tar.gz cd gwenhywfar-3.2.0 ./configure make make install
- aqbanking-Lib installieren
tar xzfz aqbanking-3.3.0.tar.gz cd aqbanking-3.3.0
Pachtes
Im Moment müssen noch 3 Patches eingespielt werden:
1/3: Vertuschung von BLANK-BLANK
- Verhalten ohne den Patch: 2 aufeinanderfolgende Blanks werden aus dem Buchungstext. Dadurch werden "tabellarisch" übertragene mehrzeilige Text beeinträchtigt.
- ./src/plugins/parsers/swift.c,
int AHB_SWIFT_Condense(char *buffer) {
char *src=buffer;
char *dst=buffer;
while(*src) {
if (*src!=10) {
*dst=*src;
dst++;
}
src++;
} /* while */
*dst=0;
return 0;
}
2/3 einstellige REF
- Verhalten ohne den Patch: Einstellige Kunden-Referenzmerkmale werden nicht übertragen, und als "" Leerstring geliefert.
- aqbanking/src/plugins/parsers/swift/swift940.c
Alt:
00426: /* customer reference (M) */
00427: if (bleft>1) {
Neu:
00426: /* customer reference (M) */
00427: if (bleft>0) {
3/3 Umlaute im DTA
- Verhalten ohne den Patch: Lastschriften mit deutschen Umlauten können nicht verarbeitet werden
- ./libs/aqbanking/imexporter.c
imexporter.c:1562 (ALT)
c=toupper(c);
if (!(isdigit(c) ||
(c>='A' && c<='Z') ||
(c>='a' && c<='z') ||
(strchr(" .,&-+*%/$", c))))
imexporter.c:1562 (NEU)
c=toupper(c);
if (!(isdigit(c) ||
(c>='A' && c<='Z') ||
(strchr(" .,&-+*%/$[\\]~", c))))
Kompilierung
./configure --disable-tutorials --disable-chipcard-client --with-frontends="" --with-backends="aqhbci" make make install
Danach kopieren der abtest.c-source (einfach die alte überschreiben) in das Verzeichnis /usr/src/aqbanking-3.2.1/src/test.
touch abtest.c make abtest
Da unser Server ein 64bit-System ist, mussten wir vor dem Anlegen der Konten noch alle libaq*, alle libgwen* und die beiden gwenhywfar und aqbanking-verzeichnisse von usr/lib nach usr/lib64 kopieren.
Konto - Deklaration
- Vorbereitung, wir brauchen ...
- BLZ
- HBCI-URL (http://www.hbci-zka.de/institute/institut_auswahl.htm)
- Kontonummer
- Benutzerkennung
- PIN
Benutzer anlegen
aqhbci-tool3 adduser -N "Benutzername" -b BLZ -u Benutzerkennung -s HBCI-URL -t pintan
Konto anlegen
aqhbci-tool3 addaccount -b BLZ -c Benutzerkennung -a Kontonummer
Systeme miteinander bekanntmachen
- Ein notwendiger Schritt damit AqBanking genau speichern kann, was die Gegenstellen für Fähigkeiten und Vorlieben hat.
aqhbci-tool3 getsysid -b BLZ -c Benutzerkennung
- kommt der Fehler "A TLS packet with unexpected length was received" muss man SSL3 (anstelle von SSL2) aktivieren.
Auf HBCI-Version 3.00 umstellen
Da die Banken schon lange auf die HBCI-Version 3 umgestell haben, das von aqhbci nicht immer erkannt wird, muss man in der datei ~/.aqbanking/settings.conf den Wert hbciVersion mit dem höchsten angebotenen Wert bei hbciversions überschrieben werden.
Beispiel
int hbciVersion="220" ... int hbciverions="201", "210", "220", "300"
umschreiben zu
int hbciVersion="300"
iTAN bereitstellen
aqhbci-tool3 getitanmodes -b BLZ
SSL3 aktivieren
- falls erforderlich (siehe oben) diese eine (grüne) Zeile in der Datei
~/.aqbanking/settings.conf
einfügen ...
users {
user {
char userId="~Dein-HBCI-User-Login-Name~"
data {
backend {
...
char userFlags="forceSsl3"
char tokenType="pintan"
...
Sammellastschrift nutzbarmachen
- rote Zeile in der settings.conf rauslöschen...
char multiJobAllowed="N"
... auch wenn mal nur eine Lastschrift verbucht werden soll.
das Flag "PreferSingleDebiNotes" rausmachen
prefersingletransfer 0x00000001 : Einzelüberwisung bevorzugt, für uns unwichtig
prefersingledebitnote 0x00000002 : Ist default, wird einfach aus der settings.conf entfernt, SingleDebinote gibt es nicht bei VoBa!
Zertifikat speichern
- Wechsle ins Verzeichnis /srv/aqb
- Führe eine erste Saldoabfrage durch
aqbd -S ~BLZ~ ~Konto#~ ~PIN~
- Das Programm bricht mit einem Zertifikatsfehler ab
- Umbenennen der frisch erstellten "cert.~BLZ~.~KTO~.tmp"-Datei nach "cert.~BLZ~.~KTO~.txt"
PIN dauerhaft speichern
Erstelle eine Datei "pin.~BLZ~.~KTO~.txt" in /srv/aqb. In ihr darf nur die PIN in einer Zeile enthalten sein, keine Kommentare oder Leerzeilen.
erster Test
aqbd -U ~BLZ~ ~KontoNummer~ ~StartDatum~
Die Umsätze ab ~StartDatum~ werden angezeigt.
Installations-Anleitung (REST)
Apache2 anpassen
- Damit PHP mit den REST-typischen Anfragen aus dem Web zurecht kommt, muss das "mod_rewrite" / "rewrite"-Modul zunächst aktiviert werden.
- Ob das Modul schon aktiv ist kann durch die PHP-Info-Seite deines Apache2 angezeigt werden.
- Wenn nicht hier die Anleitungs, wie man es aktiviert ...
/etc/sysconfig/apache2
- In dieser Datei muss rewrite eingetragen werden!
APACHE_MODULES="actions ... rewrite ..."
- Mit ...
SuSEconfig
muss die Konfiguration scharf geschaltet werden.
- Im nächsten Schritt geht es darum REST-Anfragen aus dem Web so zu manipulieren dass PHP das alles ordentlich verstehen kann ...
/etc/apache2/mod_rewrite.conf
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^/aqb(.*) /aqb/index.php?rest=$1 [QSA,L]
</IfModule>
/etc/apache2/vhosts.d/aqb.conf
<VirtualHost *> ServerName aqb.orgamon.net ServerAlias aqb.raib91 DocumentRoot /srv/www/htdocs/aqb RewriteEngine on RewriteLog /var/log/apache2/rewrite_log RewriteLogLevel 9 RewriteRule ^/(.*) /index.php?rest=$1 [QSA,L] </VirtualHost>
REST Server PHP-Script
erster Test
http://~MeinServer~/saldo/~MeineBLZ~/~MeineKontoNr~/
Ergebnis
Betrag;Waehrung
2938,23;EUR
Historisches
zurück zum Hauptartikel AqBanking.
Erreichte Meilensteine
- Linux-Anwendungsebene: QBankingManager installieren (Erfolg: 21.02.2008)
- ein Giro-Konto abfragen um zu sehen, ob das Teil funktioniert (Erfolg: 21.02.2008)
- Transaktion "Konto-Umsatz-Abfrage" ausprobieren! (Erfolg: 21.02.2008)
- Transaktion "Sammel-Lastschrift" (DTA) ausprobieren! (Geht nicht! Nur Einzeln)
- Linux-Programmierebene: "aqbanking 3" versuchen zu compilieren (Erfolg: 19.02.2008)
- Mini-Programm Konsolen-Programm erstellen das z.B. die Kontenliste auf den Schirm bringt (Erfolg: 22.02.2008)
- AH_Job_GetBalance ("~kto~.~blz~") : double (Erfolg: 26.03.08)
- AH_Job_GetTransactions ("~kto~.~blz~","20.02.2008") : (Erfolg: 28.02.2008)
- AH_Job_MultiDebitNode_new (Achtung schwierig: "Multi-Job" + "TAN" notwendig + DTAUS Importer verwenden!) (07.03.2008)
- Erfolgreiche erzeugung eines DebitNote-Auftrags aus Kommandozeilenparametern und csv-Datei (07.03.2008)
- Erfolgreiche auftragsübertragung bis zur TAN-Abfrage über den Passwort-Callback!! (05.03.2008)
- Erfolgreiche Lastschriften mit einer einzelnen, sowie mit 2 Lastschriften in einer Sammellastchrift. (07.03.2008)
- REST - Server in PHP verwirklicht, Technologie: mod_rewrite und "$fn();" (13.03.2008)
- REST - Mappings definieren auf ein nun fertiges "aqbc"-Programm das in C programmiert ist. (13.03.2008)
- REST: Lastschriften (15.03.2008)
- Umlaute (scheinbar durchgängig UTF-8, wär ja OK!) (19.03.2008)
- Integration in den OrgaMon 1/2 "Umsatz" (20.03.2008)
- Integration in den OrgaMon 2/2 "Sammellastschrift" (26.03.2008)
Offen
- aqbd TimeOut-Problem bei den Lastschriften (Erfolg mit AqBanking 3.5.0)
- aqbd nun als richtiges / eigentständiges Linux Projekt beginnen und Know-How aus abtest übernehmen (Info: http://www.openismus.com/documents/linux/automake/automake.shtml)
- Sammellastschrift mit iTAN (Erfolg mit AqBanking 3.5.0)
- Sammellastschrift mit 2000 Posten durchführen (Massentest!)
Dokumentation
- Installation
- Bedinung über Kommandozeile
- Bedienung im Deamonmode
- Bedienung des Restservers
- Entwickler
Design
Um AqBanking für den OrgaMon nutzbar zu machen wird ein Linux-basierter REST-Webservice implementiert. Dabei dient das Gesamtsystem (Apache2+PHP+index.php+aqbd-Dämon) nur als Wrapper für grundlegende "AqBanking Rev. 3.x" Funktionen. REST hilft uns, auf Kontoumsätze und andere Informationen ganz primitiv über das Web zuzugreifen. Zum Informations-Abruf benötigt man auf der Client-Seite nur einen einfachen Webbrowser (Punkt!). Dadurch ist auch die Integration in andere Prozesse ein Kinderspiel. Ruby on Rails z.B. kann REST-Webservices direkt ansprechen. "AqBanking-REST" bietet dabei folgende Dienste an ...
- ... Umsätze abrufen (./umsatz)
- ... Salden abrufen (./saldo)
- ... Sammel-Lastschriften durchführen (./lastschrift)
- ... OPTIONAL: (Termin-)Überweisungen durchführen (./ueberweisung)
Die Buchführung des OrgaMon kann "externe" Konten via Webserices (vorzugsweise REST) integrieren. Dadurch werden Giro-Konto-Buchungen direkt im OrgaMon sichtbar. Systematischer Aufbau des Server-Dienstes.
- aqbd Download - der aqbanking dämon. Muss notwendigerweise als Dämon programmiert werden da z.B. das Mehrstufige TAN Verfahren mehrere REST-Zyklen benötigt und die Verbindung zur Bank dazwischen nicht unterbrochen werden darf, insbesondere beim iTAN Verfahren. Die Kommunikation mit der Aussenwelt erledigt der Dämon über das Dateisystem. Ein PHP-Script legt Konto-Anfragen in Mini "Job"-Dateien im Verzeichnis /srv/aqbanking ab.
- aqREST Download - der REST Service als PHP Implementierung. Erfordert die mod_rewrite Anpassung im Apache2 (Beschreibung hier REST).
Sicherheitsüberlegungen
- Während der Installtionsphase sollte der Webserver nur für den Admin sichbar sein, bis alles funktioniert
- Dann sollten "pin."-Dateien nur "root" sichtbar gemacht werden
- Überlegungen sollten den Rechten der Verzeichnisse ab /srv/aqb gewidmet werden
- Das Wurzelverzeichnis des REST Servers (index.php) sollte passwortgeschützt werden
- Wird der REST Server im Internet sichtbar sollte https:// (SSL-Verschlüsselung) auf das Verzeichnis gelegt werden
- Die PIN eines Kontos wird design-bedingt niemals über das Netz übertragen
- Der (HBCI-Server-)Login-Name wird design-bedingt niemals über das Netz übertragen
- Von aussen - ohne manuellen Eingriff des admin - können keine veränderte Zertifikate akzeptiert werden. Somit ist ausgeschlossen dass die Übernahme des Netzes rund um den aqbd-Host zum Stehlen von PIN / TAN führen kann
Download
http://cargobay.orgamon.de/aqbd.html
Links
- Homepage: http://www.aquamaniac.de/sites/aqbanking/index.php
- Developement-Snapshot-aqbanking: http://devel.aqbanking.de/viewsvn/aqbanking
- Mailing-List: http://sourceforge.net/mailarchive/forum.php?forum_name=aqbanking-devel
- Alternative zu aqbd: http://openlab.radion.org/lab/Konsolenbasiertes_Online_Banking_mit_Linux (diese Implementierung basiert auf dem veralteten "aqbanking 2")