Difference between revisions of "AqBanking"

From GnuCash
Jump to: navigation, search
(link De/HBCI)
(Coverage: EBICS: clarification for testers)
 
(100 intermediate revisions by 9 users not shown)
Line 1: Line 1:
== Compatibility ==
+
<!-- Translators: Add your language to this table. -->
[[GnuCash]] compiles with all available versions of AqBanking. There used to be some version restrictions, but since gnucash 2.2.7 all versions are supported, as noted on [[AqBanking3_Porting]].
+
{| class="wikitable" style="margin: auto;"
 +
! scope="row"|Languages
 +
| [[de/Online-Banking|Deutsch]]
 +
<!--| [[es/{{PAGENAME}}|Español]]
 +
| [[fr/{{PAGENAME}}|Français]]
 +
| [[He/גנוקאש|עִברִית]]
 +
| [[pt/{{PAGENAME}}|Português]]
 +
| [[Zh-hans/{{PAGENAME}}|简体中文]] -->
 +
|}
 +
Online Banking is in GnuCash realized by the package AqBanking—''' Aquamaniac's Banking''' by Martin Preuß. It contains several ''tools'', a ''library'' and a few separate ''helper libraries''.
  
== HBCI Security Media ==
+
At [{{URL:AB}} aquamaniac.de] ([https://translate.google.com/translate?hl=de&sl=auto&tl=en&u=https%3A%2F%2Fwww.aquamaniac.de%2Frdm%2F machine translation])  are availabe:
HBCI/AqBanking can use the following security Media
+
* the most recent versions inclusive manual,
* PIN/TAN: supported on all OS
+
* the most recent infos, user tips … in the [{{URL:AB}}rdm/projects/aqbanking/wiki AqBanking Wiki],
* self-generated keyfile: supported on all OS
+
* the [{{URL:AB-ML}}listinfo/aqbanking-user Mailinglist aqbanking-user], and finally
* Chipcards: Supported on Linux, but '''Chipcards are not supported on Windows'''. (They are supported on Windows by the latest libchipcard version 4 with gwenhywfar version 3, but gnucash does not compile with those versions yet.)
+
* to report problems a [{{URL:AB}}rdm/projects/aqbanking/issues bugtracker]—but before you should have read [{{URL:AB}}rdm/projects/aqbanking/wiki/Bugreports AqBanking: Fehler oder Probleme melden]!
 +
:;Note:In times of heavy spam registration is disabled. Then ask on its mailing list.
  
== Setting up a HBCI PIN/TAN account ==
+
==Coverage==
=== By Commandline ===
+
Currently offered methods:
This instructions will explain how to set up a HBCI account with PIN/TAN authentification. The access data is from a test account that can be used by any gnucash developer; the instructions are also in src/import-export/hbci/HACKING-HBCITEST.txt.
+
* bidirectional, sending of orders possible:
 +
** the german ''Financial Transaction Services'' ('''[https://www.hbci-zka.de/ FinTS]''') standard with
 +
*** classical '''''h'''ome '''b'''anking '''c'''ommon '''i'''nterface'' (HBCI) by asymetric key encryption or
 +
*** modern ''PIN/TAN'' (2 step authentication) methods;
 +
** ''Electronic Banking Internet Communication Standard'' '''[https://en.wikipedia.org/wiki/Electronic_Banking_Internet_Communication_Standard EBICS]''', availabe for business clients in AT, CH, DE and FR,
 +
*: but because neither AqBanking nor GnuCash devs have access to an test server, upload is ''currently not implemented''. The AqBanking team is searching for users, who volunteer to test on implementing the upload.
 +
* unidirectional, query only:
 +
** '''[[Setting up OFXDirectConnect|OFX Direct Connect]]''', used mainly in the US, and
 +
** since AqBanking 5.7.8.0stable '''Paypal'''.
 +
The recent ''stable'' GnuCash {{Version}} bundles contain Aqbanking {{AqB_Version}}, the nightly ''test'' versions {{AqB Version nightly}}.
 +
:;Source: [{{URL:AB}}rdm/projects/aqbanking/wiki/AqBanking6#Aktueller-Status-der-Backends-in-AqBanking6]
  
Instructions are copied from http://linuxwiki.de/AqBanking/aqhbci-tool where they are in German. We have also a [[De/HBCI|german page (deutsche Seite)]] and the content might be partial different.
+
== Compatibility ==
 +
[[GnuCash]] compiles with many available versions of <tt>AqBanking</tt> and it's helper library <tt>Gwenhywfar</tt>, except for combinations of new gnucash with old aqbanking and vice versa.
  
We assume you have aqbanking and gnucash installed, and aqbanking's program <tt>aqhbci-tool</tt> is in your PATH.
+
=== Determinating the Versions ===
 +
To see your current versions, use the command {{Shell Versions}} or, if you are using a [[Flatpak]]: {{Flatpak Versions}}
 +
In this example you can see, that the user had built a more recent version of GnuCash, but the nightly Flatpak had a more recent AqBanking than her distribution.
  
Attention developers: If you call these programs and/or gnucash from the MSYS command line, you must change your HOME env variable to be the value of the USERPROFILE variable. This is because MSYS sets a new HOME that isn't know to any other (normal) windows program that is started outside MSYS. In particular, if you start gnucash outside of msys, it will look for the configuration and also for aqbanking's configuration in $USERPROFILE, but in msys, it will look in HOME. So you always have to gnucash as <tt>HOME="$USERPROFILE" gnucash</tt>
+
== FinTS ==
 +
This is only an overview mainly for developers. Detailed user instructions are in German: [[De/Online-Banking]]
 +
=== HBCI/FinTS Security Type ===
 +
AqBanking for FinTS/HBCI needs the definition of a "security medium". Depending on the FinTS/HBCI version, there is a range of choices for this:
 +
;Single step authentication:
 +
:;HBCI 1: self-generated asymetric keypair with
 +
::* public part given to the bank
 +
::* private part stored on your harddisk, USB stick or floppy disk
 +
::supported on all OS, but many banks dropped single step authentication.
 +
;Two step authentication:
 +
:*You have always to log in your session with your fixed ''Personal Identification number'' (PIN).
 +
:*Then each transaction needs authentication with an own ''Transaction Authentification Number'' (TAN).
 +
::To avoid Man-in-the-middle (MITM) attacks the TANs are ideally transmitted to you over a different medium.
 +
::The way the TAN is generated varies by method:
 +
:;HBCI 2, FinTS 3: PIN/TAN comes in several flavours:
 +
:::;PIN/TAN (classic): no longer supported by the banks! <s>from a simple ''paper list'': you can enter any ''unused'' TAN: supported on all OS</s>
 +
:::;iTAN: no longer supported by the banks! <s>from an indexed ''paper list'': the bank challenges TAN[i]: supported on all OS</s>
 +
:::;mTAN: TAN per SMS on your ''mobile'': supported on all OS
 +
::;chipTAN: The TAN is generated by a chip, which is today integrated in the bank card. You need a card reader to communicate with the chip. Some readers are stand alone devices, but others are connected with your computer. To access the connected readers the library <tt>libchipcard</tt> from the AqBanking family is required.
 +
:::;Warning!:[https://www.redteam-pentesting.de/en//publications/mitm-chiptan-comfort Man-in-the-Middle Attacks against the chipTAN comfort Online Banking System]
 +
:::;manual:
 +
:::;several optical methods: Since version 4.3 GC supported the flickering image. <s>GC does not generate the flickering image, but you can manually enter the displayed number in your ''TAN generator''. [{{BugURL}}/show_bug.cgi?id=667490 Bug 667490 - Support image-based TAN methods QR, photoTAN, and chipTAN optical "Flicker code"]</s>
 +
::::; Flicker code: The number is transferred in nibbles plus parity bit by an animated gif.
 +
::::; QR code: can be decoded by smartphones.
 +
::::; Photo TAN: The TAN is sent as a photo.
 +
:;Tip: There is a more precise description: [{{URL:AB}}rdm/projects/aqbanking/wiki/ImplementTanMethods Aqbanking Wiki: Implement Tan Methods]
 +
:;Note: For this standard methods some banks use own names created by their marketing department like sm@rtTAN.
 +
.
  
==== Create/register a new security medium in AqBanking ====
+
=== FinTS Test Server ===
aqhbci-tool addmedium -t pintan
+
There are no currently documented instructions. There is no known test account with a testing bank server. To our knowledge anyone who wants to test this needs an account at a German bank. Sorry for that.
==== Find out the index number of the newly created security medium ====
 
aqhbci-tool listmedia
 
The output will be something like
 
Medium 0: "PINTAN-20070216-214030" (pintan)
 
and the important part is the first number, here: 0.
 
  
==== Create a HBCI user ====
+
== Debugging ==
aqhbci-tool adduser -m N -s SERVERURL -b BANKCODE -u USERID
+
If there are any problems during the HBCI or OFX connection, here are further options for debugging:
where <tt>N</tt> is the medium number (0), SERVERURL is the full URL of the server application, BANKCODE is the bank code, and USERID is the identification string of the user that is allowed to access this account. For the test account, we have the following:
+
# In Gnucash in <tt>Edit->Preferences->Online Banking</tt>:
aqhbci-tool adduser -m 0 -s www.hora-obscura.de/pintan/PinTanServlet -b 80007777 -u gnucash
+
## Disable <tt>Close log window when finished</tt><ref>This setting affects only GnuCash's dialogs—<tt>Action->…</tt>. Most dialogs of <tt>Tools->Online Banking Setup</tt> are provided by AqBanings library Gwenhywfar.</ref> ,
There is an optional argument of the CUSTOMERID, but this concerns you only if your bank explicitly said you have to use some extra customer id that is different from the user id.
+
## enable <tt>Verbose debug messages</tt>. Since Gnucash 2.3.x this is related to AQBANKING_LOGLEVEL.
 +
# To see much more '''log messages''' of aqbanking, you can set several [https://en.wikipedia.org/wiki/Environment_variable environment variables] either before starting gnucash or in the shell script gnucash or gnucash.bat. For example, in a Unix shell you would type <SyntaxHighlight lang="sh>
 +
# General:
 +
export GWEN_LOGLEVEL=info # usually only developers need this sometimes.
 +
export AQBANKING_LOGLEVEL=info
 +
# For OFX:
 +
export AQOFX_LOG_COMM=1 # Warning: Will reveal passwords!
 +
export AQOFXCONNECT_LOGLEVEL=info
 +
# For FinTS/HBCI:
 +
export AQHBCI_LOGLEVEL=info # Warning: Will reveal passwords!
 +
</SyntaxHighlight> For <tt>AQOFX_LOG_COMM</tt> see [[Setting_up_OFXDirectConnect#Enabling_the_OFX_Log]],
 +
::other possible values to all other of these variables are
 +
::*<tt>debug</tt> (more verbose) or
 +
::*<tt>warn</tt> (less verbose) or
 +
::*<tt>error</tt> (even less verbose, default value).
 +
:However, the Gwenhywfar log messages are all sent to ''stdout'' or ''stderr'', which on [[Windows]] by default isn't available. To make these available on Windows, you need to change the exetype of ''gnucash-bin.exe'' from "Windows" to "Console", see [[Windows Debugging#Changing the Exetype to See Console Output]].
 +
:AQBanking log messages are intercepted by a GnuCash callback and added to the [[Trace_file]]. '''N.B.:''' That callback does a second filter on log level so it's necessary to set the AQBanking log level in GnuCash as well as setting the <tt>AQBANKING_LOGLEVEL</tt> by passing the argument <tt>--log aqbanking=xxx</tt> to GnuCash, e.g. <syntaxhighlight lang="sh">
 +
AQBANKING_LOGLEVEL=info gnucash --log aqbanking=info
 +
</syntaxhighlight> or adjust your [[Logging|logging configuration]].
  
==== Retrieve a system identification number ====
+
* Keep in mind that there are many many many different bank servers on this world, and every one of them might behave slightly differently. Hence, if you report a bug, please also state which '''bank server''' you are using (IP address and bank name).
This system identification is necessary for the HBCI protocol to identify you and your software; if this step is forgotten or fails, nothing else will work.
+
* If there is a '''crash''', it would be good to provide a stack trace of the crash, see [[Stack Trace]].
aqhbci-tool getsysid -b BANKCODE
 
This command will ask you several questions. First it retrieves the server certificate and asks you whether you accept it. Then it asks whether you want to accept the certificate only this session or forever. Eventually, you have to enter the PIN number (password) of your online banking account. (For the gnucash test account, this is 12345.) The full output looks e.g. like this:
 
  
aqhbci-tool getsysid -b 80007777
+
=== Log Location ===
===== Certificate Received =====
+
As for aqbanking up to version 5.x.x:
The following certificate has been received:
+
AqBanking stores log files for '''HBCI''' under Linux in
Name        : www.hora-obscura.de
+
:<tt>~/.aqbanking/backends/aqhbci/data/banks/<country code>/<Bank ID>/logs/*</tt>, with
Organisation: www.hora-obscura.de
+
:''.aqbanking'' a hidden directory in the user's home directory,
Department  : GT90185227
+
:''<country code>'' your ISO country code such as "de",
Country    : DE
+
:''<Bank ID>'' the name or the routing number of your bank (in German: BLZ).
City        : unknown
 
State      : unknown
 
Valid after : 2007/02/15 14:28:06
 
Valid until : 2008/05/17 14:28:06
 
Hash        : 69:CF:A0:D9:EA:1F:4B:DA:5F:FA:7D:EE:75:87:C9:FF
 
Status      : Certificate is valid
 
Do you wish to accept this certificate?
 
(1) Yes  (2) No
 
Please enter your choice: 1
 
===== Certificate =====
 
Do you want to accept this certificate permanently?
 
(1) Permanently  (2) This session only  (3) Abort
 
Please enter your choice: 1
 
===== Enter Password =====
 
Please enter the password for
 
PINTAN-20070216-215639
 
Input: *****
 
  
Any additional (error) messages can be ignored for now; just continue to work.
+
To enable logging of the '''OFX''' communication to <code>/tmp/ofx.log</code> (with warnings about revealing passwords), see [[Setting up OFXDirectConnect in GnuCash 2#Enabling the OFX Log]].
  
==== List the resulting accounts ====
+
;Anonymization of log files: Before you show your log files to anybody, you should replace ''passworda'', ''PINs'', ''TANs'' and other secrets by <code>X</code>es. Before publishing them e.g. sending to a mailing list, replace also your ''account number''. In theory this can also be done with <syntaxhighlight lang="sh">
aqhbci-tool listaccounts
+
aqhbci-tool4 logfile -i $INPUTLOGFILE -o $OUTPUTLOGFILE
The bank server should have sent a list of accounts in the last step already. If this is the case, you can view the list of accessible accounts now. The output for the gnucash test should look like this:
+
</syntaxhighlight> But verify that the program did not miss some.
Account 0: Bank: 80007777 Account Number: 2501111538
 
Account 1: Bank: 80007777 Account Number: 2501111539
 
Account 2: Bank: 80007777 Account Number: 2501111540
 
If you've come this far, then congratulations: Your online access works!
 
  
==== Match the HBCI accounts in gnucash ====
+
=== Config Location ===
In order to access the accounts from gnucash, you need to match a HBCI account to one of your gnucash accounts each. The next time you start gnucash, press "Tools -> Online Banking Setup" to use the online banking setup wizard. Press "Next" there. Ignore the text that says you should start the external program "AqBanking setup wizard", because you've already set up aqbanking by the command line. Because of this, press "Next" again.  
+
Most parts are stored by the setup assistent below
 +
:;Posix: <tt>$HOME/.aqbanking/</tt>
 +
:;Flatpak: <tt>~/.var/app/org.gnucash.Gnucash/aqbanking</tt>.  
  
You will now arrive at the "Match HBCI accounts with GnuCash accounts" window. You should see the three accounts mentioned above in the left column of the wizard window.
+
Gnucash stores only an ''association'' in the account's slots in the '''data file'''.
 +
Example from an uncompressed xml file:{{HBCI_Frame}}
 +
:;account-id: The account number.
 +
:;account-uid: AQBanking's internal id for the account.
 +
:;bank-code: The national bank id: In the US it's the Routing ID.
 +
:;trans-retrieval: Timestamp for the last time a retrieval attempt was made for this account.
  
Click on an account name on the left (the account defined in the AqBanking setup wizard configuration), and select the GnuCash account that should be associated with it.
+
=== GnuCash, Aqbanking or Other Error ===
 +
* If you can execute an operation successful with the ''<tt>aqbanking</tt> command line tools'', but not with <tt>gnucash</tt>, it is obvisious a GnuCash issue.
 +
* Else the issue might be in
 +
# your settings,
 +
# the bank's configuration,
 +
# AqBanking.
 +
Which Aqbanking CLI tools exist? {{Aqbanking Tools con}}
 +
:<tt>aqbanking-cli</tt> serves for executing online actions after configuration.
 +
:<tt>aqbanking-config</tt> covers the general part of the configuration, while the others configure the backend specific parts.
  
Click the Forward button.
+
== References ==
  
In the next window, click the Apply button.
+
* AqBanking:
 
+
** [{{URL:AB}} Homepage] mostly in german, includes a
== Using HBCI accounts in GnuCash ==
+
*** [{{URL:AB}}rdm/projects/aqbanking/wiki wiki],
You're now ready to use the HBCI accounts from the respective GnuCash register windows. See [[Setting_up_OFXDirectConnect_in_GnuCash_2#Using_Gnucash_to_download_transactions_directly_to_an_account_register]] on how to do this.
+
*** [{{URL:AB-ML}}listinfo/aqbanking-user mailing list] and
 
+
*** [{{URL:AB}}rdm/projects/aqbanking/issues bug tracker].
== Using the test account ==
+
** [https://sourceforge.net/projects/aqbanking/ @ Sourceforge] outdated
As mentioned above, the gnucash developers can use a test account to test some of the aqbanking/HBCI features. Here's a step-by-step instruction of what you can do:
+
* EBICS: [http://www.ebics.org/technical-information/ Technical Information]
* Setup the accounts as described above.
+
* The former Home Banking Common Interface (HBCI) got complemented by PIN/TAN and is now called FinTS - Financial Transaction Services:
* In gnucash, match one of your gnucash accounts with the first test account (bank code 80007777, account number 2501111538); press "Next" and "Finish" in the wizard.
+
** [https://www.hbci-zka.de/ FinTS - Financial Transaction Services] (former HBCI) specifications, including error codes ... in German.
=== Testing "Get Balance" ===
+
** <s>[https://www.hbci-zka.de/institute/institut_auswahl.htm Search FinTS capable institutes] and their specific settings</s> is no longer public available.
* Open the gnucash register of the account that you've matched with hbci above
+
<!-- Fell  is still searching for another source
* Press "Actions -> Online actions -> Get balance"
+
, requires
* When asked for the password/PIN, enter <tt>12345</tt>
+
*** former german routing number ("Bankleitzahl") or
* If things run successfully, you are being told a balance and asked whether you want to reconcile your account. The balance value changes by the other test users anyway, so you don't have to care about the actual balance.
+
*** name ("Institut") and place ("Ort") -->
=== Testing "Get Transactions" ===
+
:;Tip: use https://translate.google.com to get a usable translation of the pages.
* Open the gnucash register of the account that you've matched with hbci above
 
* Press "Actions -> Online actions -> Get transactions"
 
* When asked for the date, enter "From: 2007-02-15", but the To-date can be left at "now".
 
* When asked for the password/PIN, enter <tt>12345</tt>
 
* If things run successfully, you see the "transaction matcher window" with the downloaded transactions. You can select "New" for all of them. At subsequent downloads, those transactions that are downloaded again should automatically be marked as "Reconcile" instead.
 
=== Testing "Issue Transaction" ===
 
* Open the gnucash register of the account that you've matched with hbci above
 
* Press "Actions -> Online actions -> Issue transaction"
 
* Enter the following values:  
 
** Recipient account number <tt>2501111539</tt> , recipient bank code <tt>80007777</tt>
 
** All other fields can contain whatever values you like; if they are not allowed to be empty, you will be told so when clicking "Ok".
 
* Click "Ok". Now select a destination account in gnucash, then click "Ok".
 
* When asked for the password/PIN, enter <tt>12345</tt>
 
* When asked for a '''TAN''' and specifically for TAN number 1 (or another number of 2 through 9), enter <tt>11111111</tt> (or <tt>22222222</tt>...), i.e. exactly eight times the number in the question.
 
** It seems like the test account does not give out any TANs anymore. The server asks for TAN number 'no_more_free_user_tans'.
 
* If things run successfully, you only see the transaction in the gnucash register now. If the transmission didn't work, the transaction in the register should have been deleted again. If things worked ok, your next statement download should download that transaction that you've just sent to the bank, and the next balance download should have changed by that amount as well.
 
 
 
== Debugging ==
 
If there are any problems during the HBCI or OFX connection, here are further options for debugging:
 
* Keep in mind that there are many many many different bank servers on this world, and every one of them might behave slightly differently. Hence, if you report a bug, please also state which '''bank server''' you are using (IP address and bank name).
 
* If there is a '''crash''', it would be good to provide a stack trace of the crash, see [[Stack Trace]] and [[Windows#Debugging with gdb]].
 
* To see much more '''log messages''' of aqbanking, you can set several environment variables either before starting gnucash or in the shell script gnucash or gnucash.bat. For example, in a Unix shell you would type
 
export GWEN_LOGLEVEL=info
 
export AQBANKING_LOGLEVEL=info
 
export AQOFXCONNECT_LOGLEVEL=info
 
export AQHBCI_LOGLEVEL=info
 
:Other possible values to all of these variables are
 
:*<tt>debug</tt> (more verbose) or
 
:*<tt>warn</tt> (less verbose) or
 
:*<tt>error</tt> (even less verbose, default value).
 
 
 
However, these log messages are all sent to ''stdout'' or ''stderr'', which on [[Windows]] by default isn't available. To make these available on Windows, you need to change the exetype of ''gnucash-bin.exe'' from "Windows" to "Console", see [[Windows#Console output and exetype]].
 
  
From the german mailing list in 2011:
+
=== Git Repositories ===
AqBanking stores log files for '''HBCI''' in <tt>~/.aqbanking/backends/aqhbci/data/banks/<country code>/<Bank ID>/logs/*</tt>
+
AqBanking Git repositories of source code can be found here (mirrored at  ):
 +
<syntaxhighlight lang="sh">
 +
git clone https://git.aquamaniac.de/git/aqbanking   # the library
 +
git clone https://git.aquamaniac.de/git/gwenhywfar  # its OS abstraction layer as dependency
 +
git clone https://git.aquamaniac.de/git/libchipcard # optional for the use of chipcard readers
 +
</syntaxhighlight>
 +
There are also gitweb browser interfaces at
 +
:http://git.aqbanking.de/gitweb/?p=gwenhywfar.git ,
 +
:http://git.aqbanking.de/gitweb/?p=aqbanking.git .
  
To enable logging of the '''OFX''' communication to <tt>/tmp/ofx.log</tt> (with warnings about revealing passwords), see [[Setting up OFXDirectConnect in GnuCash 2#Enabling the OFX Log]].
+
==== Unofficial GitHub Mirrors ====
 +
Some community members set up (unofficial) github mirrors:
  
=== Known Issues ===
+
:;Christian Stimmig
 +
::https://github.com/cstim/aqbanking
 +
::https://github.com/cstim/gwenhywfar
 +
::There is also a continuous integration build test of gwenhywfar here: https://travis-ci.org/cstim/gwenhywfar
  
* from 2.1.1 until before 2.2.5: http://bugzilla.gnome.org/show_bug.cgi?id=439654 AqBanking on Windows cannot download balance/transactions via HBCI - there is a "Unable to send (network error)" instead. The bugreport contains a patch for the gwenhywfar DLL which must be recompiled. If someone confirms that this patch fixes the problem, the patch will be included in a new gwenhywfar release, but currently the gwenhywfar maintainers are waiting for such feedback.
+
:;Felix Schwarz, Lukas Matt
 +
::https://github.com/aqbanking/gwenhywfar
 +
::https://github.com/aqbanking/aqbanking
 +
::https://github.com/aqbanking/libchipcard
 +
::A bot script updates the "github.com/aqbanking" mirror on a daily basis so it should always be up-to-date.
  
== References ==
+
=== Currently Unsupported Open Standards ===
 +
;Note: The methods supported by AqBanking create a ''direct connection'' between you, the customer, and your bank. In contrast the 'Access to Account  ('''XS2A''') Open Banking Framework' serves to allow a FinTech ''in your name'' a connection to your bank. Some consider that as dangerous.
  
* AqBanking:
+
While many banks still think ''Security by obscurity'' is a good concept, in some countries they are changing their opinion:
** [http://www2.aquamaniac.de/sites/aqbanking/index.php Homepage] mostly in german
+
;AU: https://www.finder.com.au/open-banking
** [http://sourceforge.net/projects/aqbanking/ @ Sourceforge] somewhat outdated
+
;GB (UK): https://www.openbanking.org.uk/
* HBCI, now official called FinTS - Financial Transaction Services:
 
** [http://www.hbci-zka.de/english/ FinTS - Financial Transaction Services] (former HBCI) specifications, including error codes ...
 
** [http://www.hbci-zka.de/institute/institut_auswahl.htm Search FinTS capable institutes] and their specific settings, requires
 
*** BLZ number ("Bankleitzahl") or
 
*** name ("Institut") and place ("Ort")
 

Latest revision as of 18:22, 4 January 2023

Languages Deutsch

Online Banking is in GnuCash realized by the package AqBanking— Aquamaniac's Banking by Martin Preuß. It contains several tools, a library and a few separate helper libraries.

At aquamaniac.de (machine translation) are availabe:

Note
In times of heavy spam registration is disabled. Then ask on its mailing list.

Coverage

Currently offered methods:

  • bidirectional, sending of orders possible:
    • the german Financial Transaction Services (FinTS) standard with
      • classical home banking common interface (HBCI) by asymetric key encryption or
      • modern PIN/TAN (2 step authentication) methods;
    • Electronic Banking Internet Communication Standard EBICS, availabe for business clients in AT, CH, DE and FR,
    but because neither AqBanking nor GnuCash devs have access to an test server, upload is currently not implemented. The AqBanking team is searching for users, who volunteer to test on implementing the upload.
  • unidirectional, query only:

The recent stable GnuCash 5.5 bundles contain Aqbanking 6.5.4, the nightly test versions 6.5.4.

Source
[1]

Compatibility

GnuCash compiles with many available versions of AqBanking and it's helper library Gwenhywfar, except for combinations of new gnucash with old aqbanking and vice versa.

Determinating the Versions

To see your current versions, use the command
$ gnucash --version
GnuCash 3.8 development version
Build ID: git 3.8b-163-g0e6c9e219+(2020-02-19)
$ aqbanking-cli versions
Versions:
 AqBanking-CLI: 6.0.1
 Gwenhywfar   : 5.1.2.0
 AqBanking    : 6.0.1.0
or, if you are using a Flatpak:
$ flatpak run --command=sh org.gnucash.GnuCash
[📦 org.gnucash.GnuCash ~]$ gnucash --version
GnuCash 3.8 development version
Build ID: git e6b3c56+(2020-01-26)
[📦 org.gnucash.GnuCash ~]$ aqbanking-cli versions
Versions:
 AqBanking-CLI: 6.0.2
 Gwenhywfar   : 5.1.3.0
 AqBanking    : 6.0.2.0
[📦 org.gnucash.GnuCash ~]$ exit
exits

In this example you can see, that the user had built a more recent version of GnuCash, but the nightly Flatpak had a more recent AqBanking than her distribution.

FinTS

This is only an overview mainly for developers. Detailed user instructions are in German: De/Online-Banking

HBCI/FinTS Security Type

AqBanking for FinTS/HBCI needs the definition of a "security medium". Depending on the FinTS/HBCI version, there is a range of choices for this:

Single step authentication
HBCI 1
self-generated asymetric keypair with
  • public part given to the bank
  • private part stored on your harddisk, USB stick or floppy disk
supported on all OS, but many banks dropped single step authentication.
Two step authentication
  • You have always to log in your session with your fixed Personal Identification number (PIN).
  • Then each transaction needs authentication with an own Transaction Authentification Number (TAN).
To avoid Man-in-the-middle (MITM) attacks the TANs are ideally transmitted to you over a different medium.
The way the TAN is generated varies by method:
HBCI 2, FinTS 3
PIN/TAN comes in several flavours:
PIN/TAN (classic)
no longer supported by the banks! from a simple paper list: you can enter any unused TAN: supported on all OS
iTAN
no longer supported by the banks! from an indexed paper list: the bank challenges TAN[i]: supported on all OS
mTAN
TAN per SMS on your mobile: supported on all OS
chipTAN
The TAN is generated by a chip, which is today integrated in the bank card. You need a card reader to communicate with the chip. Some readers are stand alone devices, but others are connected with your computer. To access the connected readers the library libchipcard from the AqBanking family is required.
Warning!
Man-in-the-Middle Attacks against the chipTAN comfort Online Banking System
manual
several optical methods
Since version 4.3 GC supported the flickering image. GC does not generate the flickering image, but you can manually enter the displayed number in your TAN generator. Bug 667490 - Support image-based TAN methods QR, photoTAN, and chipTAN optical "Flicker code"
Flicker code
The number is transferred in nibbles plus parity bit by an animated gif.
QR code
can be decoded by smartphones.
Photo TAN
The TAN is sent as a photo.
Tip
There is a more precise description: Aqbanking Wiki: Implement Tan Methods
Note
For this standard methods some banks use own names created by their marketing department like sm@rtTAN.

.

FinTS Test Server

There are no currently documented instructions. There is no known test account with a testing bank server. To our knowledge anyone who wants to test this needs an account at a German bank. Sorry for that.

Debugging

If there are any problems during the HBCI or OFX connection, here are further options for debugging:

  1. In Gnucash in Edit->Preferences->Online Banking:
    1. Disable Close log window when finished[1] ,
    2. enable Verbose debug messages. Since Gnucash 2.3.x this is related to AQBANKING_LOGLEVEL.
  2. To see much more log messages of aqbanking, you can set several environment variables either before starting gnucash or in the shell script gnucash or gnucash.bat. For example, in a Unix shell you would type
    # General:
    export GWEN_LOGLEVEL=info # usually only developers need this sometimes.
    export AQBANKING_LOGLEVEL=info
    # For OFX:
    export AQOFX_LOG_COMM=1 # Warning: Will reveal passwords!
    export AQOFXCONNECT_LOGLEVEL=info
    # For FinTS/HBCI:
    export AQHBCI_LOGLEVEL=info # Warning: Will reveal passwords!
    
    For AQOFX_LOG_COMM see Setting_up_OFXDirectConnect#Enabling_the_OFX_Log,
other possible values to all other of these variables are
  • debug (more verbose) or
  • warn (less verbose) or
  • error (even less verbose, default value).
However, the Gwenhywfar log messages are all sent to stdout or stderr, which on Windows by default isn't available. To make these available on Windows, you need to change the exetype of gnucash-bin.exe from "Windows" to "Console", see Windows Debugging#Changing the Exetype to See Console Output.
AQBanking log messages are intercepted by a GnuCash callback and added to the Trace_file. N.B.: That callback does a second filter on log level so it's necessary to set the AQBanking log level in GnuCash as well as setting the AQBANKING_LOGLEVEL by passing the argument --log aqbanking=xxx to GnuCash, e.g.
AQBANKING_LOGLEVEL=info gnucash --log aqbanking=info
or adjust your logging configuration.
  • Keep in mind that there are many many many different bank servers on this world, and every one of them might behave slightly differently. Hence, if you report a bug, please also state which bank server you are using (IP address and bank name).
  • If there is a crash, it would be good to provide a stack trace of the crash, see Stack Trace.

Log Location

As for aqbanking up to version 5.x.x: AqBanking stores log files for HBCI under Linux in

~/.aqbanking/backends/aqhbci/data/banks/<country code>/<Bank ID>/logs/*, with
.aqbanking a hidden directory in the user's home directory,
<country code> your ISO country code such as "de",
<Bank ID> the name or the routing number of your bank (in German: BLZ).

To enable logging of the OFX communication to /tmp/ofx.log (with warnings about revealing passwords), see Setting up OFXDirectConnect in GnuCash 2#Enabling the OFX Log.

Anonymization of log files
Before you show your log files to anybody, you should replace passworda, PINs, TANs and other secrets by Xes. Before publishing them e.g. sending to a mailing list, replace also your account number. In theory this can also be done with
aqhbci-tool4 logfile -i $INPUTLOGFILE -o $OUTPUTLOGFILE
But verify that the program did not miss some.

Config Location

Most parts are stored by the setup assistent below

Posix
$HOME/.aqbanking/
Flatpak
~/.var/app/org.gnucash.Gnucash/aqbanking.

Gnucash stores only an association in the account's slots in the data file.

Example from an uncompressed xml file:
    <slot>
      <slot:key>hbci</slot:key>
      <slot:value type="frame">
         <slot>
           <slot:key>account-id</slot:key>
           <slot:value type="string">1234567890</slot:value>
         </slot>
         <slot>
           <slot:key>account-uid</slot:key>
           <slot:value type="integer">9</slot:value>
         </slot>
        <slot>
          <slot:key>bank-code</slot:key>
          <slot:value type="string">121107882</slot:value>
        </slot>
        <slot>
          <slot:key>trans-retrieval</slot:key>
          <slot:value type="timespec">
            <ts:date>2017-08-27 09:33:08 -0700</ts:date>
          </slot:value>
        </slot>
      </slot:value>
    </slot>
account-id
The account number.
account-uid
AQBanking's internal id for the account.
bank-code
The national bank id: In the US it's the Routing ID.
trans-retrieval
Timestamp for the last time a retrieval attempt was made for this account.

GnuCash, Aqbanking or Other Error

  • If you can execute an operation successful with the aqbanking command line tools, but not with gnucash, it is obvisious a GnuCash issue.
  • Else the issue might be in
  1. your settings,
  2. the bank's configuration,
  3. AqBanking.
Which Aqbanking CLI tools exist?
$ aq[TAB][TAB]
aqbanking-cli     aqbanking-config  aqebics-tool      aqhbci-tool4      aqpaypal-tool     
$ aqbanking-cli --help
This is version 6.2.1
Usage: aqbanking-cli [GLOBAL OPTIONS] COMMAND [LOCAL OPTIONS]

Global Options:
:
aqbanking-cli serves for executing online actions after configuration.
aqbanking-config covers the general part of the configuration, while the others configure the backend specific parts.

References

Tip
use https://translate.google.com to get a usable translation of the pages.

Git Repositories

AqBanking Git repositories of source code can be found here (mirrored at ):

git clone https://git.aquamaniac.de/git/aqbanking   # the library
git clone https://git.aquamaniac.de/git/gwenhywfar  # its OS abstraction layer as dependency
git clone https://git.aquamaniac.de/git/libchipcard # optional for the use of chipcard readers

There are also gitweb browser interfaces at

http://git.aqbanking.de/gitweb/?p=gwenhywfar.git ,
http://git.aqbanking.de/gitweb/?p=aqbanking.git .

Unofficial GitHub Mirrors

Some community members set up (unofficial) github mirrors:

Christian Stimmig
https://github.com/cstim/aqbanking
https://github.com/cstim/gwenhywfar
There is also a continuous integration build test of gwenhywfar here: https://travis-ci.org/cstim/gwenhywfar
Felix Schwarz, Lukas Matt
https://github.com/aqbanking/gwenhywfar
https://github.com/aqbanking/aqbanking
https://github.com/aqbanking/libchipcard
A bot script updates the "github.com/aqbanking" mirror on a daily basis so it should always be up-to-date.

Currently Unsupported Open Standards

Note
The methods supported by AqBanking create a direct connection between you, the customer, and your bank. In contrast the 'Access to Account (XS2A) Open Banking Framework' serves to allow a FinTech in your name a connection to your bank. Some consider that as dangerous.

While many banks still think Security by obscurity is a good concept, in some countries they are changing their opinion:

AU
https://www.finder.com.au/open-banking
GB (UK)
https://www.openbanking.org.uk/
  1. This setting affects only GnuCash's dialogs—Action->…. Most dialogs of Tools->Online Banking Setup are provided by AqBanings library Gwenhywfar.
  2. Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=AqBanking&oldid=21447"