$Id: README,v 1.25 2003/08/23 00:54:31 aquamaniac Exp $


This file describes how to use AqMoney.



                              Overview
                              ========
    0.  Requirements                          
    1.  Global Options
    2.  Examples On How To Use AqMoney
    2.1  Create a User
    2.1.1  Create a User using a Keyfile as Security Medium
    2.1.2  Create a User using a Chipcard as Security Medium
    2.1.3  Import a User using an existing Medium (Card or File)
    2.2  Get The Server Keys
    2.3  Create Server's Ini-Letter
    2.4  Send Your Keys To The Server
    2.5  Create Your Ini-Letter
    2.6  Get Your System ID
    2.7  Get The Account List
    2.8  Get Balance
    2.9  Get Transaction Lists
    2.10 Dump Account Data
    2.11 Transfer Money
    2.11.1 Get Transfer Status
    2.11.2 Show Transfer Status
    2.12 Export Transactions to Other Programs
    2.13 Create Reports
    2.14 Generate Standing Orders
    2.15 Withdraw Standing Orders
    2.16 Change The HBCI Protocol Version To Be Used
    2.17 Convert Transaction Files
    2.18 Get/Set Medium Properties
    3. Import Reports Into Spread Sheet Programs
    4. Howto Use An Older Keyfile
    5. PIN Manager
    

0. Requirements
===============

AqMoney needs the following packages:
- OpenHBCI (required, get it from http://www.openhbci.de)
- Plugins for OpenHBCI (recommended, get them from http://www.openhbci.de)
- Libchipcard (needed if chipcard plugins for OpenHBCI are used, get it from 
  http://www.libchipcard.de)

Please note that in most cases you'll also need "devel" packages to compile 
the packages above yourself (like "openssl-devel" in addition to just
"openssl" etc).

To compile AqMoney issue the following commands:
"./configure"
"make"
"make install"

The last step usually requires you to be root.

When using the CVS version of AqMoney you'll have to use the following
command in order to create the configure script:
"make -fMakefile.dist"
In this case you also need the following packages:
 - autoconf
 - automake
 - libtool



1. Global Options
=================

AqMoney knows the following global options:
--command=ARG		tell AqMoney what to do, possible values are:
			"balance" to ask the server about the balance
			"createuser" to create a user
			"getkeys" to get the servers public keys (RDH)
			"sendkeys" to send our public keys (RDH)
			"iniletter" to create an ini letter
			"turnover" to get the turnover
                        and so on. 
                        In latest versions of AqMoney you can give the command
                        directly, without "--command="
--readonly		when this is given only those jobs are allowed which
			do not change the state of your account (forbidden
			are for example transactions)
--configfile=ARG	which OpenHBCI configfile to load (defaults to 
			"$HOME/.openhbci")
                        If this configuration file does not exist at startup
                        it will be created.
--aqmfile=ARG           path and name AqMoney's own configfile (defaults to
			"$HOME/.openhbci_aqmoney")
                        If this configuration file does not exist at startup
                        it will be created.
--debuglevel=ARG        set the debug level (defaults to 0)
                        the higher the level the more output you'll see
--help			show a little help screen
--pinlist               tells AqMoney that a PINLIST is submitted via stdin

Some commands have additional options.




2 Examples On How To Use AqMoney
================================



2.1 Create a User
---------------------

Aqmoney is able to create both RDH mode ("security disc" mode called in
other programs) and DDV mode (chip card) user. A user is one who
has one or more account(s) at a credit institute. To manage accounts you must
first create a user.


2.1.1 Create a User using a Keyfile as Security Medium
------------------------------------------------------

aqmoney "createuser" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					defaults to 280 if omitted
    --user="USERID" 			userid assigned to you by the credit
					institute
    [-customer="CUSTOMERID"]            the customer id assigned to you by
    					your bank. If you have none or the
                                        one provided to you by your bank 
                                        equals the userid you can omit it
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute
    --medium="PATH"  			absolute path and name of the file to 
					store the keys in
    --mediumtype="file" 		this is needed to create a file based
					customer
    --server="127.0.0.1"		ip address of your server in 
					dot-notatation (1.2.3.4)


2.1.2 Create a User using a Chip Card as Security Medium
--------------------------------------------------------

aqmoney "createuser" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					defaults to 280 if omitted
    --user="USERID" 			userid assigned to you by the credit
					institute
    [-customer="CUSTOMERID"]            the customer id assigned to you by
    					your bank. If you have none or the
                                        one provided to you by your bank 
                                        equals the userid you can omit it
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute
    [--medium="CARDNUMBER"]  		the card number is a quite unique
					number stored on the card. You may
					omit this number to let aqmoney find
					it out by itself
    --mediumtype="card" 		this is needed to create a card based
					customer
    --server="127.0.0.1"		ip address of your server in 
					dot-notatation (1.2.3.4)


2.1.3 Import a User using an existing Medium (Card or File)
-----------------------------------------------------------

AqMoney can not import keyfile created by proprietary software like
"StarMoney" or "Moneyplex". But it can import all keyfiles created by OpenHBCI
using software (such as GnuCash, AqMoney, GOpenHBCI and KOpenHBCI).

aqmoney "createuser" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					defaults to 280 if omitted
    --user="USERID" 			userid assigned to you by the credit
					institute if omitted aqmoney tries to
                                        get this id from the medium.
                                        Please note that the user id stored
                                        on a RSA card sometimes has nothing
                                        to do with your real user id. So with
                                        such a card you should provide the id
    [-customer="CUSTOMERID"]            the customer id assigned to you by
    					your bank. If you have none or the
                                        one provided to you by your bank 
                                        equals the userid you can omit it
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute
    [--medium="MEDIUM"]  		if the mediumtype is "file" then you
                                        must give the path and name of the
                                        keyfile to import from.
                                        if the mediumtype is "card" then you
                                        may provide the cardnumber here
                                        the card number is a quite unique
					number stored on the card. You may
					omit this number to let aqmoney find
					it out by itself
    --mediumtype="card" or "file"       what medium to import.
                                        You can also specify the plugin name
                                        of the medium to be used 
                                        (e.g. "ddvcard" for DDV chipcards)
    --server="127.0.0.1"		ip address of your server in 
					dot-notatation (1.2.3.4). If this
                                        address is stored on the medium
                                        (like with DDV cards) you can omit 
                                        this
    --import                            this flag tells aqmoney that you want
     					to import data from a medium


2.2 Get The Server Keys
-----------------------

This is only necessary when using RDH mode (keyfile, RSA card).
To determine whether your card uses RDH mode (und thus needs the serverkeys)
you can use the LibChipCard tool "hbcicard":
"hbcicard type"
If it says "RSA card" then your card uses RDH mode.

aqmoney "getkeys" 
    --user="USERID" 			userid assigned to you by the credit
					institute
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute


2.3 Create Server's Ini-Letter
------------------------------

You need this only in RDH mode, to verify the server's public keys. Your
credit institute sends you a letter containing a "HASH" line and asks you
to verify that key against data read with this command.

NOTE: If the hash data does not match you should NOT continue with 
      section 2.4 !!
      Instead try again getting the servers keys and compare the HASH value
      again. If it still does not match report this incident to your bank !

aqmoney "iniletter" 
    --user="USERID" 			userid assigned to you by the credit
					institute
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute
    --key="institute" 			this makes aqmoney show the server's
					ini letter. "user" would give the
					users ini letter
    [--output="txt"]			output format:
					"txt": produce simple ASCII output
					"html": produce html output, not
					implemented for now, but will follow
					soon


2.4 Send Your Keys To The Server
--------------------------------

This is only necessary when using RDH mode.

aqmoney "sendkeys" 
    --user="USERID" 			userid assigned to you by the credit
					institute
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute


2.5 Create Your Ini-Letter
--------------------------

This is only necessary in RDH mode. Your credit institute wants you to 
create this so-called ini letter to verify the keys you submitted to them.

NOTE: After you have created and signed this INI letter you must send it to
      the bank and wait until they activated your account. They will only do 
      so if the data on the INI letter matches that of the keys you submitted.
      Before your account is activated NO OTHER COMMAND of AqMoney will 
      succeed !
      So please be patient.

NOTE: While waiting for the bank to activate your account: 
      Please DO NOT create a new user or new keys ! 
      If you do so the newly created key replaces the one for which the ini
      letter has been submitted ! So in fact that would deactivate your 
      account !

aqmoney "iniletter" 
    --user="USERID" 			userid assigned to you by the credit
					institute
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute
    --key="user" 			this makes aqmoney show the user's ini
					letter. "institute" would give the
					servers ini letter
    [--output="txt"]			output format:
					"txt": produce simple ASCII output
					"html": produce html output, not
					implemented for now, but will follow
					soon


2.6 Get Your System ID
---------------------

This is only necessary when using RDH mode. The system id is assigned to each
program of each user which he uses to contact the server. Without this id
some credit institute servers refuse all further requests.

aqmoney "sync" 
    --user="USERID" 			userid assigned to you by the credit
					institute
    --institute="INSTITUTECODE" 	numerical code (German "Bankleitzahl")
					of your credit institute




2.7 Get The Account List
------------------------

This command asks the institute for the list of accounts that are accessable
via HBCI.

aqmoney "acclist" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--user="USERID"] 			user id, joker and wildcards are
					allowed. If omitted all user ids
					match


2.8 Get Balance
---------------

aqmoney "balance" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--account="ACCOUNT"] 		account number, joker and wildcards are
					allowed. If omitted all account numbers
					match


2.9 Get Transaction List
------------------------

This command retrieves a list of transactions that occurred in the given
period.

aqmoney "turnover" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
					the value serves as a joker
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--account="ACCOUNT"] 		account number, joker and wildcards are
					allowed. If omitted all account numbers
					match
    [--fromdate="YYYYMMDD"] 		specify the begin of the period for 
					which you want to get the turnover. 
					If omitted then the first possible date
				        is used
    [--todate="YYYYMMDD"]		specify the end of the period for 
					which you want to get the turnover. 
					If omitted then the current date
				        is used

2.10 Dump Account Data
----------------------

This command prints your account data to stdout.

aqmoney "dump" 
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
					the value serves as a joker
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--account="ACCOUNT"] 		account number, joker and wildcards are
					allowed. If omitted all account numbers
					match
    [--transactions]			show the transactions for the matching
					account(s)
    [--balance]				show the balances for the matching
					account(s)
    [--users]				show the matching users
    [--transfers]                       show transfer states
    [--msg]                             show institute messages
    [--users]                           show user list
    [--sto]                             show standing orders
    [--outformat="txt"]			output format:
					"txt": produce simple ASCII output
					"html": produce html output
    [--pos]                             dump only positive values
    [--neg]                             dump only negative values
    [--fromdate="DATE"]	                dump only transactions from the given
    					date on (YYYYMMDD)
    [--todate="DATE"]	                dump only transactions up to the
    					given date (YYYYMMDD)
   [--open]                             dump only open transfers
   [--done]                             dump only transfers which have been
                                        marked "done"
   [--failed]                           dump only transfers which have failed
   [--no-unknown]                       if there are transfers for which we
                                        have no status then they will not be
                                        shown. Otherwise you will always see
                                        them if "--transfers" is given


2.11 Transfer Money
-------------------

This command lets you transfer money from one of your accounts to another one
or vice versa.

AqMoney knows about two kinds of transactions which may be mixed in one
single file:
- simple transfer (from your account to an other's one)
- debit note (from other's accounts to your's)

A debit note draws money from an other's account to yours ("Lastschrift").
You need to contact your bank in order to be allowed to execute such a
command. If you are a private person the chance is not that good that
your bank allows you to do that ;-)

The transfer data is expected to be in a file which typically looks like this:

# this line is a comment which is ignored by AqMoney
# first transfer
[TRANSACTION]                        # each X-action must be preceeded by this
institute="09950001"                 # these lines describe ...
id="101010719"                       # the source account
otherinstitute="09950001"            # this is the target institute
otherid="102010719"                  # and the target's account number
value="11,22:EUR"                    # value to transfer
othername="Test User"                # recipient's name
description="Greetings from Aqmoney" # purpose, each "description" entry ...
description="First transaction"      # holds one line of purpose
#
# second transfer
[TRANSACTION]
institute="09950001"
id="102010719"                       # here we use an other source account !!
otherinstitute="09950001"
otherid="102010719"
value="11,22:EUR"
othername="Test User"
description="Greetings from Aqmoney"
description="Second transaction"
#
# debit note
[debitnote]
institute="09950001"                 # here we pull the money back ;-)
id="102010719"
otherinstitute="09950001"
otherid="102010719"                      
value="11,22:EUR"
othername="Test User"
description="Greetings from Aqmoney"
description="Debit note"



As you can see you can put multiple transactions into one file.
After handling these transfers AqMoney creates one or two files to show the
results:
 TAKENFILE          Contains all transfers successfully transfered to 
                    the bank. 
                    Please note that this does not necessarily mean that your
                    transfer requests approved ! It only means that your bank
                    has formally accepted the requests and is considering their
                    execution ;-)
 NOTTAKENFILE       Contains all transfers which have not been
                    successfull (for any reason, but in most cases this is
                    because the bank rejected this transfer)
                    If all transfers succeeded this file will not be created.
 TAKENFILE is the name of the file given by the option "--taken=FILENAME"
 NOTTAKENFILE is the name of the file given by the option "--nottaken=FILENAME"


aqmoney "transfer"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted "280" is assumed
    --tfile="FILE"                      read transfers from file
    [--taken="FILE"]                    this file will be created with the
                                        list of transfers that where accepted
                                        by the bank. 
                                        If omitted this file will not be
                                        created
    [--nottaken="FILE"]                 this file will be created with the
                                        list of transfers that where rejected
                                        by the bank
                                        If omitted this file will not be
                                        created

2.11.1 Get Transfer Status

AqMoney keeps track of all transfers you issue with this program.
In order to make AqMoney update the status of each transfer you must use the
command "getstatus"

aqmoney "getstatus"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--customer="CUSTOMERID"] 		customer id, joker and wildcards are
					allowed. If omitted all customer ids
					match
    [--fromdate="DATE"]	                get only states from the given
    					date on (YYYYMMDD). 
                                        This is only supported if the HBCI 
                                        protocol version is 2.1 or higher
    [--todate="DATE"]	                get only states up to the given
    					date (YYYYMMDD)
                                        This is only supported if the HBCI 
                                        protocol version is 2.1 or higher

This updates the transfer states of all transfers the given customer (or any 
customer) has issued.


2.11.2 Show Transfer Status

To view the status of your transactions you may give additional arguments
to the command "dump":
   [--transfers]                        make "dump" show transfer states
   [--open]                             show only open transfers
   [--done]                             show only transfers which have been
                                        marked "done"
   [--failed]                           show only transfers which have failed
   [--no-unknown]                       if there are transfers for which we
                                        have no status then they will not be
                                        shown. Otherwise you will always see
                                        them if "--transfers" is given



2.12 Export Transactions to Other Programs
------------------------------------------

This command exports all transactions of an account to a file. The format
of the file can be given by a command line argument.

aqmoney "texport"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
					the value serves as a joker
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--account="ACCOUNT"] 		account number, joker and wildcards are
					allowed. If omitted all account numbers
					match
    [--outformat="FORMAT"]		give the format of the output. 
    					Valid formats are:
                                        - qhacc (export to format of the
                                          program QHAcc)
                                        - txt (export in CSV format, this can
                                          be read by most spread sheet
                                          programs like StarCalc)
    [--outfile="FILE"]			name of the output file
                                        if omitted or "-" then output goes
                                        to stdout
    [--pos]                             export only positive values
    [--neg]                             export only negative values
    [--tab]                             when outformat is "txt" then this
                                        option makes aqmoney use TABs instead
                                        of semicolons as field delimiter
    [--noquote]		                when outformat is "txt" then aqmoney
                                        will not quote the fields (you should
                                        use "--tab" together with this option)
    [--noheader]		        when outformat is "txt" then this
    					option makes AqMoney omit the header.
    [--fromdate="DATE"]	                export only transactions from the 
                                        given date on (YYYYMMDD)
    [--todate="DATE"]	                export only transactions up to the
    					given date (YYYYMMDD)

    [--transfers]                       if this is given then the list of
                                        transfers issued by AqMoney is 
                                        exported. In this case the following
                                        flags may be used:
    [--open]                            dump only open transfers
    [--done]                            dump only transfers which have been
                                        marked "done"
    [--failed]                          dump only transfers which have failed
    [--no-unknown]                      if there are transfers for which we
                                        have no status then they will not be
                                        shown. Otherwise you will always see
                                        them if "--transfers" is given


2.13 Create Reports
-------------------

This command creates reports.

aqmoney "report"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
					the value serves as a joker
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--account="ACCOUNT"] 		account number, joker and wildcards are
					allowed. If omitted all account numbers
					match
    [--output="txt"]			output format:
					"txt": produce simple ASCII output
					"html": produce html output
    [--pos]                             dump only positive values
    [--neg]                             dump only negative values
    [--fromdate="DATE"]	                dump only transactions from the given
    					date on (YYYYMMDD)
    [--todate="DATE"]	                dump only transactions up to the
    					given date (YYYYMMDD)
    [--rflags="FLAGS"]                  specify the type of report. It may
                                        contain the following characters:
                                        "y" to generate year reports
                                        "m" to generate month reports
                                        "d" to generate day reports
                                        "n" when generating day reports also
                                            show days when no transactions
                                            occurred.
                                        Default is "ymd"

2.14 Generate Standing Orders
-----------------------------

This commands creates standing orders ("Dauerauftraege").

The standing order data is expected to be in a file which typically looks 
like this:

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# this line is a comment which is ignored by AqMoney
[standing_order]
# 
# Set the id of the job you want to modify or delete.
# NOTE: Some banks don't use jobids. In this case, you have
# to set all fields (otherid, othername,...) to current values 
# if you want to delete the order (modifying is not possible).
# NOTE: Not used when creating a new order
# NOTE: When modifying a standing order, this can not be changed
#jobid="20020520"
#
# Your bank code (german BLZ)
# NOTE: When modifying a standing order, this can not be changed
institute="09950003"
# 
# The country-code of your bank (280 for Germany)
# NOTE: If not specified, the default "280" is used
# NOTE: When modifying a standing order, this can not be changed
country="280"
#
# Your account id
# NOTE: When modifying a standing order, this can not be changed
id="101030086"
#
# The id of the account to which money will be transfered to
otherid="104030086"
# 
# Suffix for the above "otherid"
# Only set if the other's account consists of multiple 
# subaccounts 
# (normaly not used and only allowed for HBCI version >= 2.2)
#othersuffix=""
# 
# The bank code (german BLZ) of the bank where 
# money will be transfered to.
otherbank="9950003"
# 
# The country-code of the bank where money will be transfered to
# (280 for Germany)
# NOTE: If not specified, the default "280" is used
othercountry="280"
# 
# Name of the owner of the accout to which money will be transfered to
othername="Alice Green"
# 
# A second name, optional
#othername="Bob Green"
# 
# The amount of money you want to transfer
# Format: XX,XX:CUR (for XX,00:EUR you might also say "XX,:EUR")
value="50000,:EUR"
# 
# A textual description for this order. Enter as many
# description-items as you want (and as are supported 
# by your bank)
description="RENT FOR HOUSE"
description="HAMBURG, RATHAUS"
# 
# Transaction-code that identifies the kind of order.
# Should be "52" in most cases (I don't know any other;-)
# NOTE: If not specified, the default "52" is used
code="52"
# 
# Date when the order should be executed for the first time
# FORMAT: yyyymmdd
firstdate="20020701"
# 
# Date when the order should be executed the last time
# (optional)
# FORMAT: yyyymmdd
#lastdate="20030701"
# 
# Date when the order should be executed next time or
# when the order should be deleted (not supported by all banks)
# FORMAT: yyyymmdd
# NOTE: Don't use it when creating a new standing order!
#nextdate="20020801"
# 
# "0" for weekly, "1" for monthly execution of this order
cycle="1"
# 
# 1 for "every week/month", 2 for "every 2nd week/month"...
period="1"
# 
# Day within week/month when the order should be executed
# NOTE: 99 is "last in month", 98 is "day before last in month"
# NOTE: "execday" has to match the date given in 
# "firstdate" and/or "nextdate"!
execday="1"
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

aqmoney "newstdorder"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted "280" is assumed
    --tfile="FILE"                      read standing orders from file


2.15 Withdraw Standing Orders
-----------------------------

This commands withdraws standing orders ("Dauerauftraege").
It uses the same input file used when creating a standing order (please see
above for the format).

aqmoney "delstdorder"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted "280" is assumed
    --tfile="FILE"                      read standing orders from file


2.16 Change The HBCI Protocol Version To Be Used
------------------------------------------------

The version is used on a per bank basis. This command checks whether the
given version is supported by the bank. An error will be reported if it
is not. After changing the HBCI protocol version this command updates the
bank information by contacting the server, since some operational bank 
parameters depend on the HBCI protocol version used.

aqmoney "chgversion"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    --hversion="VERSIONCODE"            HBCI protocol version code. The
                                        following scheme applies:
                                        
                                        Version | Value needed
                                        --------|-------------
                                          2.01  |     201
                                          2.10  |     210
                                          2.20  |     220

2.17 Convert Transaction Files
------------------------------
AqMoney can be used to convert transaction files.
Currently, only DTAUS files can be read, while standard AqMoney transaction
files can be read and written.

aqmoney convert
    [--infile="FILE"]                   name of the file to read.
                                        If omitted "-" is assumed, which
                                        indicates the use of stdin
    --informat="FORMAT"                 format of the input file:
                                        "dta"  : simple DTAUS file supported
                                                 by most accounting programs
                                        "trans": AqMoney's own format
    [--outfile="FILE"]                  name of the file to write
                                        If omitted "-" is assumed, which
                                        indicates the use of stdout
    --outformat="FORMAT"                format of the output file, see
                                        --informat

2.18 Get/Set Medium Properties
------------------------------
Some media have specific properties (kind of attributes which modify their
behaviour). You can use the command "getproperty" to retrieve the value of
a given property and "setproperty" to modify a property.
The supported properties highly depend on the media type. Please refer to
the documentation of your plugin for a list of supported properties.

aqmoney "getproperty"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--customer="CUSTOMERID"] 		customer id, joker and wildcards are
					allowed. If omitted all customer ids
					match
    --pname=NAME                        name of the property

aqmoney "setproperty"
    [--country="COUNTRY"] 		give the country code (280 for Germany)
					if omitted all country codes match
    [--institute="INSTITUTECODE"]	give the institute code, joker and
					wildcards are allowed. If omitted all
					institute codes match
    [--customer="CUSTOMERID"] 		customer id, joker and wildcards are
					allowed. If omitted all customer ids
					match
    --pname=NAME                        name of the property
    --pvalue=VALUE                      new value for the property




3. Import Reports Into Spread Sheet Programs
============================================

This example shows how to import a report created by AqMoney into StarCalc,
but it works in similar ways with other programs, too.

First create a report. In this example we create a day report for the March
of 2003:

aqmoney report 
        --rflags="d" 
        --month=3 
        --year=2003
        --outformat=csv 
        --outfile=report-2003-03.csv
        
If you have multiple accounts you should specify the account to be used with 
"--account=xyz". 
Please note that the extension of the file should be ".csv", this way at least
Star Office directly recognizes the file as a "CSV" file. 
Please also note that for Star Office 5.2 you are required to omit the rflag 
"c", because for some reason it is unable to import a "123,45 EUR" statement.

Now open the report in Star Office via "File/Open". In the file open dialog
select the report just created. The only thing you have to change in the now
popping up dialog is to uncheck "Komma" and to check "Semicolon". The preview
window should now show the report as it will be imported. Simply klick "Ok".
That's it.



4.   Howto Use An Older Keyfile
===============================

If after a system crash your current keyfile is lost but you still have an
older version, then you must use the following command to reactivate the old
keyfile:

  aqmoney modifymedium --institute=INSTCODE --user=USERID --newseq=XYZ

I suggest to use a value of 1000 for XYZ the first time you issue this 
command. Every next time you should use a value which is about 1000 higher.

Explanation: SEQ is the so called signature sequence counter. Every time
AqMoney sends a message to the bank this counter is incremented. The bank
does not accept a message whose signature counter is less than any other 
counter before (to protect against replay-attacks).

So while using your keyfile the sequence counter is incremented, while
in the old copy of that keyfile the sequence counter is still lower.
So you have to increment the sequence counter in the keyfile by using the
command above. If it does not work try an even higher value for XYZ.



5. PIN Manager
==============

I have been asked so many times for a feature for pin automation.
So here it is, a compromise of security needs an usability.

You can now provide a list of all PINs you are going to use in the session
via stdin.

The format of the stream expected via stdin is this:

------------------------------ X8
PINLIST
MEDIUM1=PIN1
MEDIUM2=PIN2

------------------------------ X8
et cetera.

MEDIUM is the exact mediumname. For a chipcard this is the card number, for
a key file this is the full and absolute path to the keyfile.
Use "aqmoney mkpinlist" to create an empty pinlist.

PIN1 and PIN2 are the PINs for the media, respectively.
Each line MUST only include ONE PIN definition.
The PIN list is terminated by a single empty line.

You must tell AqMoney that a PIN list is submitted by giving the option
"--pinlist". This makes sure that the PIN list does not interfere with
other data transmitted via stdin/stdout.

An example:
echo -e "PINLIST\n123456789=PIN1\n/home/user/keyfile.medium=PIN2\n" |
 aqmoney turnover --pinlist

The option "-e" tells "echo" to output control characters, like the "\n" we
are using in this example. The output of "echo" is piped through to aqmoney
via the "|" character.

I suggest using a file which is only read/writeable by YOU and which can be
piped to aqmoney, like this:

cat YOURPINFILE | aqmoney turnover --pinlist


_____________________________________________________________________________
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
=============================  WARNING ======================================
Please note that anybody who is able to read a file which contains your PINS 
is able to make use of the security medium !

So if you place a command like those in the examples above in any file you
MUST make sure that no unauthorized person can read it !

Please note, that using the PIN manager with a chip card while you have a card
reader with a keypad reduces the security level by magnitudes !!

As a compromise you might create a new user which has no SHELL so that he
can not login to your system. Then make him own AqMoney and set the SUID bit.

This can be done by:
groupadd aqmoney
useradd aqmoney -s /bin/false -d /home/aqmoney
chown aqmoney:aqmoney /PATH/TO/aqmoney
chmod u+s /PATH/TO/aqmoney
chmod o-rwx /PATH/TO/aqmoney

Copy your OpenHBCI configuration file into the folder "/home/aqmoney" and
change the owner of that file, too:
chown aqmoney:aqmoney /home/aqmoney/*
chmod u=rwx /home/aqmoney/*

Now aqmoney can only be started by someone who is member of the group
"aqmoney". You should also change the rights for the pin file like
chown aqmoney:aqmoney YOURPINFILE
chmod 600 YOURPINFILE

Now to be able to use aqmoney you must put yourself into the group "aqmoney".
Please use one of the graphical frontends (like KUser) to do that.

After that has been done only members of the group "aqmoney" can start
aqmoney, but they still cannot read the PIN file.
_____________________________________________________________________________
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
=============================================================================









