HBCI

May 29, 2020

Using GnuCash for personal finance is a rewarding activity, especially for someone obsessed knowing where spending goes to.

Recently, after a long pause period, I decided to switch back to using aqbanking in order to automatically retrieve my transactions from my banking institutions using HBCI, instead of using the plain old CSV import.

Luckily, my current residence is Germany, where a standardized approach retrieving these (HBCI) has been going on for quite some time. The approach is similar for most of the banks:

Contact the bank and activate the HBCI service, if not already active.
Generate a pair of local signing and encryption keys, or use the alternative PIN/TAN method for banks that support it.
Import the banks public key information
Sending the keys generated in step 2 to the bank and validating them using a 3rd channel.
Enjoy an alternative online banking experience while using aqbanking to retrieve transactions, check balance, and issue SEPA transactions, among other operations.

Easier said than done, there have been multiple approaches of configuring this, however the documentation of aqbanking is lacking details when it comes to configuring the software for particular banks, and the wiki can be out of date. A huge resource is the community of homebankers, which is mostly composed of German-speaking members.

I decided to write up the steps required to set up the account, for the following two banks:

DKB (Deutsche Kredit Bank)
Commerzbank

DKB

The DKB setup is pretty straightforward. My account is protected using a PIN/password, and an additional TAN which is displayed on the TAN2Go Android application. It is assumed that you have a working TAN2Go installation on the phone.

Add an account using the following command:

aqhbci-tool4 adduser -t pintan --hbciversion=300 -b 12030000 -u  <ACCOUNT NUMBER> -N "<YOUR NAME>" -s https://banking-dkb.s-fints-pt-dkb.de/fints30

You should replace the <ACCOUNT NUMBER> with the Legitimations-ID taken from the online banking application, in the Service tab, the HBCI und FinTS page. The <YOUR NAME> can be any string which you would like to use as an account owner value.

The following steps include optionally accepting the server fingerprint, as well as changing the TAN mode to correspond to the TAN2Go app:

Use the aqhbci-tool4 listusers command to find out the Unique Id of the newly added user. (e.g. 7).
Use the aqhbci-tool4 getitanmodes -u 7 command to (optionally) accept the server fingerprint, and also to retrieve all the available TAN methods.
List the available TAN modes, using aqhbci-tool4 listitanmodes -u 7.
If using the TAN2Go generation method, use the aqhbci-tool4 setitanmode -u 7 -m 6921 command. If using another TAN method, replace the 6921 value with the one corresponding to your TAN method, listed in step 3.
Retrieve the existing accounts associated with the user using aqhbci-tool4 getaccounts -u 7. You will first be prompted for a PIN (your online banking password) and then for a TAN.

You can now list your accounts or use this user for retrieving transactions in GnuCash or aqbanking. To test this, issue the aqbanking-cli listaccs command. You should see a listing of the accounts.

Commerzbank

For personal accounts with the Commerzbank (Germany) bank, a pre-activation of HBCI functionality needs to be done before setting up a public/private key pair to interact with the bank.

Note: before calling the support number, make sure to have your “Teilnehmer Nummer” available. You can find the account number by logging into your online (web) bankaccount and click the tiny button which looks like a clock. In my case, this is a 10 digit number.

Note 2: I would also suggest changing your online account PIN (password) to a numeric one, as the telephone support system used when activating HBCI is expecting you to DTMF the PIN in. You can change it back to an alphanumeric one afterwards.

The steps for adding an account are:

Generate a new master key using the gct-tool util: gct-tool showkey -n <KEYFILE> -t ohbci. Make sure the KEYFILE value is an absolute path to the keyfile, as it will make life easier when calling aqhbci4-tool later on.
The next step is adding an account. Thanks to the great German support forum, you can find this information readily available, but scattered, without any additional explanations. Issue the aqhbci-tool4 adduser -t ohbci -n <KEYFILE> --context=1 -b <BLZ> -u <ACCOUNT NUMBER> -s hbci://hbci.commerzbank.de:3000/ -N "<YOUR NAME>" --rdhtype=10 --hbciversion=300 --cryptmoderah. Notice the addition of --cryptmoderah and --rdhtype=10 which are new parameters to support new RDH-10 public/private keypairs. This, unfortunately is not so well documented in the aqhbci-tool4 documentation. You should replace <KEYFILE> by the keyfile generated in step 1, replace the <ACCOUNT NUMBER> with the 10 digit account number, taken from the online banking application (see the note above). Replace the <BLZ> with your actual BLZ. The <YOUR NAME> can be any string which you would like to use as an account owner value.
Use the aqhbci-tool4 listusers command to find out the Unique Id of the newly added user. (e.g. 16).
Create a new pair of keys for this account, using the aqhbci-tool4 tool: aqhbci-tool4 createkeys -u 16.
Upload the public key to the banking backend using aqhbci-tool4 sendkeys -A -u 16. (optionally) Accept the server fingerprint.
Generate the initialisation letter: aqhbci-tool4 iniletter -u 16
Send the public key hash (40 or 64 characters) to the bank, or, alternatively use the online banking page to input the hash code. You can find this page by navigating to Persönlicher Bereich » Zugang beantragen & sperren » HBCI-Signatur Aktivieren.
The account should be ready for use, after confirming the signature. You can retrieve the accounts using aqhbci-tool4 getaccounts -u 16 and aqhbci-tool4 getsysid -u 16.

Note 3: The transactions in the accounts retrieved during the last step (8) started appearing 24 hours after activating HBCI access via telephone. Be patient if you can list the account numbers, but there are no transactions available.