AqBanking

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

Überblick

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 ...

1. ... Umsätze abrufen (./umsatz)
2. ... Salden abrufen (./saldo)
3. ... Sammel-Lastschriften durchführen (./lastschrift)
4. ... 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.

Implementierungen

• 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

Projektstatus

Erreichte Meilensteine

1. Linux-Anwendungsebene: QBankingManager installieren (Erfolg: 21.02.2008)
   1. ein Giro-Konto abfragen um zu sehen, ob das Teil funktioniert (Erfolg: 21.02.2008)
   2. Transaktion "Konto-Umsatz-Abfrage" ausprobieren! (Erfolg: 21.02.2008)
   3. Transaktion "Sammel-Lastschrift" (DTA) ausprobieren! (Geht nicht! Nur Einzeln)
2. Linux-Programmierebene: "aqbanking 3" versuchen zu compilieren (Erfolg: 19.02.2008)
3. Mini-Programm Konsolen-Programm erstellen das z.B. die Kontenliste auf den Schirm bringt (Erfolg: 22.02.2008)
4. AH_Job_GetBalance ("~kto~.~blz~") : double (aufgegeben, wir können das ergebnis nicht parsen)
5. AH_Job_GetTransactions ("~kto~.~blz~","20.02.2008") : (Erfolg: 28.02.2008)
6. AH_Job_MultiDebitNode_new (Achtung schwierig: "Multi-Job" + "TAN" notwendig + DTAUS Importer verwenden!) (07.03.2008)
7. Erfolgreiche erzeugung eines DebitNote-Auftrags aus Kommandozeilenparametern und csv-Datei (07.03.2008)
8. Erfolgreiche auftragsübertragung bis zur TAN-Abfrage über den Passwort-Callback!! (05.03.2008)
9. Erfolgreiche Lastschriften mit einer einzelnen, sowie mit 2 Lastschriften in einer Sammellastchrift. (07.03.2008)
10. REST - Server in PHP verwirklicht, Technologie: mod_rewrite und "$fn();" (13.03.2008)
11. REST - Mappings definieren auf ein nun fertiges "aqbc"-Programm das in C programmiert ist. (13.03.2008)
12. REST: Lastschriften (15.03.2008)
13. Umlaute (scheinbar durchgängig UTF-8, wär ja OK!) (19.03.2008)
14. Integration in den OrgaMon 1/2 "Umsatz" (20.03.2008)

Offen

1. Integration in den OrgaMon 2/2 "Sammellastschrift"
2. 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)
3. Grosse Kick-Off-Party für DDBAC

Anwendung als Kommandozeilen-Programm

hier: ./abqd Ausgabe bei "--help"

Lastschriften (-L)

• Der Programmteil Umsatzabfrage ist im Beta-Stadium fertiggestellt!!

Bedienung:

-U oder -u für umsatzabfrage

Danach kommen die Parameter
BLZ KTO PIN [Datum]
ohne - oder / oder ähnliches, nur durch whitespace getrennt

• Erfolgreiche Lastschriften
  • Lastschriftverfahren für ein- oder mehrere Datensätze erfolgreich getestet!
  • Der Programmteil Lastschrift ist im Beta-Stadium fertiggestellt!!

Bedienung

-L oder -l für Lastschrift

Danach kommen die Paramter
BLZ KTO PIN "Pfad der CSV-Datei"
ebenfalls ohne sonderzeichen, nur durch whitespace getrennt

• Erfolgreches Abrufen der Salden und ablegen in eine csv-Datei
  • Der Programmteil Saldo ist im Beta-Stadium fertiggestellt!!

Bedienung:

-S oder -s für Saldo

Danach kommen die Parameter
BLZ KTO PIN
ohne - oder / oder ähnliches, nur durch whitespace getrennt

Anwendung als Dämon für den Serverbetrieb

Dämon (-D)

Es werden zwischen den verschiedenen Programmebenen Daten ausgetauscht, indem Files auf der Festplatte abgelegt werden. (Von der DBUS-Technologie sind wir abgekommen, schlicht und einfach wegen der enormen, und für unsere Zwecke zu hohen, komplexität der DBUS-Bibliothek.)

Job-Files

Wird abtest mit -d als Parameter gestartet befindet sich die Anwendung im "Deamon-Mode".
Aufträge werden mit in sogenannten JobFiles in das jobs-verzeichnis geschrieben, 
und von abtest gelesen. Der Inhalt der Files ist identisch mit den in der Kommandozeile zu 
übergebenden Parameter.
Sind die Jobs Abgearbeitet werden sie je nach erfolg zusammen mit den Ergebnisdaten im csv-
Format in den results ordner, oder in den error-ordner verschoben. Uber jede Aktion werden
log-Dateien geschrieben.

Tan-Übergabe

Die Tan wird ab Sommer 2008 im iTan-verfahren abgefragt, und ist damit nichtmehr frei wählbar.
Die Aufforderung lautet dann in etwa: "Bitte die 17.TAN eingeben: ". Damit muss während 
eines Lastschriftverfahrens die Gegenseite gerufen werden. Dafür wird die Anforderung 
der Bank in einem File Gespeichert, und muss innerhalb von 20sec mit einem tanFile 
"beantwortet" werden.

PHP-Rest-Server

Die erste Alphaversion des Rest-Servers ist jetzt online, und arbeitet super mit abtest zusammen. abtest läuft im Daemon-Modus im Hintergrund, und wird sozusagen vom Restserver ferngesteuert. Das skript erzeugt die Job-Files und prüft auf das Vorhandensein der Ergebnissdaten, und gibt diese aus. Die ersten Dauertests für den Daemon stehen ebenfalls aus.

Anfrage auf den server

http://www.orga-mon.de/rest/Funktion/BLZ/KTO/datum

Funktionen:
./info/
./umsatz/
./saldo/
./lastschrift/
./itan/

Umsatz (./umsatz/)

Anfrage:

./UMSATZ/~BLZ~/~KONTO#~/2008-02-28?f=text

Antwort:

• Mapping csv<->Aqbanking

       // Zuordnungen gefunden
       Buchungsdatum<->date
       Typ<->transactionKey (Beispiel: "NSTO","NMSC","NCHK")
       vonBLZ<->remoteBankCode
       vonKonto<->remoteAccountNumber
       vonName1..2<->remoteName
       ValutaDatum<->valutaDate
       Betrag<->value.value
       Waehrung<->value.currency
       VorgangID<->textKey
       VorgangText<->transactionText
       Primanota<->primanota
       Verwendungszweck1..7<->purpose

Sammellastschrift (./lastschrift)

Anfrage 1/2

POST ./lastschrift/~BLZ~/~Konto~

mit einem zeitgleichen http-Upload der DTA-Datei (Name spielt keine Rolle)!

Antwort:

• die Antwort ist, sobald die DTA-Datei fehlt ein kleines Upload-Formular, mit dem man die Anfrage (diesmal mit Datei) wiederholen kann.
• iTAN: Ist das iTAN Verfahren gewählt, so muss vom Server vor Anzeige der Antwort zunächst die Index-Nummer der iTAN abgefragt werden
• ansonsten ist die Antwort eine Text der Bank, die Informationen zur TAN-Eingabe enthält:

JobID: 293837
Nun bitte die 34. TAN eingeben 

• Mit Hilfe dieser Meldungen muss man eine zweite RESTful Anfrage formulieren. Diesmal mit JobID und TAN. Dazu hat man ein Zeitfenster von 20 Sekunden.

Anfrage 2/2

GET ./itan/~JobID~/~TAN~

Nun erfolgt die TAN-Übergabe an die Bank und die tatsächliche Durchführung. War die Ausführung erfolgreich, so erscheint ein einfaches "OK".

Termin-Überweisung

-- noch kein Bedarf --

Installations-Anleitung (aqbd)

aqbd compilieren

• gwen-Lib installieren

tar xzfz gwenhywfar-3.1.1.tar.gz
cd gwenhywfar-3.1.1
./configure
make
make install

• aqbanking-Lib installieren

tar xzfz aqbanking-3.2.1.tar.gz
cd aqbanking-3.2.1

Wir haben beide Packages in das Verzeichnis /usr/src entpackt.

Im Moment müssen noch 2 Dateien ersetzt werden:

src/plugins/backends/aqhbci/plugin/joblayer/jobqueue.c http://orgamon.de/aqbanking/jobqueue.c
src/plugins/parsers/swift/swift940.c http://orgamon.de/aqbanking/swift940.c

./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.

Kompilieren der Source

touch abtest.c
make abtest

Da unser server ein 64bit-System besitzt, mussten wir vor dem Anlegen der Konten noch eine .so in das richtige lib64-Verzeicnis kopieren.

Konto - Deklaration

• Vorbereitung, wir brauchen ...

1. BLZ
2. HBCI-URL (http://www.hbci-zka.de/institute/institut_auswahl.htm)
3. Kontonummer
4. Benutzerkennung
5. PIN

Benutzer anlegen

aqhbci-tool3 adduser -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.

SSL3 aktivieren (optional)

• 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 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)

erster Test

http://~MeinServer~/saldo/~MeineBLZ~/~MeineKontoNr~/

Ergebnis

Betrag;Waehrung 2938,23;EUR

Links

Aqbanking 3

• 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 Projekte

• http://openlab.radion.org/lab/Konsolenbasiertes_Online_Banking_mit_Linux

leider basiert die Implementierung auf "aqbanking 2" das nicht weiterentwickelt wird. In "aqbanking 3" das wir verwenden wollen ist das Kommandozeilen-Tool "aqbanking-tool" nicht mehr vorhanden.