How to setup payment for a Mix cascade

General

Setting up payment for a mix cascade involves setting up a so called "payment instance" (BI) and configuring the first mix of a cascde to support payment. The payment instance manages accounts for users. For a detail describtion of how the payment works lock here:

Setting up the payment instance (BI)

Installation

Voraussetzungen

In order to succesful instal the BI java server application one needs a running server maschin with:

• korrekt installiertes Java2 SDK ab Version 1.4 (http://java.sun.com)
• JDBC driver for postgresql (http://jdbc.postgresql.org)
• laufender postgresql-Server (zum Testen wurde Version 7.3 benutzt)
• the BI java server BI.jar (http://anon.inf.tu-dresden.de/develop)

Setting up the database

First of all you have to create a user and a database within the postgresql system. To do this you can use the createuser and createdb commands as follows:

createuser -A -D <PayUser>
createdb -O <PayUser> <PayDB>

Now you need to create some tables within the newly created database <PayDB>. You can use the database-tables.sql for this. (The script could be found in the /documentation/BezahlInstanz directory of the JAP sources).

You can use the psql tool for executing the script as follow:

psql -U <PayUser> -d <PayDB>

[You should get the following Postgresql Prompt:]

PayDB =>

[On this prompt you can type "\i database-tables.sql" and hit enter. This creates the tables.]

PayDB =>\i database-tables.sql

Now the tables are created and the database is ready for use.

Creating the cryptogaphic keys and certifcates for the BI

Die Bezahlinstanz benötigt einen privaten Schlüssel zum Signieren und ein öffentliches Zertifikat, das an die Betreiber der Abrechnungsinstanzen weitergegeben werden muss. You can create this key and certifcate by using openssl as follows:

openssl dsaparam -genkey 1024 -out bi.key
openssl req -x509 -new -out bi.cer -key bi.key -subj "/CN=BI/"
openssl pkcs12 -export -in bi.cer -inkey bi.key -name BI -nodes -noiter -out bi.pfx

Now you should have two files called bi.cer and bi.pfx, where bi.cer is the public key certificate and bi.pfx contains the private key of the BI.

Configuration

The file config.example contains an example configuration which you could use as starting point for your configuration. The file could be found in the documentation/BezahlInstanz directory of the JAP sources. The config.example file is hopefully self-explaining.

Executing of the BI java server

You can start the BI by executing the BI.jar file within your java environment. As first argument you have to specify the configuration file to use:

java -jar BI.jar bi.config

Now you are finished with setting up the BI java server. You should have a look at the log file, to see if the BI is running. (The location and name of the log file could be specified in the configuration file)

Setting up the mix cascade with payment support

First of all you should be familar with setting up an ordinary mix cascade. This procedure is explained here.

Compiling the mix with payment support

In order to use the payment support of a mix cascade the first mix of that cascade has to be compile with payment support enabled. You can achieve this, if you call configure with the --enable-payment argument:

./configure --enable-payment

Note that you need the necessary postgresql development files (headers and libraries) installed on the maschine.

Setting up the database

The first mix stores some payment relevant information within a posgresql database. Therefore such a database needs to be available.

You need to create a user and a database within the postgresql system which will be used for storing the payment data. You can use the createuser and createdb commands as described above.

You need also to create some tables within the <PayDB> database. You can use the psql command as described above:

psql -U <PayUser> -d <PayDB>
PayDB => \i paymentTablesReadme.sql

[Note: You will find the paymentTablesReadme.sql file in the documentation directory of the mix sources.]

Now the postgresql database is ready for use.

Setting up the first mix

Configuration of the first mix is done as described in the ordinary mix setup procedure (http://anon.inf.tu-dresden.de/develop/howtooperateamix.html). Additionally the mix needs some information about the BI and the database which you have created in the step before. You should use the MixConfig tool to make the necessary changes on the configuratiuon file.

Start the MixConfig tool, load your existing first mix configuration file, switch to the expert view and click on the payment panel. Enable payment and import the public key certifcate of the BI you wnat to use (In our example the bi.cer file.)

Enter the hostname and portnumber of the BI (called JPI in the MixConfig tool). Alos you have to enter the information of the postgresql database you have created in the step before.

At the end enter some apropriated values in the General settings. The SoftLimit describes after how many unpayed bytes the mix requests some payment form a JAP. The HardLimit describes after how many unpayed bytes the mix will close the connection to the JAP. Naturally you should set HardLimit>>SoftLimit.

The SettleInterval describes how often the mix will contact the BI to cash the payments received by the JAPs.

Save your configuration file and start the mix cascade as usual. You should see in the log files, that the mix has connected to the postgresql database.

Using JAP with a payment cascade.

First of all you need a JAP >=00.05.055. If you do not use the default BI, than you have to make some modifications in the source code of JAP:

• exchange the BI.cer with the public certifcate of your BI
• set PIHOST and PIPORT in JAPConstants to the values of your BI

Start JAP with the -pay option:

java -jar JAP.jar -pay