AqBanking

From GnuCash
Revision as of 20:41, 23 December 2020 by CWehli (talk | contribs) (TAN-List and iTAN are deprecated, Flickering image is supported as of version 4.3)
Jump to: navigation, search

Aquamaniacs Banking (translation) is a library for online banking. In particular, the german online banking standard FinTS (Financial Transaction Services) is supported, which originally was named home banking common interface (HBCI) and that old name still appears in module names etc. Additionally, some other online banking standards are supported or have been, such as

  • Electronic Banking Internet Communication Standard EBICS, used in CH, DE and FR,
  • OFX Direct Connect, used mainly in the US, and
  • since AqBanking 5.7.8.0stable Paypal are supported.

Deutsche Version: De/HBCI (German version of this page)

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

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,
    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
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, 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 Debugging#Changing the Exetype to See Console Output.
  • 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.

Config Location

Most parts are stored by the setup assistent below $HOME/.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 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 tranlation 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

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/
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=AqBanking&oldid=17013"