$RCSfile: README-TNG,v $
-----------------
cvs         : $Id: README-TNG,v 1.7 2003/12/18 05:33:04 aquamaniac Exp $
begin       : Mon Oct 13 2003
copyright   : (C) 2003 by Martin Preuss
email       : martin@libchipcard.de


=========================== PLEASE NOTE =====================================
OpenHBCI is no longer actively developed. It has been replaced by AqBanking,
see http://www.aquamaniac.de/aqbanking
=========================== PLEASE NOTE =====================================



Prerequisites
=============

OpenHBCI needs the following libraries:
 - OpenSSL (please make sure that the header files are also installed,
            in most cases these are in "openssl-devel" packets)
 - Gwenhywfar (http://gwenhywfar.sf.net)



Overview
========

This is OpenHBCI-TNG, the next generation of OpenHBCI.
It needs Libgwenhywfar (http://sf.net/projects/gwenhywfar) and OpenSSL (which
should be installed on any computer).

As opposed to the first generation of OpenHBCI this version uses a message
engine based on XML-alike files.
This allows to simply add new jobs ("Geschaeftsvorfaelle") without changing
a single line of code in OpenHBCI itself. You just have to add some lines to
the XML files.

In fact OpenHBCI itself does not even know about the format of HBCI messages.
This allows us to use OpenHBCI even if the message format dramatically
changes (as expected with the next XML based version of the HBCI protocol).

OpenHBCI-TNG is very modular, most important functions are implemented as
plugins. There are dynamically loadable plugins for:
- security media (keyfile, chip card, StarMoney files)
- transport layer (currently only TCP [=internet] is implemented, but if we
  are going to implement PIN/TAN mode we would need SSL. With the current
  design of OpenHBCI we can simply replace the TCP plugin and use a SSL
  plugin instead)
- message engine (currently a XML-alike-file-based engine is provided.
  But other message engines may be created as soon as possible)
- parsers for binary data. The following parser plugins are available:
  - SWIFT parser (for MT940 data like in transaction reports from the bank)
  - DTAUS parser

OpenHBCI-TNG is focused on the HBCI protocol only. 
Earlier versions also did account administration. This is now beyond the scope
of OpenHBCI, that's now up to the programs (which are much better suited for 
this task anyway).

OpenHBCI-TNG now only does this:
- administration of banks
- administration of customers and users (including their security media)
- creating and sending jobs, receiving their responses
- error checking of server replies



Using OpenHBCI-TNG
==================

The simplest way to use OpenHBCI in applications is:
- create a HBCI::API object
- call API::setSystemName() and API::setSystemversion()
- call API::loadEnvironment()
- select a customer
- create a OutboxJob object
- set some properties of the job (see API documentation of classes OutboxJob 
  and Job)
- create a Outbox object
- call Outbox::addJob()
- call API::executeQueue()
- inspect the response data
- call API::saveEnvironment()

The tricky part is to set the job's properties and to interprete the response
data.
When using the XML-based message engine then the format of the request and
response data is defined in the XML files.

To make things easier I started working on a generic library which does some
of the administration formerly done by OpenHBCI (account management etc).
It also introduces some new OutboxJobs which work together with the account
management. This library is only intended to be used by AqMoney and KOpenHBCI,
though it might be usefull for other projects, too.
You can find it inside AqMoney-TNG, which is available from 
http://aqmoney.sf.net/.

Please note that at this moment the structures of jobs responses/request data
are defined by the contents of the descriptive XML files. 
However, as soon as we have enough experience with the XML files it will
hopefully be the other way around (since the XML message engine is only ONE
possible message engine, there are supposed to be one or two more. At that
time the structures of the request/response data should be well defined).



HBCIXML
=======

There is a tool called "hbcixml" which shows the properties to be set for
any job defined in the XML files.
This tool can also be used to anonymize log files before sending them to an
OpenHBCI developer.


"hbcixml list" 
-------------
lists all jobs which are defined in the XML files


"hbcixml show -j JOBNAME" 
-------------------------
dumps the properties used by the given job.


"hbcixml analyze --analyze LOGFILE -ol NEW_LOGFILE -od PARSED_LOGFILE"
----------------------------------------------------------------------
can be used to anonymize a logfile created by OpenHBCI.
You can use this to create a bug report. You can give the trustlevel (i.e.
how much you trust the recipient of the logfile) by the option "--trustlevel".

The following trustlevels are known:
0: no trust at all
1: low trust
2: medium trust
3: high trust
4: full trust

The XML file defines which fields of a HBCI message need how much trust to
show them in plaintext. If the element needs a higher trustlevel then is 
currently given by the option "--trustlevel" then the element will be
anonymized.

Values, recipients of transfers/debit notes normally need a lesser trustlevel
than userids but currently need a trustlevel higher than 0 (while 0 is
the default trustlevel both in the XML file and as option to the tool 
"hbcixml").

The option "-ol NEW_LOGFILE" tells the tool under which name to save the
anonymized version of the logfile.

The option "-od PARSED_LOGFILE" leads to hbcixml creating a broken down
message file. This is anonymized with the same level as the new logfile is.



Note About XML Files
====================

The structure of the XML-alike files used by OpenHBCI-TNG has been inspired
by that used by HBCI4Java (http://hbci4java.sf.net), which is a Java based
HBCI client. 
However, you can not use the files from that project, since its syntax is 
different.



Martin Preuss, Hamburg/Germany, Nov 05 2003



