attachment:README_HBCI.txt von GnuCash

   1 README.HBCI
   2 -----------
   3 
   4 1. Introduction
   5 2. Requirements
   6 3. Quick Tour
   7 4. Known Banks
   8 5. Call for Feedback
   9 6. Known Problems
  10 7. Credits
  11 
  12 1. Introduction
  13 -----------
  14 
  15 Since version 1.7.2, GnuCash features HBCI online banking
  16 support. This makes it the world's first *free* HBCI-enabled personal
  17 finance manager.
  18 
  19 HBCI (Home Banking Computer Interface) is a standard used by German
  20 banks for offering online banking service. Through this standard,
  21 business actions like statement retrieval, initiate bank transfer, or
  22 direct debits can be invoked by any HBCI-compliant client application,
  23 i.e. now also from GnuCash. Authentification and encryption is done
  24 through a bank-issued chip card or a self-generated file-based RSA key
  25 pair. (In the latter case, the user prints out his public key finger
  26 print on paper, signs it, and sends it to his bank.)
  27 
  28 Please note that the programmers of GnuCash cannot give warranties for
  29 anything. In particular, some banks are running a poorly implemented
  30 HBCI on their servers, which does not give you any proper feedback
  31 when a transfer order has been rejected and will not be
  32 executed. Please do not rely on time-critical money transfers through
  33 HBCI for now.
  34 
  35 2. Requirements
  36 ------------
  37 
  38 OpenHBCI 0.9.11 or later: Get openhbci and openhbci-devel from
  39 http://sourceforge.net/projects/openhbci
  40 
  41 which in turn requires:
  42 OpenSSL any 0.9.x, http://www.openssl.org
  43 
  44 For chipcard support, you also need openhbci-plugin-ddvcard from
  45 http://sourceforge.net/projects/openhbci
  46 
  47 which in turn requires 
  48 Libchipcard 0.9 or later, http://sourceforge.net/projects/libchipcard
  49 
  50 Then you can build GnuCash 1.7.x/1.8.x with:
  51    ./configure --enable-hbci --with-openhbci-prefix=/your/openhbci/prefix 
  52 
  53 Optionally, for automated checking of destination account numbers you
  54 need the package ktoblzcheck,
  55 http://sourceforge.net/projects/ktoblzcheck
  56 
  57 And you need to apply at your Bank to get HBCI access. The bank will 
  58 provide you with some paper work which is needed during HBCI setup in 
  59 GnuCash. (For problems during compile see 6. Known Problems below.)
  60 
  61 3. Quick Tour
  62 ----------
  63 
  64 HBCI support is accessible through a few new menu items:
  65 
  66 * Setup: In the main window with the account hierarchy, the "Tools" menu 
  67 (German: "Werkzeuge") now contains the item "HBCI Setup" ("HBCI 
  68 Einrichtung"). This menu item opens the HBCI Setup druid which will 
  69 guide you through the setup.
  70 
  71    - Chip card users will need to run this only once. (see 6. Known
  72      Problems below if this doesn't work)
  73 
  74    - Users with self-generated file-based keys need to run this for the
  75      first time to generate their keys and have their Ini-Letter printed,
  76      which they need to send to their bank. After some days when the bank
  77      has processed that letter, they need to run the HBCI Setup druid
  78      a second time.
  79 
  80    - Either way, eventually you are presented with a list of
  81      HBCI-accessible accounts, and can choose which of your gnucash
  82      account should be matched with each HBCI account.
  83 
  84 * Account functions: In the register window of your GnuCash accounts, 
  85 you now find the submenu item "Online Actions" ("Online Aktionen") in 
  86 the menu "Actions" ("Aktionen"). Each item in this submenu invokes a 
  87 particular HBCI action: "Get Balance", "Get Transactions", "New 
  88 Transfer", "New Direct Debit" ("Abfrage Saldo", "Abfrage Kontoumsätze", 
  89 "Neue Überweisung", "Neue Lastschrift"). Of course those menu items will 
  90 only do anything if that particular GnuCash account was matched to a 
  91 HBCI account in the setup druid; otherwise, simply nothing will happen. 
  92 How to perform each action will be explained in the respective 
  93 dialog windows.
  94 
  95 * Preference: By default, the user has to enter his password/PIN each 
  96 time a HBCI action is performed. If you prefer to have your password 
  97 cached in memory during your gnucash session, you can enable this by 
  98 activating the appropriate button in the Edit->Preference dialog 
  99 ("Bearbeiten->Einstellungen") in the tab "Online Banking & Importing". 
 100 Of course the password/PIN is *never ever* stored on disk anywhere.
 101 
 102 * HBCI Connection window preference: The HBCI Connection window can
 103 either disappear once the connection is closed, or it can still be
 104 left open so that you can read the bank's feedback messages about the
 105 order. The setting of this respective checkbox in the Connection
 106 window is remembered from session to session.
 107 
 108 * Debug Preference: If HBCI connectivity does not work the way you
 109 expected it to work, you can enable a whole lot of HBCI debugging
 110 output. First, on the "General" page of the preferences, activate the
 111 checkbox for "Show Advanced Setting". Then, on the newly appearing
 112 "Advanced" page, activate "HBCI Verbose Debug Messages" to get much
 113 more debugging output.
 114 
 115 4. Known Banks
 116 -----------
 117 
 118 OpenHBCI/Gnucash is successfully being used with:
 119 - Deutsche Bank
 120 - Kreissparkasse Hannover
 121 - Hamburger Sparkasse
 122 - Sparkasse Wilhelmshaven
 123 - and many more, see http://linuxwiki.de/OpenHBCI
 124 
 125 5. Call for Feedback
 126 -----------------
 127 
 128 If you encounter an error, you can report it in German language on
 129 gnucash-de@gnucash.org (Subscriber-only list; please subscribe on
 130 http://www.gnucash.org/cgi-bin/mailman/listinfo/gnucash-de ) and on on
 131 openhbci-general@lists.sf.net. Please remember to include the version
 132 numbers of gnucash and openhbci as well as any console output and/or
 133 HBCI connection log (can be obtained through the HBCI Verbose Debug
 134 Messages preference mentioned above).
 135 
 136 Also, if you managed to successfully setup a bank that we don't have in 
 137 our list yet, please let us know as well. We appreciate any feedback on 
 138 this new functionality.
 139 
 140 6. Known Problems
 141 --------------
 142 
 143 * If the compilation of GnuCash fails with 'cc1: changing search order
 144   for system directory ...' as one of the last message lines, then
 145   call ./configure with the additional option
 146   --enable-error-on-warning=no and recompile.
 147 
 148 * If you don't see the menu items mentioned above, then GnuCash was
 149   not built/compiled with --enable-hbci. Please try to compile GnuCash
 150   by yourself or contact the place where you got your pre-compiled
 151   version of GnuCash from.
 152 
 153 * If you cannot select "Chip Card" as security medium: For openhbci
 154   0.9.10 and newer: You need to install the package
 155   openhbci-plugin-ddvcard, too. 
 156   For openhbci earlier than 0.9.10, it means that your installed
 157   version of the OpenHBCI library has been compiled without chipcard
 158   support. You will need to recompile OpenHBCI while libchipcard is
 159   installed, and then you (probably) need to recompile GnuCash.
 160 
 161 * Currently each HBCI action can only be executed while you are
 162   online; support for off-line preparation and queueing is not yet
 163   implemented.
 164 
 165 If you think you can do better on any of these issues -- why not give it 
 166 a try and start coding on yet more HBCI features? Gnucash only requires 
 167 some C and Gtk/Gnome knowledge, and other developers in the IRC channel 
 168 #gnucash, irc.gnome.org, will always assist you with problems arising 
 169 during coding. You don't need to know anything about HBCI since OpenHBCI 
 170 will do everything for you. Also, I (Christian Stimming) will withdraw 
 171 from HBCI/Gnucash development due to personal/time constraints in the 
 172 medium term. So if you want more features, why don't *you* start coding 
 173 today? We definitely welcome any new developer who contributes even the 
 174 smallest improvements.
 175 
 176 7. Credits
 177 -------
 178 
 179 The excellent OpenHBCI library is written by Fabian Kaiser 
 180 <fabian.kaiser@gmx.de>, Martin Preuss <openhbci@aquamaniac.de>, and 
 181 Christian Stimming <stimming@tuhh.de>. Libchipcard is written by Martin 
 182 Preuss <openhbci@aquamaniac.de>.
 183 
 184 By Christian Stimming <stimming@tuhh.de>
 185 May 31st, 2003