.. 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 @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 ` requests. Outgoing ^^^^^^^^ This exchange's bank account is used to give money to merchants, after successful :ref:`deposits ` 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 `. 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-' 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-' 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.