     [file version.texi not included]

The GNU Taler manual for Web shops
**********************************

This manual is for the GNU Taler merchant backend (version VERSION, UPDATED),

Copyright © 2016 INRIA

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Introduction
************

About GNU Taler
===============

GNU Taler is an open protocol for an electronic payment system with a free software reference implementation.  GNU Taler offers secure, fast and easy payment processing using well understood cryptographic techniques.  GNU Taler allows customers to remain anonymous, while ensuring that merchants can be held accountable by governments. Hence, GNU Taler is compatible with anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as data protection regulation (such as GDPR).

GNU Taler is not yet production-ready, after following this manual you will have a backend that can process payments in ``KUDOS'', but not regular currencies.  This is not so much because of limitations in the backend, but because we are not aware of a Taler exchange operator offering regular currencies today.

About this manual
=================

This tutorial targets system administrators who want to install a GNU Taler merchant backend.

We expect some moderate familiarity with the compilation and installation of free software packages. An understanding of cryptography is not required.

This first chapter of the tutorial will give a brief overview of the overall Taler architecture, describing the environment in which the Taler backend operates.  The second chapter then explains how to install the software, including key dependencies.  The third chapter will explain how to configure the backend, including in particular the configuration of the bank account details of the merchant.

The last chapter gives some additional information about advanced topics which will be useful for system administrators but are not necessary for operating a basic backend.

Architecture overview
=====================

Taler is a pure payment system, not a new crypto-currency. As such, it operates in a traditional banking context.  In particular, this means that in order to receive funds via Taler, the merchant must have a regular bank account, and payments can be executed in ordinary currencies such as USD or EUR.  For testing purposes, Taler uses a special currency ``KUDOS'' and includes its own special bank.

The Taler software stack for a merchant consists of four main components:

  * A frontend which interacts with the customer's browser. The frontend enables the customer to build a shopping cart and place an order.  Upon payment, it triggers the respective business logic to satisfy the order.  This component is not included with Taler, but rather assumed to exist at the merchant. This manual describes how to integrate Taler with Web shop frontends.

  * A back office application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied.  This component is again not included with Taler, but rather assumed to exist at the merchant. This manual will describe how to integrate such a component to handle payments managed by Taler.

  * A Taler-specific payment backend which makes it easy for the frontend to process financial transactions with Taler.  The next two chapters will describe how to install and configure this backend.

  * A DBMS which stores the transaction history for the Taler backend. For now, the GNU Taler reference implemenation only supports Postgres, but the code could be easily extended to support another DBMS.

The following image illustrates the various interactions of these key components:

Basically, the backend provides the cryptographic protocol support, stores Taler-specific financial information in a DBMS and communicates with the GNU Taler exchange over the Internet.  The frontend accesses the backend via a RESTful API.  As a result, the frontend never has to directly communicate with the exchange, and also does not deal with sensitive data.  In particular, the merchant's signing keys and bank account information is encapsulated within the Taler backend.

Installation
************

This chapter describes how to install the GNU Taler merchant backend.

Installing Taler using Docker
=============================

This section provides instructions for the merchant backend installation using `Docker`.

For security reasons, we run Docker against a VirtualBox instance, so the docker command should connect to a docker-machine instance that uses the VirtualBox driver.

Therefore, the needed tools are: ``docker``, ``docker-machine``, and ``docker-compose``.  Please refer to Docker's official (https://docs.docker.com/)documentation in order to get those components installed, as that is not in this manual's scope.

Before starting to build the merchant's image, make sure a ``docker-machine`` instance is up and running.

Because all of the Docker source file are kept in our ``deployment`` repository, we start by checking out the git://taler.net/deployment codebase:

     $ git clone git://taler.net/deployment

Now we actually build the merchant's image.  From the same directory as above:

     $ cd deployment/docker/merchant/
     $ docker-compose build

If everything worked as expected, the merchant is ready to be launched.  From the same directory as the previous step:

     # Recall: the docker-machine should be up and running.
     $ docker-compose up

You should see some live logging from all the involved containers. At this stage of development, you should also ignore some (harmless) error message from postresql about already existing roles and databases.

To test if everything worked as expected, it suffices to issue a simple request to the merchant, as:

     $ curl http://$(docker-machine ip)/
     # A greeting message should be returned by the merchant.

Generic instructions
====================

This section provides generic instructions for the merchant backend installation independent of any particular operating system. Operating system specific instructions are provided in the following sections.  You should follow the operating system specific instructions if those are available, and only consult the generic instructions if no system-specific instructions are provided for your specific operating system.

Installation of dependencies
----------------------------

The following packages need to be installed before we can compile the backend:

  * autoconf \ge 2.69

  * automake \ge 1.14

  * libtool \ge 2.4

  * autopoint \ge 0.19

  * libltdl \ge 2.4

  * libunistring \ge 0.9.3

  * libcurl \ge 7.26 (or libgnurl \ge 7.26)

  * GNU libmicrohttpd \ge 0.9.39

  * GNU libgcrypt \ge 1.6

  * libjansson \ge 2.7

  * Postgres \ge 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 sections will provide detailed instructions for installing the libgnunetutil and GNU Taler exchange dependencies.

Installing libgnunetutil
------------------------

Before you install libgnunetutil, you must download and install the dependencies mentioned in the previous section, 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.

Installing the GNU Taler exchange
---------------------------------

After installing GNUnet, you can download and install the exchange 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.

Installing the GNU Taler merchant backend
-----------------------------------------

The following steps assume all dependencies are installed.

Use the following commands to download and install the merchant backend:

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

Note that you have to specify --with-exchange=/usr/local and/or --with-exchange=/usr/local if you installed the exchange and/or GNUnet to /usr/local in the previous steps.

Installing Taler on Debian GNU/Linux
====================================

Debian wheezy is too old and lacks most of the packages required.

On Debian jessie, only GNU libmicrohttpd needs to be compiled from source.  To install dependencies on Debian jesse, run the following commands:

     # apt-get install \
       autoconf \
       automake \
       autopoint \
       libtool \
       libltdl-dev \
       libunistring-dev \
       libcurl4-gnutls-dev \
       libgcrypt20-dev \
       libjansson-dev \
       libpq-dev \
       postgresql-9.4
     # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz
     # wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
     # gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC
     # tar xf libmicrohttpd-latest.tar.gz
     # cd libmicrohttpd-0*
     # ./configure
     # make install

For more recent versions of Debian, you should instead run:

     # apt-get install \
       autoconf \
       automake \
       autopoint \
       libtool \
       libltdl-dev \
       libunistring-dev \
       libcurl4-gnutls-dev \
       libgcrypt20-dev \
       libjansson-dev \
       libpq-dev \
       postgresql-9.5 \
       libmicrohttpd-dev

For the rest of the installation, follow the generic installation instructions starting with the installation of libgnunetutil.  Note that if you used the Debian wheezy instructions above, you need to pass --with-microhttpd=/usr/local/ to all configure invocations.

How to configure the merchant's backend
***************************************

The installation already provides reasonable defaults for most of the configuration options. However, some must be provided, in particular the database account and bank account that the backend should use.  By default, the file $HOME/.config/taler.conf is where the Web shop administrator specifies configuration values that augment or override the defaults.  The format of the configuration file is the well-known INI file format.  You can edit the file by hand, or use the taler-config commands given as examples. For more information on taler-config, see Using taler-config.

Backend options
===============

The following table describes the options that commonly need to be modified. Here, the notation [$section]/$option denotes the option $option under the section [$section] in the configuration file.

Service address
     The following option sets the transport layer address used by the merchant backend:

          [merchant]/serve = TCP | UNIX

     If given,

       * TCP, then we need to set the TCP port in [merchant]/port

       * UNIX, then we need to set the unix domain socket path and mode in [merchant]/unixpath and [merchant]/unixpath_mode. The latter takes the usual permission mask given as a number, e.g. 660 for user/group read-write access.

     The frontend can then connect to the backend over HTTP using the specified address. If frontend and backend run within the same operating system, the use of a UNIX domain socket is recommended to avoid accidentally exposing the backend to the network.

     To run the Taler backend on TCP port 8888, use:

          $ taler-config -s merchant -o serve -V TCP
          $ taler-config -s merchant -o port -V 8888

Currency
     Which currency the Web shop deals in, i.e. ``EUR'' or ``USD'', is specified using the option

          [taler]/currency

     For testing purposes, the currency MUST match ``KUDOS'' so that tests will work with the Taler demonstration exchange at https://exchange.demo.taler.net/:

          $ taler-config -s taler -o currency -V KUDOS

Database
     In principle is possible for the backend to support different DBMSs. The option

          [merchant]/db

     specifies which DBMS is to be used. However, currently only the value "postgres" is supported. This is also the default.

     In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database.

     For postgres, you need to provide:

          [merchantdb-postgres]/config

     This option specifies a postgres access path using the format postgres:///$DBNAME, where $DBNAME is the name of the Postgres database you want to use.  Suppose $USER is the name of the user who will run the backend process.  Then, you need to first run

          $ sudu -u postgres createuser -d $USER

     as the Postgres database administrator (usually postgres) to grant $USER the ability to create new databases.  Next, you should as $USER run:

          $ createdb $DBNAME

     to create the backend's database.  Here, $DBNAME must match the database name given in the configuration file.

     To configure the Taler backend to use this database, run:

          $ taler-config -s merchantdb-postgres -o CONFIG \
            -V postgres:///$DBNAME

Exchange
     To add an exchange to the list of trusted payment service providers, you create a section with a name that starts with ``merchant-exchange-''. In that section, the following options need to be configured:

       * The ``uri'' option specifies the exchange's base URL.  For example, to use the Taler demonstrator use:

               $ taler-config -s merchant-exchange-demo -o URI \
                 -V https://exchange.demo.taler.net/

       * The ``master_key'' option specifies the exchange's master public key in base32 encoding. For the Taler demonstrator, use:

               $ taler-config -s merchant-exchange-demo -o master_key \
                 -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00

          Note that multiple exchanges can be added to the system by using different tokens in place of demo in the example above.  Note that all of the exchanges must use the same currency.  If you need to support multiple currencies, you need to configure a backend per currency.

Wireformat
     In order to receive payments, the merchant backend needs to communicate bank account details to the exchange.  The banking system used is specified using the following global option:

          [merchant]/wireformat

     The value test can be used to interact with the Taler demonstrator at https://bank.demo.taler.net/:

          $ taler-config -s merchant -o wireformat -V test

     Other wireformats will be supported in the future to interact with actual banks.

Instances
     The backend allows the user to run multiple instances of shops with distinct business entities against a single backend.  Each instance uses its own bank account and key for signing contracts.  It is mandatory to configure a "default" instance.  The specific configuration format depends slightly on the banking system selected via the wireformat option.

       * For the test wire format, a sample specification looks as follows:

          {
            "type": "test",
            "bank_uri": "https://bank.demo.taler.net/",
            "account_number": 5,
            "salt": "RANDOMSALT"
          }

          These bank details are included in the contract in their hashed form. Hence, the random salt is necessary to make it difficult for customers to invert the hash by brute-force.

          You should substitute the account number with your actual account number.  In order to get an account number, register at our demonstration bank at https://bank.demo.taler.net/ using your browser.

          The option ``test_response_file'' in the section ``merchant-instance-wireformat-default'' specifies the path to this file.  Assuming this JSON specification is stored in a file $TEST.json, then run:

               $ taler-config -s merchant-instance-wireformat-default \
                               -o test_response_file -V $TEST.json

     Note that additional instances can be specified using different tokens in the section name instead of default.

Sample backend configuration
============================

The following is an example for a complete backend configuration:

     [merchant]
     wireformat = TEST
     serve = TCP
     port = 8888
     currency = EUR
     database = postgres

     [merchant-instance-default]
     KEYFILE = $DATADIR/key.priv

     [merchant-instance-wireformat-default]
     TEST_RESPONSE_FILE = $DATADIR/test.json

     [merchantdb-postgres]
     config = postgres:///donations

     [merchant-demoexchange]
     uri = https://exchange.demo.taler.net/
     master_key = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00

Given the above configuration, the backend will use a database named donations within Postgres.

The backend will deposit the coins it receives to the exchange at https://exchange.demo.taler.net/, which has the master key

"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".

Please note that doc/config.sh will walk you through all configuration steps, showing how to invoke taler-config for each of them.

Launching the backend
=====================

Assuming you have configured everything correctly, you can launch the merchant backend using:

     $ taler-merchant-httpd

When launched for the first time, this command will print a message about generating your private key. If everything worked as expected, the command

     $ curl http://localhost:8888/

should return the message

     Hello, I'm a merchant's Taler backend. This HTTP server is not for humans.

Please note that your backend is right now likely globally reachable.  Production systems should be configured to bind to a UNIX domain socket or properly restrict access to the port.

Testing
*******

The tool taler-merchant-generate-payments can be used to test the merchant backend installation.  It implements all the payment's steps in a programmatically way, relying on the backend you give it as input. Note that this tool gets installed along all the merchant backend's binaries.

This tool gets configured by a config file, that must have the following layout:

     [payments-generator]

     # The exchange used during the test: make sure the merchant backend
     # being tested accpets this exchange.
     # If the sysadmin wants, she can also install a local exchange
     # and test against it.
     exchange = https://exchange.demo.taler.net/

     # This value must indicate some URL where the backend
     # to be tested is listening; it doesn't have to be the
     # "official" one, though.
     merchant = http://localbackend/

     # This value is used when the tool tries to withdraw coins,
     # and must match the bank used by the exchange. If the test is
     # done against the exchange at https://exchange.demo.taler.net/,
     # then this value can be "https://bank.demo.taler.net/".
     bank = https://bank.demo.taler.net/

     # The merchant instance in charge of serving the payment.
     # Make sure this instance has a bank account at the same bank
     # indicated by the 'bank' option above.
     instance = default

     # The currency used during the test. Must match the one used
     # by merchant backend and exchange.
     currency = KUDOS

Run the test in the following way:

     $ taler-merchant-generate-payments [-c config] [-e EURI] [-m MURI]

the argument config given to -c points to the configuration file and is optional -- ~/.config/taler.conf will be checked by default. By default, the tool forks two processes: one for the merchant backend, and one for the exchange. The option -e (-m) avoids any exchange (merchant backend) fork, and just runs the generator against the exchange (merchant backend) running at EURI (MURI).

Please NOTE that the generator contains hardcoded values, as for deposit fees of the coins it uses.  In order to work against the used exchange, those values MUST match the ones used by the exchange.

The following example shows how the generator "sets" a deposit fee of EUR:0.01 for the 5 EURO coin.

     // from <merchant_repository>/src/sample/generate_payments.c
     { .oc = OC_PAY,
       .label = "deposit-simple",
       .expected_response_code = MHD_HTTP_OK,
       .details.pay.contract_ref = "create-proposal-1",
       .details.pay.coin_ref = "withdraw-coin-1",
       .details.pay.amount_with_fee = concat_amount (currency, "5"),
       .details.pay.amount_without_fee = concat_amount (currency, "4.99") },

The logic calculates the deposit fee according to the subtraction: amount_with_fee - amount_without_fee.

The following example shows a 5 EURO coin configuration - needed by the used exchange - which is compatible with the hardcoded example above.

     [coin_eur_5]
     value = EUR:5
     duration_overlap = 5 minutes
     duration_withdraw = 7 days
     duration_spend = 2 years
     duration_legal = 3 years
     fee_withdraw = EUR:0.00
     fee_deposit = EUR:0.01 # important bit
     fee_refresh = EUR:0.00
     fee_refund = EUR:0.00
     rsa_keysize = 1024

If the command terminates with no errors, then the merchant backend is correctly installed.

After this operation is done, the merchant database will have some dummy data in it, so it may be convenient to clean all the tables; to this purpose, issue the following command:

     $ taler-merchant-dbinit -r

Advanced topics
***************

Configuration in Taler
======================

In Taler realm, any component obeys to the same pattern to get configuration values.  According to this pattern, once the component has been installed, the installation deploys default values in ${prefix}/share/taler/config.d/, in .conf files.  In order to override these defaults, the user can write a custom .conf file and either pass it to the component at execution time, or name it taler.conf and place it under $HOME/.config/.

A config file is a text file containing sections, and each section contains its values. The right format follows:

     [section1]
     value1 = string
     value2 = 23

     [section2]
     value21 = string
     value22 = /path22

Throughout any configuration file, it is possible to use $-prefixed variables, like $VAR, especially when they represent filesystem paths. It is also possible to provide defaults values for those variables that are unset, by using the following syntax: ${VAR:-default}. However, there are two ways a user can set $-prefixable variables:

by defining them under a [paths] section, see example below,

     [paths]
     TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
     ..
     [section-x]
     path-x = ${TALER_DEPLOYMENT_SHARED}/x

or by setting them in the environment:

     $ export VAR=/x

The configuration loader will give precedence to variables set under [path], though.

The utility taler-config, which gets installed along with the exchange, serves to get and set configuration values without directly editing the .conf. The option -f is particularly useful to resolve pathnames, when they use several levels of $-expanded variables. See taler-config --help.

Note that, in this stage of development, the file $HOME/.config/taler.conf can contain sections for all the component. For example, both an exchange and a bank can read values from it.

The repository git://taler.net/deployment contains examples of configuration file used in our demos. See under deployment/config.

     Expectably, some components will not work just by using default values, as their work is often interdependent. For example, a merchant needs to know an exchange URL, or a database name.

Using taler-config
==================

The tool taler-config can be used to extract or manipulate configuration values; however, the configuration use the well-known INI file format and can also be edited by hand.

Run

     $ taler-config -s $SECTION

to list all of the configuration values in section $SECTION.

Run

     $ taler-config -s $section -o $option

to extract the respective configuration value for option $option in section $section.

Finally, to change a setting, run

     $ taler-config -s $section -o $option -V $value

to set the respective configuration value to $value. Note that you have to manually restart the Taler backend after you change the configuration to make the new configuration go into effect.

Some default options will use $-variables, such as $DATADIR within their value.  To expand the $DATADIR or other $-variables in the configuration, pass the -f option to taler-config.  For example, compare:

     $ taler-config -s merchant-instance-wireformat-default \
                    -o test_response_file
     $ taler-config -f -s merchant-instance-wireformat-default \
                    -o test_response_file

While the configuration file is typically located at $HOME/.config/taler.conf, an alternative location can be specified to taler-merchant-httpd and taler-config using the -c option.

Merchant key management
=======================

The option ``KEYFILE'' in the section ``merchant-instance-default'' specifies the path to the instance's private key.  You do not need to create a key manually, the backend will generate it automatically if it is missing.  While generally unnecessary, it is possible to display the corresponding public key using the gnunet-ecc command-line tool:

     $ gnunet-ecc -p                                  \
       $(taler-config -f -s merchant-instance-default \
                      -o keyfile)

Using the SEPA wire transfer method
===================================

The following is a sample configuration for the SEPA wire transfer method: (Supporting SEPA is still work in progress; the backend will accept this configuration, but the exchange will not work with SEPA today.).

{
  "type": "SEPA",
  "IBAN": "XY00 1111 2222 3333 4444 5555 6666",
  "name": "Taler charity program",
  "BIC": "XXXXAB99",
  "salt": "RANDOMSALT"
}

We will now assume that this information is stored in file ${DATADIR}/sepa.json. Then, to configure the backend for SEPA payments in EUR, the following configuration options need to be set:

     $ taler-config -s merchant -o currency -V EUR
     $ taler-config -s merchant -o wireformat -V sepa
     $ taler-config -s merchant-instance-wireformat-default \
                     -o sepa_response_file -V ${DATADIR}/sepa.json

Please note that you will also have to configure an exchange and/or auditors that support SEPA.  However, we cannot explain how to do this yet as such entities do not yet exist.  Once such entities do exist, we expect future versions of the Taler backend to ship with pre-configured exchanges and auditors for common denominations.

GNU-LGPL
********

     [file lgpl.texi not included]

GNU Affero GPL
**************

     [file agpl.texi not included]

GNU-FDL
*******

     [file fdl-1.3.texi not included]