\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename manual.info
@include version.texi
@settitle The GNU Taler exchange operator tutorial @value{VERSION}

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying
This manual is for the GNU Taler exchange (version @value{VERSION}, @value{UPDATED}),

Copyright @copyright{} 2017 INRIA

@quotation
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''.
@end quotation
@end copying
@c If your manual is published on paper by the FSF, it should include
@c The standard FSF Front-Cover and Back-Cover Texts, as given in
@c maintain.texi.
@c
@c Titlepage
@c
@titlepage
@title The GNU Taler exchange operator tutorial
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@summarycontents
@contents

@ifnottex
@node Top
@top The GNU Taler manual for Web shops
@insertcopying
@end ifnottex

@menu
* Introduction::            Whom this manual is addressed to
* Installation::            Installing the exchange
* Configuration::           How to set up the exchange


Appendices

* GNU-LGPL::                     The GNU Lesser General Public License says how you
                                 can use the code of libtalermerchant.so in your own projects.
* GNU Affero GPL::               The Affero GNU General Public License says how you
                                 can copy and share the Taler merchant backend.
* GNU-FDL::                      The GNU Free Documentation License says how you
                                 can copy and share the documentation of GNU Taler.

Indices

* Concept Index::               Index of concepts and programs.

@end menu


@node Introduction
@chapter Introduction

@section 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 working Taler exchange installed and configured.

@section About this manual

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

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

@section Architecture overview

@node Installation
@menu
* generic-instructions:: Generic installation guidelines
@end menu

@chapter Installation

This chapter describes how to install the GNU Taler exchange.

@node generic-instructions
@section Generic instructions

This section provides generic instructions for the exchange
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.

@subsection Installation of dependencies

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

@itemize
@item autoconf @math{\ge 2.69}
@item automake @math{\ge 1.14}
@item libtool @math{\ge 2.4}
@item autopoint @math{\ge 0.19}
@item libltdl @math{\ge 2.4}
@item libunistring @math{\ge 0.9.3}
@item libcurl @math{\ge 7.26} (or libgnurl @math{\ge 7.26})
@item GNU libmicrohttpd @math{\ge 0.9.39}
@item GNU libgcrypt @math{\ge 1.6}
@item libjansson @math{\ge 2.7}
@item Postgres @math{\ge 9.4}, including libpq
@item libgnunetutil (from Git)
@item GNU Taler exchange (from Git)
@end itemize

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.


@subsection Installing libgnunetutil

@cindex GNUnet
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:

@example
$ 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
@end example

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

@subsection Installing the GNU Taler exchange

@cindex exchange
After installing GNUnet, you can download and install
the exchange as follows:

@example
$ 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
@end example

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

@node Configuration
@chapter How to configure the exchange

@section The configuration file
@cindex taler-config
@cindex taler.conf
The installation already provides reasonable defaults.  The file
@code{$HOME/.config/taler.conf} is responsible of overriding defaults
values, or add new ones.  The format of the configuration file is
the well-known INI file format.  Nonetheless, the exchange takes a
@code{-c CONFIG} option that makes the file @code{CONFIG} ovveride
the defaults.

@cindex keys
@cindex denomination keys
@cindex auditor
@section Configuring keys

@subsection Denomination keys
@c FIXME TBD - NOTE, docs.taler.net contains already some text on this

@subsection Master key
@c FIXME TBD - NOTE, docs.taler.net contains already some text on this

@subsection Specifying auditors

In order to "add" any auditor to the list of the auditors accepted by
the exchange, it's required to (1) generate a cryptographic blob containing
metadata about the denomination keys, (2) ask the auditor to sign this blob,
and (3) copy the auditor signed blob to a exchange's dedicated directory.

The following command accomplishes step (1).

@example
taler-exchange-keyup -o blob
@end example

In production, step (2) is accomplished thanks to each auditor providing a RESTful
service that lets the exchange administrator upload the @code{blob} and get a signed
version of it.

Nonetheless, for testing purposes, the following command emulates a auditor's
signature that a exchange administrator can run locally.

@example
taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URI -o OUTPUT_FILE
@end example

The shown arguments are all mandatory.

@itemize
@item @code{EXCHANGE_MASTER_PUB} the base32 Crockford-encoded exchange's master
public key.  Tipically, this value lies in the configuration option
@code{[exchange]/master_public_key}.
@item @code{BLOB} the blob generated in step (1).
@item @code{AUDITOR_URI} the URI that identifies the auditor.
@item @code{OUTPUT_FILE} where on the disk the signed blob is to be saved.
@end itemize

As of step (3), the signed blob must be copied into the dorectory specified
by the option @code{AUDITOR_BASE_DIR} under the section @code{[exchangedb]}.
Assuming @code{AUDITOR_BASE_DIR = $@{HOME@}/.local/share/taler/auditors}, the
following command will "add" a auditor to the exchange.

@example
# assuming that the file 'blob' is in the CWD
cp blob $@{HOME@}/.local/share/taler/auditors
@end example

If the auditor has been correctly added, the exchange's @code{/keys} response
must contain an entry in the @code{auditors} array mentioning the auditor's URI
specified at step (2) in the @code{-u} argument.


@section Wire formats
@c FIXME TBD - NOTE, docs.taler.net _might_ contain already some text on this


@c **********************************************************
@c *******************  Appendices  *************************
@c **********************************************************

@node GNU-LGPL
@unnumbered GNU-LGPL
@cindex license
@cindex LGPL
@include lgpl.texi

@node GNU Affero GPL
@unnumbered GNU Affero GPL
@cindex license
@cindex Affero GPL
@include agpl.texi

@node GNU-FDL
@unnumbered GNU-FDL
@cindex license
@cindex GNU Free Documentation License
@include fdl-1.3.texi

@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye