summaryrefslogtreecommitdiff
path: root/operate-exchange.rst
blob: 874b837c1c922b5a030feca8e4870009039a1247 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
..
  This file is part of GNU TALER.
  Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
  TALER is free software; you can redistribute it and/or modify it under the
  terms of the GNU General Public License as published by the Free Software
  Foundation; either version 2.1, or (at your option) any later version.
  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License along with
  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>

  @author Christian Grothoff

======================
Operating the Exchange
======================

+++++++++++++
Configuration
+++++++++++++

The following data and facilities have to be set up, in order to run an exchange:

* Keying
* Serving
* Currency
* Bank account
* Coins
* Database

In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.

------
Keying
------

The exchange works with three types of keys:

* `master key`
* `sign keys`
* `denomination keys` (see section `Coins`)

`master key`: in section `[exchange]`, edit the two following values:

* `master_priv_file`: Path to the exchange's master private file.
* `master_public_key`: Must specify the exchange's master public key.

`sign keys`: the following two options under `[exchange_keys]` section control `sign keys`:

* `signkey_duration`: How long should one signing key be used?
* `lookahead_sign`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. See :ref:`keys-duration`.

-------
Serving
-------

The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this
configuration *twice*, because it opens one connection for ordinary REST calls, and one
for "/admin" and "/test" REST calls, because the operator may want to restrict the access to "/admin".

The following values are to be configured under the section `[exchange]` and `[exchange-admin]`:

* `serve`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
* `port`: Set to the TCP port to listen on if `serve` Is `tcp`.
* `unixpath`: set to the UNIX domain socket path to listen on if `serve` Is `unix`
* `unixpath_mode`: number giving the mode with the access permissiON MASK for the `unixpath` (i.e. 660 = rw-rw----).

The exchange can be started with the `-D` option to disable the administrative
functions entirely.  It is recommended that the administrative API is only
accessible via a properly protected UNIX domain socket.

--------
Currency
--------

The exchange supports only one currency. This data is set under the respective
option `currency` in section `[taler]`.

------------
Bank account
------------

Wireformat
^^^^^^^^^^

The wireformat is the protocol to be used between the exchange and the banks.
The option is `wireformat`, under section `[exchange]`. The exchange currently supports
the `test` wireformat. This wireformat is used for testing the system against a fictional bank.

.. note::
  The SEPA wireformat is work in progress.

Incoming
^^^^^^^^
The bank account where the exchange gets money from customers is configured under
the section `[exchange-wire-incoming-X]`, where `X` matches the value given to the
option `wireformat`. This section contains only one option: `X_response_file`, which
takes the path to a text file containing the exchange's bank account details in JSON
format.

The command line tool `taler-exchange-wire` is used to create such a file.
For example, the utility may be invoked as follows::

  $ taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json

Note that the value given to option `-t` must match the value in the JSON's field ``"type"``.

The generated file will be echoed by the exchange when serving :ref:`/wire <wire-req>` requests.

Outgoing
^^^^^^^^

This exchange's bank account is used to give money to merchants, after successful :ref:`deposits <deposit-par>`
operations. If `test` is the chosen wireformat, the outcoming bank account is configured by the following
options under `[exchange-wire-outcoming-test]`:

  * `exchange_account_numer`: which bank account number has the exchange
  * `bank_uri`: base URL of the bank hosting the exchange bank account

.. note::
  The rationale behind having two bank accounts is that the exchange operator, as a security
  measure, may want to instruct the bank that the incoming bank account is only supposed to
  *receive* money.

--------
Database
--------

The option `db` under section `[exchange]` gets the DB backend's name the exchange
is going to use. So far, only `db = postgres` is supported. After choosing the backend,
it is mandatory to supply the connection string (namely, the database name). This is
possible in two ways:

* via an environment variable: `TALER_EXCHANGEDB_POSTGRES_CONFIG`.
* via configuration option `db_conn_str`, under section `[exchangedb-BACKEND]`. For example, the demo exchange is configured as follows:

.. code-block:: text

  [exchange]
  ...
  db = postgres
  ...

  [exchangedb-postgres]
  db_conn_str = postgres:///talerdemo

-------------------------
Coins (denomination keys)
-------------------------

Sections specifying denomination (coin) information start with "coin\_".  By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. `[coin_eur_ct_10]` for a 10 cent piece.  However, only the "coin\_" prefix is mandatory.  Each "coin\_"-section must then have the following options:

* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION.  For example, a 10 cent piece is "EUR:0.10".
* `duration_withdraw`: How long can a coin of this type be withdrawn?  This limits the losses incurred by the exchange when a denomination key is compromised.
* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type?
* `duration_spend`: How long is a coin of the given type valid?  Smaller values result in lower storage costs for the exchange.
* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`.
* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`.
* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`.
* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin.

-------------
Keys duration
-------------

Both `signkeys` and `denom keys` have a :ref:`starting date <keys-duration>`. The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys
whose starting date is younger than `lookahead_provide` will be issued by the exchange.

.. _exchange-install:

++++++++++++
Installation
++++++++++++

Please install the following packages before proceeding with the exchange compilation.

* autoconf >= 2.69
* automake >= 1.14
* libtool >= 2.4
* autopoint >= 0.19
* libltdl >= 2.4
* libunistring >= 0.9.3
* libcurl >= 7.26 (or libgnurl >= 7.26)
* GNU libmicrohttpd >= 0.9.39
* GNU libgcrypt >= 1.6
* libjansson >= 2.7
* Postgres >= 9.4, including libpq
* libgnunetutil (from Git)
* GNU Taler exchange (from Git)

Except for the last two, these are available in most GNU/Linux
distributions and should just be installed using the respective
package manager.

The following instructions will show how to install libgnunetutil and
the GNU Taler exchange.


Before you install libgnunetutil, you must download and install the
dependencies mentioned above, otherwise the build may succeed but fail
to export some of the tooling required by Taler.

To download and install libgnunetutil, proceed as follows::

  $ git clone https://gnunet.org/git/gnunet/
  $ cd gnunet/
  $ ./bootstrap
  $ ./configure [--prefix=GNUNETPFX]
  $ # Each dependency can be fetched from non standard locations via
  $ # the '--with-<LIBNAME>' option. See './configure --help'.
  $ make
  # make install


If you did not specify a prefix, GNUnet will install to
``/usr/local``, which requires you to run the last step as
``root``.

To download and install the GNU Taler exchange, proceeds as follows::

  $ git clone git://taler.net/exchange
  $ cd exchange
  $ ./bootstrap
  $ ./configure [--prefix=EXCHANGEPFX] \
                [--with-gnunet=GNUNETPFX]
  $ # Each dependency can be fetched from non standard locations via
  $ # the '--with-<LIBNAME>' option. See './configure --help'.
  $ make
  # make install

If you did not specify a prefix, the exchange will install to
``/usr/local``, which requires you to run the last step as
``root``.  Note that you have to specify ``--with-gnunet=/usr/local``
if you installed GNUnet to ``/usr/local`` in the previous step.

+++++
Other
+++++

------------------
Reserve management
------------------

Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their reserve key.
The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database.