diff options
| author | Florian Dold <florian.dold@gmail.com> | 2019-08-29 13:02:55 +0200 |
|---|---|---|
| committer | Florian Dold <florian.dold@gmail.com> | 2019-08-29 13:02:55 +0200 |
| commit | ba9335ec4c3578fdebfbec3072396bcda29d3425 (patch) | |
| tree | 6d44f540797cba9ed77f28548714ff874141da66 | |
| parent | c3a6698c48f315e124bfd89bbb98564966f89434 (diff) | |
| download | docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.tar.gz docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.tar.bz2 docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.zip | |
initial rough import of other docs
| -rw-r--r-- | Makefile | 9 | ||||
| -rw-r--r-- | arch-api.dot | 27 | ||||
| -rw-r--r-- | arch-api.png | bin | 0 -> 59189 bytes | |||
| -rw-r--r-- | arch.png | bin | 0 -> 40820 bytes | |||
| -rw-r--r-- | backoffice.rst | 155 | ||||
| -rw-r--r-- | conf.py | 1 | ||||
| -rw-r--r-- | core/api-auditor.rst (renamed from api-auditor.rst) | 0 | ||||
| -rw-r--r-- | core/api-bank.rst (renamed from api-bank.rst) | 2 | ||||
| -rw-r--r-- | core/api-common.rst (renamed from api-common.rst) | 0 | ||||
| -rw-r--r-- | core/api-error.rst (renamed from api-error.rst) | 0 | ||||
| -rw-r--r-- | core/api-exchange.rst (renamed from api-exchange.rst) | 0 | ||||
| -rw-r--r-- | core/api-merchant.rst (renamed from api-merchant.rst) | 0 | ||||
| -rw-r--r-- | core/api-sync.rst (renamed from api-sync.rst) | 0 | ||||
| -rw-r--r-- | core/index.rst | 40 | ||||
| -rw-r--r-- | core/taler-uri.rst (renamed from taler-uri.rst) | 0 | ||||
| -rw-r--r-- | core/wireformats.rst (renamed from wireformats.rst) | 0 | ||||
| -rwxr-xr-x | exchange-db-generate.sh | 3 | ||||
| -rw-r--r-- | exchange-db.png | bin | 0 -> 564934 bytes | |||
| -rw-r--r-- | index.rst | 29 | ||||
| -rw-r--r-- | merchant-api.rst | 1703 | ||||
| -rw-r--r-- | merchant-manual.rst | 1228 | ||||
| -rw-r--r-- | onboarding.rst | 386 | ||||
| -rw-r--r-- | taler-bank.rst | 190 | ||||
| -rw-r--r-- | taler-exchange.rst | 869 |
24 files changed, 4621 insertions, 21 deletions
@@ -49,9 +49,16 @@ help: clean: rm -rf $(BUILDDIR)/* + +arch-api.png: arch-api.dot + dot -Tpng arch-api.dot > arch-api.png + +diagrams: arch-api.png + + # The html-linked builder does not support caching, so we # remove all cached state first. -html: +html: diagrams $(SPHINXBUILD) -b html-linked $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/arch-api.dot b/arch-api.dot new file mode 100644 index 00000000..1c30c06a --- /dev/null +++ b/arch-api.dot @@ -0,0 +1,27 @@ +digraph G { + + user[label="Customer browser"]; + admin[label="Shop admin"]; + Backend[color="blue"]; + BackendPublic[color="blue", label="Backend\n(public interface)"]; + subgraph cluster_0 { + Frontend; + Backoffice; + Backend; + BackendPublic; + DBMS; + label="Shop server"; + } + subgraph cluster_1 { + Exchange; + label="Exchange"; + } + user->Frontend; + admin->Backoffice; + Frontend->Backend; + Backoffice->Backend; + BackendPublic->Backend; + user->BackendPublic; + Backend->DBMS; + Backend->Exchange; +} diff --git a/arch-api.png b/arch-api.png Binary files differnew file mode 100644 index 00000000..8004f790 --- /dev/null +++ b/arch-api.png diff --git a/arch.png b/arch.png Binary files differnew file mode 100644 index 00000000..37fc845b --- /dev/null +++ b/arch.png diff --git a/backoffice.rst b/backoffice.rst new file mode 100644 index 00000000..8dbfb165 --- /dev/null +++ b/backoffice.rst @@ -0,0 +1,155 @@ +Howtos for taler.net admins and developers (version 0.0.0, 16 Jan 2018), +Copyright © 2017-2018 Taler Systems SA. + + 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”. + +.. _Top: + +Back-office Web service manual +############################### + +Howtos for taler.net admins and developers (version 0.0.0, 16 Jan 2018), +Copyright © 2017-2018 Taler Systems SA. + + 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: + +Introduction +============ + +The back-office Web service allows a merchant to check on the status of +their Taler transactions. Merchants can check if and when they were paid +by a wire transfer for coins deposited at the exchange. Also, given a +wire transfer they have received, they can ask which Taler transactions +correspond to the wire transfer. + +This manual guides merchant system administrators through the +installation and configuration of this Web service. + +.. _Installation: + +Installation +============ + +The back-office Web service code is available at +``git://taler.net/backoffice``. The application can be installed in a +GNU-ish fashion. + +:: + + # Get the code: + $ git clone git://taler.net/backoffice + + # Bootstrap and configure + $ cd backoffice + $ ./bootstrap + # This step will check if the system is ready to + # allow the installation. + $ ./configure --prefix=<PREFIX> + $ make install + +Note that to make the application work ``<PREFIX>/bin`` must be included +in the ``$PATH``, and ``<PREFIX>/lib/python3.5/site-packages/`` in +``$PYTHONPATH``. + +.. _Configuration: + +Configuration +============= + +The following information must be provided in the configuration: on +which address the backend should serve the Web site, which currency is +used, and which merchant backend this Web service will work with. + +The merchant backend is an important agent, as it is responsible for +returning information about transactions and wire transfers. The +backoffice Web service is merely a frontend for it. A separate manual +(available at https://docs.taler.net/merchant/backend/html/manual.html) +describes the installation and configuration of the merchant backend. + +Assuming the reader is familiar with configuration in Taler (if not, +read: +https://docs.taler.net/exchange/html/taler-exchange.html#Configuration-format), +a working configuration example is the following one: + +:: + + [taler] + # will be EUR, USD, or whatever currency the merchant + # works with. + currency = KUDOS + + # each back-office Web service is associated with a "frontend + # name": this name instructs the application which configuration + # section is going to be read. Thus <name> is the "frontend name" + # and must be specified on the command line via the "--frontend" + # option. See the 'Run' chapter for more details on launching the + # application. + [backoffice-<name>] + + # This option sets the way the backoffice communicates + # when it is instructed to operate via UWSGI. Therefore, + # <how> can be: TCP or UNIX. If TCP is given, then the + # additional UWSGI_PORT option becomes necessary. + uwsgi_serve = <how> + + # those options will be read if the Web site is served via + # WSGI. + uwsgi_unixpath_mode = 660 + uwsgi_unixpath = /path/to/backoffice-<name>.uwsgi + uwsgi_unixmode = 666 + + # If UWSGI_SERVE were set as 'TCP', then the following option + # would have been necessary. It instructs the backoffice service + # about which TCP port should be listened on, to communicate over + # UWSGI. + # uwsgi_port = 8080 + + # this option will be read if the Web site is served via + # HTTP. + http_port = 5959 + + # specifies which merchant backend is going to be used. + backend = http://backend.test.taler.net/ + + # Informally speaking, each instance points to both a private + # key that can sign proposals and a bank account that can receive + # wire transfers by some exchange. + + # Here, <instance_i> is just a string (with no spaces) that will + # make the referenced instance be traceable by the back-office Web + # application. + + instances = <instance_1> <instance_2> .. + +.. _Launching-the-backoffice: + +Launching the backoffice +======================== + +The following example shows how to run the Web service. + +:: + + # such invocation will work only if the configuration contains + # a section called "[backoffice-myshop]" which looks like the + # example above. + + # As of serving, the Web site will be available via HTTP, at the + # port specified in the configuration option "http_port", at localhost. + + $ taler-merchant-backoffice --frontend myshop serve-http + +Other options, such as those to serve the site via WSGI, are explained +in the man page and can be listed using the ``--help`` argument. @@ -136,6 +136,7 @@ html_sidebars = { html_theme_options = { # Set the name of the project to appear in the sidebar "project_nav_name": "GNU Taler", + "globaltoc_depth": 4, } # Add any paths that contain custom themes here, relative to this directory. diff --git a/api-auditor.rst b/core/api-auditor.rst index 957b1c01..957b1c01 100644 --- a/api-auditor.rst +++ b/core/api-auditor.rst diff --git a/api-bank.rst b/core/api-bank.rst index 07de8191..a3c8953e 100644 --- a/api-bank.rst +++ b/core/api-bank.rst @@ -55,7 +55,7 @@ This API provides programmatic withdrawal of cash via Taler to all the users registered at the bank. It triggers a wire transfer from the client bank account to the exchange's. -.. _bank-register: +.. _bank-withdraw: .. http:post:: /taler/withdraw **Request** The body of this request must have the format of a `BankTalerWithdrawRequest`_. diff --git a/api-common.rst b/core/api-common.rst index 8f3ae378..8f3ae378 100644 --- a/api-common.rst +++ b/core/api-common.rst diff --git a/api-error.rst b/core/api-error.rst index 61716b72..61716b72 100644 --- a/api-error.rst +++ b/core/api-error.rst diff --git a/api-exchange.rst b/core/api-exchange.rst index 1d03dae9..1d03dae9 100644 --- a/api-exchange.rst +++ b/core/api-exchange.rst diff --git a/api-merchant.rst b/core/api-merchant.rst index 9eb69812..9eb69812 100644 --- a/api-merchant.rst +++ b/core/api-merchant.rst diff --git a/api-sync.rst b/core/api-sync.rst index 701c7df5..701c7df5 100644 --- a/api-sync.rst +++ b/core/api-sync.rst diff --git a/core/index.rst b/core/index.rst new file mode 100644 index 00000000..76b77903 --- /dev/null +++ b/core/index.rst @@ -0,0 +1,40 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2018 GNUnet e.V. + + 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 Florian Dold + @author Benedikt Muller + @author Sree Harsha Totakura + @author Marcello Stanisci + @author Christian Grothoff + +--------------------------- +Core Protocol Specification +--------------------------- + +The *Protocol Specification* defines the HTTP-based, predominantly RESTful +interfaces between the core components of Taler. + +.. toctree:: + :maxdepth: 2 + + api-common + api-error + api-exchange + api-merchant + api-auditor + api-bank + wireformats + api-sync + taler-uri diff --git a/taler-uri.rst b/core/taler-uri.rst index d69b4b0c..d69b4b0c 100644 --- a/taler-uri.rst +++ b/core/taler-uri.rst diff --git a/wireformats.rst b/core/wireformats.rst index 12d23630..12d23630 100644 --- a/wireformats.rst +++ b/core/wireformats.rst diff --git a/exchange-db-generate.sh b/exchange-db-generate.sh new file mode 100755 index 00000000..b296e0c9 --- /dev/null +++ b/exchange-db-generate.sh @@ -0,0 +1,3 @@ +#!/bin/sh +taler-exchange-dbinit -r +java -jar schemaSpy_5.0.0.jar -t pgsql -db taler -o taler -host localhost -dp /usr/share/java/postgresql-jdbc3-9.2.jar -u grothoff -p test -s public -hq diff --git a/exchange-db.png b/exchange-db.png Binary files differnew file mode 100644 index 00000000..421e5941 --- /dev/null +++ b/exchange-db.png @@ -43,9 +43,8 @@ In this document, we describe the REST-based APIs between the various components, internal architecture of key components, and how to get them installed. --------------------------------------- -Taler HTTP Core Protocol Specification --------------------------------------- +Documentation Overview +---------------------- The *Protocol Specification* defines the HTTP-based, predominantly RESTful interfaces between the core components of Taler. @@ -53,20 +52,12 @@ interfaces between the core components of Taler. .. toctree:: :maxdepth: 2 - api-common - api-error - api-exchange - api-merchant - api-auditor - api-bank - wireformats - taler-uri - ---------- -Licensing ---------- - -.. toctree:: - :maxdepth: 2 - + core/index + taler-exchange + merchant-manual + merchant-api + taler-bank + backoffice + onboarding global-licensing + diff --git a/merchant-api.rst b/merchant-api.rst new file mode 100644 index 00000000..cc4ede93 --- /dev/null +++ b/merchant-api.rst @@ -0,0 +1,1703 @@ +The GNU Taler Merchant API Tutorial +################################### + +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). + +About this tutorial +------------------- + +This tutorial addresses how to process payments using the GNU Taler +merchant Backend. This chapter explains some basic concepts. In the +second chapter, you will learn how to do basic payments. + +This version of the tutorial has examples for Python3. It uses the +requests library for HTTP requests. Versions for other +languages/environments are available as well. + +examples +git +If you want to look at some simple, running examples, check out these: + +- The `essay + merchant <https://git.taler.net/blog.git/tree/talerblog/blog/blog.py>`__ + that sells single chapters of a book. + +- The `donation + page <https://git.taler.net/donations.git/tree/talerdonations/donations/donations.py>`__ + that accepts donations for software projects and gives donation + receipts. + +- The + `survey <https://git.taler.net/survey.git/tree/talersurvey/survey/survey.py>`__ + that gives users who answer a question a small reward. + +Architecture overview +--------------------- + +The Taler software stack for a merchant consists of the following main +components: + +- frontend + 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 tutorial describes how to + develop a Taler frontend. + +- backend + A Taler-specific payment backend which makes it easy for the frontend + to process financial transactions with Taler. For this tutorial, you + will use a public sandbox backend. For production use, you must + either set up your own backend or ask another person to do so for + you. + +The following image illustrates the various interactions of these key +components: + +|image0| + +The backend provides the cryptographic protocol support, stores +Taler-specific financial information 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 are +encapsulated within the Taler backend. + +Some functionality of the backend (the “public interface“) is also +exposed to the customer’s browser directly. In the HTTP API, all public +endpoints are prefixed with ``/public/``. + +Public Sandbox Backend and Authentication +----------------------------------------- + +sandbox +authorization +How the frontend authenticates to the Taler backend depends on the +configuration. See Taler Merchant Operating Manual. + +The public sandbox backend https://backend.demo.taler.net/ uses an API +key in the ``Authorization`` header. The value of this header must be +``ApiKey sandbox`` for the public sandbox backend. + +:: + + >>> import requests + >>> requests.get("https://backend.demo.taler.net", + ... headers={"Authorization": "ApiKey sandbox"}) + <Response [200]> + +If an HTTP status code other than 200 is returned, something went wrong. +You should figure out what the problem is before continuing with this +tutorial. + +The sandbox backend https://backend.demo.taler.net/ uses ``KUDOS`` as an +imaginary currency. Coins denominated in ``KUDOS`` can be withdrawn from +https://bank.demo.taler.net/. + +Merchant Instances +------------------ + +instance +The same Taler merchant backend server can be used by multiple separate +merchants that are separate business entities. Each of these separate +business entities is called a *merchant instance*, and is identified by +an alphanumeric *instance id*. If the instance is omitted, the instance +id ``default`` is assumed. + +The following merchant instances are configured on +https://backend.demo.taler.net/: + +- ``GNUnet`` (The GNUnet project) + +- ``FSF`` (The Free Software Foundation) + +- ``Tor`` (The Tor Project) + +- ``default`` (Kudos Inc.) + +Note that these are fictional merchants used for our demonstrators and +not affiliated with or officially approved by the respective projects. + +.. _Accepting-a-Simple-Payment: + +Accepting a Simple Payment +========================== + +Creating an Order for a Payment +------------------------------- + +order +Payments in Taler revolve around an *order*, which is a machine-readable +description of the business transaction for which the payment is to be +made. Before accepting a Taler payment as a merchant you must create +such an order. + +This is done by posting a JSON object to the backend’s ``/order`` API +endpoint. At least the following fields must be given: + +- amount: The amount to be paid, as a string in the format + ``CURRENCY:DECIMAL_VALUE``, for example ``EUR:10`` for 10 Euros or + ``KUDOS:1.5`` for 1.5 KUDOS. + +- summary: A human-readable summary for what the payment is about. The + summary should be short enough to fit into titles, though no hard + limit is enforced. + +- fulfillment_url: A URL that will be displayed once the payment is + completed. For digital goods, this should be a page that displays the + product that was purchased. On successful payment, the wallet + automatically appends the ``order_id`` as a query parameter, as well + as the ``session_sig`` for session-bound payments (discussed later). + +Orders can have many more fields, see `The Taler Order +Format <#The-Taler-Order-Format>`__. + +After successfully ``POST``\ ing to ``/order``, an ``order_id`` will be +returned. Together with the merchant ``instance``, the order id uniquely +identifies the order within a merchant backend. + +:: + + >>> import requests + >>> order = dict(order=dict(amount="KUDOS:10", + ... summary="Donation", + ... fulfillment_url="https://example.com/thanks.html")) + >>> order_resp = requests.post("https://backend.demo.taler.net/order", json=order, + ... headers={"Authorization": "ApiKey sandbox"}) + <Response [200]> + +The backend will fill in some details missing in the order, such as the +address of the merchant instance. The full details are called the +*contract terms*. contract terms + +Checking Payment Status and Prompting for Payment +------------------------------------------------- + +The status of a payment can be checked with the ``/check-payment`` +endpoint. If the payment is yet to be completed by the customer, +``/check-payment`` will give the frontend a URL (the +payment_redirect_url) that will trigger the customer’s wallet to execute +the payment. + +Note that the only way to obtain the payment_redirect_url is to check +the status of the payment, even if you know that the user did not pay +yet. + +:: + + >>> import requests + >>> r = requests.get("https://backend.demo.taler.net/check-payment", + ... params=dict(order_id=order_resp.json()["order_id"]), + ... headers={"Authorization": "ApiKey sandbox"}) + >>> print(r.json()) + +If the paid field in the response is ``true``, the other fields in the +response will be different. Once the payment was completed by the user, +the response will contain the following fields: + +- paid: Set to true. + +- contract_terms: The full contract terms of the order. + +- refunded: ``true`` if a (possibly partial) refund was granted for + this purchase. + +- refunded_amount: Amount that was refunded + +- last_session_id: Last session ID used by the customer’s wallet. See + `Session-Bound Payments <#Session_002dBound-Payments>`__. + +Once the frontend has confirmed that the payment was successful, it +usually needs to trigger the business logic for the merchant to fulfill +the merchant’s obligations under the contract. + +.. _Giving-Refunds: + +Giving Refunds +============== + +refunds +A refund in GNU Taler is a way to “undo” a payment. It needs to be +authorized by the merchant. Refunds can be for any fraction of the +original amount paid, but they cannot exceed the original payment. +Refunds are time-limited and can only happen while the exchange holds +funds for a particular payment in escrow. The time during which a refund +is possible can be controlled by setting the ``refund_deadline`` in an +order. The default value for this refund deadline is specified in the +configuration of the merchant’s backend. + +The frontend can instruct the merchant backend to authorize a refund by +``POST``\ ing to the ``/refund`` endpoint. + +The refund request JSON object has the following fields: + +- order_id: Identifies for which order a customer should be refunded. + +- instance: Merchant instance to use. + +- refund: Amount to be refunded. If a previous refund was authorized + for the same order, the new amount must be higher, otherwise the + operation has no effect. The value indicates the total amount to be + refunded, *not* an increase in the refund. + +- reason: Human-readable justification for the refund. The reason is + only used by the Back Office and is not exposed to the customer. + +If the request is successful (indicated by HTTP status code 200), the +response includes a ``refund_redirect_url``. The frontend must redirect +the customer’s browser to that URL to allow the refund to be processed +by the wallet. + +This code snipped illustrates giving a refund: + +:: + + >>> import requests + >>> refund_req = dict(order_id="2018.058.21.46.06-024C85K189H8P", + ... refund="KUDOS:10", + ... instance="default", + ... reason="Customer did not like the product") + >>> requests.post("https://backend.demo.taler.net/refund", json=refund_req, + ... headers={"Authorization": "ApiKey sandbox"}) + <Response [200]> + +.. _Giving-Customers-Tips: + +Giving Customers Tips +===================== + +tips +GNU Taler allows Web sites to grant small amounts directly to the +visitor. The idea is that some sites may want incentivize actions such +as filling out a survey or trying a new feature. It is important to note +that tips are not enforceable for the visitor, as there is no contract. +It is simply a voluntary gesture of appreciation of the site to its +visitor. However, once a tip has been granted, the visitor obtains full +control over the funds provided by the site. + +The “merchant” backend of the site must be properly configured for +tipping, and sufficient funds must be made available for tipping See +Taler Merchant Operating Manual. + +To check if tipping is configured properly and if there are sufficient +funds available for tipping, query the ``/tip-query`` endpoint: + +:: + + >>> import requests + >>> requests.get("https://backend.demo.taler.net/tip-query?instance=default", + ... headers={"Authorization": "ApiKey sandbox"}) + <Response [200]> + +authorize tip +To authorize a tip, ``POST`` to ``/tip-authorize``. The following fields +are recognized in the JSON request object: + +- amount: Amount that should be given to the visitor as a tip. + +- instance: Merchant instance that grants the tip (each instance may + have its own independend tipping funds configured). + +- justification: Description of why the tip was granted. Human-readable + text not exposed to the customer, but used by the Back Office. + +- next_url: The URL that the user’s browser should be redirected to by + the wallet, once the tip has been processed. + +The response from the backend contains a ``tip_redirect_url``. The +customer’s browser must be redirected to this URL for the wallet to pick +up the tip. pick up tip + +This code snipped illustrates giving a tip: + +:: + + >>> import requests + >>> tip_req = dict(amount="KUDOS:0.5", + ... instance="default", + ... justification="User filled out survey", + ... next_url="https://merchant.com/thanks.html") + >>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req, + ... headers={"Authorization": "ApiKey sandbox"}) + <Response [200]> + +.. _Advanced-topics: + +Advanced topics +=============== + +.. _Detecting-the-Presence-of-the-Taler-Wallet: + +Detecting the Presence of the Taler Wallet +------------------------------------------ + +wallet +Taler offers ways to detect whether a user has the wallet installed in +their browser. This allows Web sites to adapt accordingly. Note that not +all platforms can do presence detection reliably. Some platforms might +have a Taler wallet installed as a separate App instead of using a Web +extension. In these cases, presence detection will fail. Thus, sites may +want to allow users to request Taler payments even if a wallet could not +be detected, especially for visitors using mobiles. + +Presence detection without JavaScript +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Presence detection without JavaScript is based on CSS classes. You can +hide or show elements selectively depending on whether the wallet is +detected or not. + +In order to work correctly, a special fallback stylesheet must be +included that will be used when the wallet is not present. The +stylesheet can be put into any file, but must be included via a ``link`` +tag with the ``id`` attribute set to ``taler-presence-stylesheet``. If a +wallet is present, it will “hijack” this stylesheet to change how +elements with the following classes are rendered: + +The following CSS classes can be used: + +``taler-installed-hide`` + A CSS rule will set the ``display`` property for this class to + ``none`` once the Taler wallet is installed and enabled. If the + wallet is not installed, ``display`` will be ``inherit``. + +``taler-installed-show`` + A CSS rule will set the ``display`` property for this class to + ``inherit`` once the Taler wallet is installed and enabled. If the + wallet is not installed, ``display`` will be ``none``. + +The following is a complete example: + +:: + + <!DOCTYPE html> + <html data-taler-nojs="true"> + <head> + <title>Tutorial</title> + <link rel="stylesheet" + type="text/css" + href="/web-common/taler-fallback.css" + id="taler-presence-stylesheet" /> + </head> + <body> + <p class="taler-installed-hide"> + No wallet found. + </p> + <p class="taler-installed-show"> + Wallet found! + </p> + </body> + </html> + +The ``taler-fallback.css`` is part of the Taler’s *web-common* +repository, available at +https://git.taler.net/web-common.git/tree/taler-fallback.css. You may +have to adjust the ``href`` attribute in the HTML code above to point to +the correct location of the ``taler-fallback.css`` file on your Web +site. + +Detection with JavaScript +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following functions are defined in the ``taler`` namespace of the +``taler-wallet-lib`` helper library available at +https://git.taler.net/web-common.git/tree/taler-wallet-lib.js. + +``onPresent(callback: () => void)`` + Adds a callback to be called when support for Taler payments is + detected. + +``onAbsent(callback: () => void)`` + Adds a callback to be called when support for Taler payments is + disabled. + +Note that the registered callbacks may be called more than once. This +may happen if a user disables or enables the wallet in the browser’s +extension settings while a shop’s frontend page is open. + +.. _Integration-with-the-Back-Office: + +Integration with the Back Office +-------------------------------- + +Taler ships a Back Office application as a stand-alone Web application. +The Back Office has its own documentation at +https://docs.taler.net/backoffice/html/manual.html. + +Developers wishing to tightly integrate back office support for +Taler-based payments into an existing back office application should +focus on the wire transfer tracking and transaction history sections of +the Taler Backend API specification at +https://docs.taler.net/api/api-merchant.html + +.. _Session_002dBound-Payments: + +Session-Bound Payments +---------------------- + +session +Sometimes checking if an order has been paid for is not enough. For +example, when selling access to online media, the publisher may want to +be paid for exactly the same product by each customer. Taler supports +this model by allowing the mechant to check whether the “payment +receipt” is available on the user’s current device. This prevents users +from easily sharing media access by transmitting a link to the +fulfillment page. Of course sophisticated users could share payment +receipts as well, but this is not as easy as sharing a link, and in this +case they are more likely to just share the media directly. + +To use this feature, the merchant must first assign the user’s current +browser an ephemeral ``session_id``, usually via a session cookie. When +executing or re-playing a payment, the wallet will receive an additional +signature (``session_sig``). This signature certifies that the wallet +showed a payment receipt for the respective order in the current +session. cookie + +Session-bound payments are triggerd by passing the ``session_id`` +parameter to the ``/check-payment`` endpoint. The wallet will then +redirect to the fulfillment page, but include an additional +``session_sig`` parameter. The frontend can query ``/check-payment`` +with both the ``session_id`` and the ``session_sig`` to verify that the +signature is correct. + +The last session ID that was successfuly used to prove that the payment +receipt is in the user’s wallet is also available as ``last_session_id`` +in the response to ``/check-payment``. + +.. _Product-Identification: + +Product Identification +---------------------- + +resource url +In some situations the user may have paid for some digital good, but the +frontend does not know the exact order ID, and thus cannot instruct the +wallet to reveil the existing payment receipt. This is common for simple +shops without a login system. In this case, the user would be prompted +for payment again, even though they already purchased the product. + +To allow the wallet to instead find the existing payment receipt, the +shop must use a unique fulfillment URL for each product. Then, the +frontend must provide an additional ``resource_url`` parameter to to +``/check-payment``. It should identify this unique fulfillment URL for +the product. The wallet will then check whether it has paid for a +contract with the same ``resource_url`` before, and if so replay the +previous payment. + +.. _The-Taler-Order-Format: + +The Taler Order Format +---------------------- + +contract +terms +order +A Taler order can specify many details about the payment. This section +describes each of the fields in depth. + +Financial amounts are always specified as a string in the format +``"CURRENCY:DECIMAL_VALUE"``. + +amount + amount + Specifies the total amount to be paid to the merchant by the + customer. + +max_fee + fees + maximum deposit fee + This is the maximum total amount of deposit fees that the merchant is + willing to pay. If the deposit fees for the coins exceed this amount, + the customer has to include it in the payment total. The fee is + specified using the same triplet used for amount. + +max_wire_fee + fees + maximum wire fee + Maximum wire fee accepted by the merchant (customer share to be + divided by the ’wire_fee_amortization’ factor, and further reduced if + deposit fees are below ’max_fee’). Default if missing is zero. + +wire_fee_amortization + fees + maximum fee amortization + Over how many customer transactions does the merchant expect to + amortize wire fees on average? If the exchange’s wire fee is above + ’max_wire_fee’, the difference is divided by this number to compute + the expected customer’s contribution to the wire fee. The customer’s + contribution may further be reduced by the difference between the + ’max_fee’ and the sum of the actual deposit fees. Optional, default + value if missing is 1. 0 and negative values are invalid and also + interpreted as 1. + +pay_url + pay_url + Which URL accepts payments. This is the URL where the wallet will + POST coins. + +fulfillment_url + fulfillment URL + Which URL should the wallet go to for obtaining the fulfillment, for + example the HTML or PDF of an article that was bought, or an order + tracking system for shipments, or a simple human-readable Web page + indicating the status of the contract. + +order_id + order ID + Alphanumeric identifier, freely definable by the merchant. Used by + the merchant to uniquely identify the transaction. + +summary + summary + Short, human-readable summary of the contract. To be used when + displaying the contract in just one line, for example in the + transaction history of the customer. + +timestamp + Time at which the offer was generated. + +pay_deadline + payment deadline + Timestamp of the time by which the merchant wants the exchange to + definitively wire the money due from this contract. Once this + deadline expires, the exchange will aggregate all deposits where the + contracts are past the refund_deadline and execute one large wire + payment for them. Amounts will be rounded down to the wire transfer + unit; if the total amount is still below the wire transfer unit, it + will not be disbursed. + +refund_deadline + refund deadline + Timestamp until which the merchant willing (and able) to give refunds + for the contract using Taler. Note that the Taler exchange will hold + the payment in escrow at least until this deadline. Until this time, + the merchant will be able to sign a message to trigger a refund to + the customer. After this time, it will no longer be possible to + refund the customer. Must be smaller than the pay_deadline. + +products + product description + Array of products that are being sold to the customer. Each entry + contains a tuple with the following values: + + description + Description of the product. + + quantity + Quantity of the items to be shipped. May specify a unit (``1 kg``) + or just the count. + + price + Price for quantity units of this product shipped to the given + delivery_location. Note that usually the sum of all of the prices + should add up to the total amount of the contract, but it may be + different due to discounts or because individual prices are + unavailable. + + product_id + Unique ID of the product in the merchant’s catalog. Can generally + be chosen freely as it only has meaning for the merchant, but + should be a number in the range :math:`[0,2^{51})`. + + taxes + Map of applicable taxes to be paid by the merchant. The label is + the name of the tax, i.e. VAT, sales tax or income tax, and the + value is the applicable tax amount. Note that arbitrary labels are + permitted, as long as they are used to identify the applicable tax + regime. Details may be specified by the regulator. This is used to + declare to the customer which taxes the merchant intends to pay, + and can be used by the customer as a receipt. The information is + also likely to be used by tax audits of the merchant. + + delivery_date + Time by which the product is to be delivered to the + delivery_location. + + delivery_location + This should give a label in the locations map, specifying where + the item is to be delivered. + + Values can be omitted if they are not applicable. For example, if a + purchase is about a bundle of products that have no individual prices + or product IDs, the product_id or price may not be specified in the + contract. Similarly, for virtual products delivered directly via the + fulfillment URI, there is no delivery location. + +merchant + address + This should give a label in the locations map, specifying where + the merchant is located. + + name + This should give a human-readable name for the merchant’s + business. + + jurisdiction + This should give a label in the locations map, specifying the + jurisdiction under which this contract is to be arbitrated. + +locations + location + Associative map of locations used in the contract. Labels for + locations in this map can be freely chosen and used whenever a + location is required in other parts of the contract. This way, if the + same location is required many times (such as the business address of + the customer or the merchant), it only needs to be listed (and + transmitted) once, and can otherwise be referred to via the label. A + non-exhaustive list of location attributes is the following: + + country + Name of the country for delivery, as found on a postal package, + i.e. “France”. + + state + Name of the state for delivery, as found on a postal package, i.e. + “NY”. + + region + Name of the region for delivery, as found on a postal package. + + province + Name of the province for delivery, as found on a postal package. + + city + Name of the city for delivery, as found on a postal package. + + ZIP code + ZIP code for delivery, as found on a postal package. + + street + Street name for delivery, as found on a postal package. + + street number + Street number (number of the house) for delivery, as found on a + postal package. + + name receiver name for delivery, either business or person name. + + Note that locations are not required to specify all of these fields, + and they is also allowed to have additional fields. Contract + renderers must render at least the fields listed above, and should + render fields that they do not understand as a key-value list. + +.. _GNU_002dLGPL: + +GNU-LGPL +======== + +license +LGPL +Version 2.1, February 1999 +:: + + Copyright © 1991, 1999 Free Software Foundation, Inc. + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + [This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence the + version number 2.1.] + +**Preamble** + +The licenses for most software are designed to take away your freedom to +share and change it. By contrast, the GNU General Public Licenses are +intended to guarantee your freedom to share and change free software—to +make sure the software is free for all its users. + +This license, the Lesser General Public License, applies to some +specially designated software—typically libraries—of the Free Software +Foundation and other authors who decide to use it. You can use it too, +but we suggest you first think carefully about whether this license or +the ordinary General Public License is the better strategy to use in any +particular case, based on the explanations below. + +When we speak of free software, we are referring to freedom of use, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish); that you receive source code or can get it if +you want it; that you can change the software and use pieces of it in +new free programs; and that you are informed that you can do these +things. + +To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for you +if you distribute copies of the library or if you modify it. + +For example, if you distribute copies of the library, whether gratis or +for a fee, you must give the recipients all the rights that we gave you. +You must make sure that they, too, receive or can get the source code. +If you link other code with the library, you must provide complete +object files to the recipients, so that they can relink them with the +library after making changes to the library and recompiling it. And you +must show them these terms so they know their rights. + +We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + +To protect each distributor, we want to make it very clear that there is +no warranty for the free library. Also, if the library is modified by +someone else and passed on, the recipients should know that what they +have is not the original version, so that the original author’s +reputation will not be affected by problems that might be introduced by +others. + +Finally, software patents pose a constant threat to the existence of any +free program. We wish to make sure that a company cannot effectively +restrict the users of a free program by obtaining a restrictive license +from a patent holder. Therefore, we insist that any patent license +obtained for a version of the library must be consistent with the full +freedom of use specified in this license. + +Most GNU software, including some libraries, is covered by the ordinary +GNU General Public License. This license, the GNU Lesser General Public +License, applies to certain designated libraries, and is quite different +from the ordinary General Public License. We use this license for +certain libraries in order to permit linking those libraries into +non-free programs. + +When a program is linked with a library, whether statically or using a +shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the entire +combination fits its criteria of freedom. The Lesser General Public +License permits more lax criteria for linking other code with the +library. + +We call this license the Lesser General Public License because it does +*Less* to protect the user’s freedom than the ordinary General Public +License. It also provides other free software developers Less of an +advantage over competing non-free programs. These disadvantages are the +reason we use the ordinary General Public License for many libraries. +However, the Lesser license provides advantages in certain special +circumstances. + +For example, on rare occasions, there may be a special need to encourage +the widest possible use of a certain library, so that it becomes a +de-facto standard. To achieve this, non-free programs must be allowed to +use the library. A more frequent case is that a free library does the +same job as widely used non-free libraries. In this case, there is +little to gain by limiting the free library to free software only, so we +use the Lesser General Public License. + +In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of free +software. For example, permission to use the GNU C Library in non-free +programs enables many more people to use the whole GNU operating system, +as well as its variant, the GNU/Linux operating system. + +Although the Lesser General Public License is Less protective of the +users’ freedom, it does ensure that the user of a program that is linked +with the Library has the freedom and the wherewithal to run that program +using a modified version of the Library. + +The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +“work based on the library” and a “work that uses the library”. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + +**TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION** + +1. This License Agreement applies to any software library or other + program which contains a notice placed by the copyright holder or + other authorized party saying it may be distributed under the terms + of this Lesser General Public License (also called “this License”). + Each licensee is addressed as “you”. + + A “library” means a collection of software functions and/or data + prepared so as to be conveniently linked with application programs + (which use some of those functions and data) to form executables. + + The “Library”, below, refers to any such software library or work + which has been distributed under these terms. A “work based on the + Library” means either the Library or any derivative work under + copyright law: that is to say, a work containing the Library or a + portion of it, either verbatim or with modifications and/or + translated straightforwardly into another language. (Hereinafter, + translation is included without limitation in the term + “modification”.) + + “Source code” for a work means the preferred form of the work for + making modifications to it. For a library, complete source code + means all the source code for all modules it contains, plus any + associated interface definition files, plus the scripts used to + control compilation and installation of the library. + + Activities other than copying, distribution and modification are not + covered by this License; they are outside its scope. The act of + running a program using the Library is not restricted, and output + from such a program is covered only if its contents constitute a + work based on the Library (independent of the use of the Library in + a tool for writing it). Whether that is true depends on what the + Library does and what the program that uses the Library does. + +2. You may copy and distribute verbatim copies of the Library’s + complete source code as you receive it, in any medium, provided that + you conspicuously and appropriately publish on each copy an + appropriate copyright notice and disclaimer of warranty; keep intact + all the notices that refer to this License and to the absence of any + warranty; and distribute a copy of this License along with the + Library. + + You may charge a fee for the physical act of transferring a copy, + and you may at your option offer warranty protection in exchange for + a fee. + +3. You may modify your copy or copies of the Library or any portion of + it, thus forming a work based on the Library, and copy and + distribute such modifications or work under the terms of Section 1 + above, provided that you also meet all of these conditions: + + a. The modified work must itself be a software library. + + b. You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. + + c. You must cause the whole of the work to be licensed at no charge + to all third parties under the terms of this License. + + d. If a facility in the modified Library refers to a function or a + table of data to be supplied by an application program that uses + the facility, other than as an argument passed when the facility + is invoked, then you must make a good faith effort to ensure + that, in the event an application does not supply such function + or table, the facility still operates, and performs whatever part + of its purpose remains meaningful. + + (For example, a function in a library to compute square roots has + a purpose that is entirely well-defined independent of the + application. Therefore, Subsection 2d requires that any + application-supplied function or table used by this function must + be optional: if the application does not supply it, the square + root function must still compute square roots.) + + These requirements apply to the modified work as a whole. If + identifiable sections of that work are not derived from the Library, + and can be reasonably considered independent and separate works in + themselves, then this License, and its terms, do not apply to those + sections when you distribute them as separate works. But when you + distribute the same sections as part of a whole which is a work + based on the Library, the distribution of the whole must be on the + terms of this License, whose permissions for other licensees extend + to the entire whole, and thus to each and every part regardless of + who wrote it. + + Thus, it is not the intent of this section to claim rights or + contest your rights to work written entirely by you; rather, the + intent is to exercise the right to control the distribution of + derivative or collective works based on the Library. + + In addition, mere aggregation of another work not based on the + Library with the Library (or with a work based on the Library) on a + volume of a storage or distribution medium does not bring the other + work under the scope of this License. + +4. You may opt to apply the terms of the ordinary GNU General Public + License instead of this License to a given copy of the Library. To + do this, you must alter all the notices that refer to this License, + so that they refer to the ordinary GNU General Public License, + version 2, instead of to this License. (If a newer version than + version 2 of the ordinary GNU General Public License has appeared, + then you can specify that version instead if you wish.) Do not make + any other change in these notices. + + Once this change is made in a given copy, it is irreversible for + that copy, so the ordinary GNU General Public License applies to all + subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of the + Library into a program that is not a library. + +5. You may copy and distribute the Library (or a portion or derivative + of it, under Section 2) in object code or executable form under the + terms of Sections 1 and 2 above provided that you accompany it with + the complete corresponding machine-readable source code, which must + be distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange. + + If distribution of object code is made by offering access to copy + from a designated place, then offering equivalent access to copy the + source code from the same place satisfies the requirement to + distribute the source code, even though third parties are not + compelled to copy the source along with the object code. + +6. A program that contains no derivative of any portion of the Library, + but is designed to work with the Library by being compiled or linked + with it, is called a “work that uses the Library”. Such a work, in + isolation, is not a derivative work of the Library, and therefore + falls outside the scope of this License. + + However, linking a “work that uses the Library” with the Library + creates an executable that is a derivative of the Library (because + it contains portions of the Library), rather than a “work that uses + the library”. The executable is therefore covered by this License. + Section 6 states terms for distribution of such executables. + + When a “work that uses the Library” uses material from a header file + that is part of the Library, the object code for the work may be a + derivative work of the Library even though the source code is not. + Whether this is true is especially significant if the work can be + linked without the Library, or if the work is itself a library. The + threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data + structure layouts and accessors, and small macros and small inline + functions (ten lines or less in length), then the use of the object + file is unrestricted, regardless of whether it is legally a + derivative work. (Executables containing this object code plus + portions of the Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may + distribute the object code for the work under the terms of Section + 6. Any executables containing that work also fall under Section 6, + whether or not they are linked directly with the Library itself. + +7. As an exception to the Sections above, you may also combine or link + a “work that uses the Library” with the Library to produce a work + containing portions of the Library, and distribute that work under + terms of your choice, provided that the terms permit modification of + the work for the customer’s own use and reverse engineering for + debugging such modifications. + + You must give prominent notice with each copy of the work that the + Library is used in it and that the Library and its use are covered + by this License. You must supply a copy of this License. If the work + during execution displays copyright notices, you must include the + copyright notice for the Library among them, as well as a reference + directing the user to the copy of this License. Also, you must do + one of these things: + + a. Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever + changes were used in the work (which must be distributed under + Sections 1 and 2 above); and, if the work is an executable linked + with the Library, with the complete machine-readable “work that + uses the Library”, as object code and/or source code, so that the + user can modify the Library and then relink to produce a modified + executable containing the modified Library. (It is understood + that the user who changes the contents of definitions files in + the Library will not necessarily be able to recompile the + application to use the modified definitions.) + + b. Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a + copy of the library already present on the user’s computer + system, rather than copying library functions into the + executable, and (2) will operate properly with a modified version + of the library, if the user installs one, as long as the modified + version is interface-compatible with the version that the work + was made with. + + c. Accompany the work with a written offer, valid for at least three + years, to give the same user the materials specified in + Subsection 6a, above, for a charge no more than the cost of + performing this distribution. + + d. If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the + above specified materials from the same place. + + e. Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + + For an executable, the required form of the “work that uses the + Library” must include any data and utility programs needed for + reproducing the executable from it. However, as a special exception, + the materials to be distributed need not include anything that is + normally distributed (in either source or binary form) with the + major components (compiler, kernel, and so on) of the operating + system on which the executable runs, unless that component itself + accompanies the executable. + + It may happen that this requirement contradicts the license + restrictions of other proprietary libraries that do not normally + accompany the operating system. Such a contradiction means you + cannot use both them and the Library together in an executable that + you distribute. + +8. You may place library facilities that are a work based on the + Library side-by-side in a single library together with other library + facilities not covered by this License, and distribute such a + combined library, provided that the separate distribution of the + work based on the Library and of the other library facilities is + otherwise permitted, and provided that you do these two things: + + a. Accompany the combined library with a copy of the same work based + on the Library, uncombined with any other library facilities. + This must be distributed under the terms of the Sections above. + + b. Give prominent notice with the combined library of the fact that + part of it is a work based on the Library, and explaining where + to find the accompanying uncombined form of the same work. + +9. You may not copy, modify, sublicense, link with, or distribute the + Library except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, link with, or distribute the + Library is void, and will automatically terminate your rights under + this License. However, parties who have received copies, or rights, + from you under this License will not have their licenses terminated + so long as such parties remain in full compliance. + +10. You are not required to accept this License, since you have not + signed it. However, nothing else grants you permission to modify or + distribute the Library or its derivative works. These actions are + prohibited by law if you do not accept this License. Therefore, by + modifying or distributing the Library (or any work based on the + Library), you indicate your acceptance of this License to do so, and + all its terms and conditions for copying, distributing or modifying + the Library or works based on it. + +11. Each time you redistribute the Library (or any work based on the + Library), the recipient automatically receives a license from the + original licensor to copy, distribute, link with or modify the + Library subject to these terms and conditions. You may not impose + any further restrictions on the recipients’ exercise of the rights + granted herein. You are not responsible for enforcing compliance by + third parties with this License. + +12. If, as a consequence of a court judgment or allegation of patent + infringement or for any other reason (not limited to patent issues), + conditions are imposed on you (whether by court order, agreement or + otherwise) that contradict the conditions of this License, they do + not excuse you from the conditions of this License. If you cannot + distribute so as to satisfy simultaneously your obligations under + this License and any other pertinent obligations, then as a + consequence you may not distribute the Library at all. For example, + if a patent license would not permit royalty-free redistribution of + the Library by all those who receive copies directly or indirectly + through you, then the only way you could satisfy both it and this + License would be to refrain entirely from distribution of the + Library. + + If any portion of this section is held invalid or unenforceable + under any particular circumstance, the balance of the section is + intended to apply, and the section as a whole is intended to apply + in other circumstances. + + It is not the purpose of this section to induce you to infringe any + patents or other property right claims or to contest validity of any + such claims; this section has the sole purpose of protecting the + integrity of the free software distribution system which is + implemented by public license practices. Many people have made + generous contributions to the wide range of software distributed + through that system in reliance on consistent application of that + system; it is up to the author/donor to decide if he or she is + willing to distribute software through any other system and a + licensee cannot impose that choice. + + This section is intended to make thoroughly clear what is believed + to be a consequence of the rest of this License. + +13. If the distribution and/or use of the Library is restricted in + certain countries either by patents or by copyrighted interfaces, + the original copyright holder who places the Library under this + License may add an explicit geographical distribution limitation + excluding those countries, so that distribution is permitted only in + or among countries not thus excluded. In such case, this License + incorporates the limitation as if written in the body of this + License. + +14. The Free Software Foundation may publish revised and/or new versions + of the Lesser General Public License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Library specifies a version number of this License which applies to + it and “any later version”, you have the option of following the + terms and conditions either of that version or of any later version + published by the Free Software Foundation. If the Library does not + specify a license version number, you may choose any version ever + published by the Free Software Foundation. + +15. If you wish to incorporate parts of the Library into other free + programs whose distribution conditions are incompatible with these, + write to the author to ask for permission. For software which is + copyrighted by the Free Software Foundation, write to the Free + Software Foundation; we sometimes make exceptions for this. Our + decision will be guided by the two goals of preserving the free + status of all derivatives of our free software and of promoting the + sharing and reuse of software generally. + + NO WARRANTY +16. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY + FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT + WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER + PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, + EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE + LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME + THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +17. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY + AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU + FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE + LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING + RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A + FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF + SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF + SUCH DAMAGES. + +**END OF TERMS AND CONDITIONS** + +**How to Apply These Terms to Your New Libraries** + +If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of +the ordinary General Public License). + +To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should have +at least the “copyright” line and a pointer to where the full notice is +found. + +:: + + one line to give the library's name and an idea of what it does. + Copyright (C) year name of author + + This library is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at + your option) any later version. + + This library 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 this library; if not, write to the Free Software + Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + USA. + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a “copyright disclaimer” for the library, if +necessary. Here is a sample; alter the names: + +:: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the library + `Frob' (a library for tweaking knobs) written by James Random Hacker. + + signature of Ty Coon, 1 April 1990 + Ty Coon, President of Vice + +That’s all there is to it! + +.. _GNU_002dFDL: + +GNU-FDL +======= + +license +GNU Free Documentation License +Version 1.3, 3 November 2008 +:: + + Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + http://fsf.org/ + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +1. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document free in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the author + and publisher a way to get credit for their work, while not being + considered responsible for modifications made by others. + + This License is a kind of “copyleft”, which means that derivative + works of the document must themselves be free in the same sense. It + complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to software + manuals; it can be used for any textual work, regardless of subject + matter or whether it is published as a printed book. We recommend + this License principally for works whose purpose is instruction or + reference. + +2. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice grants + a world-wide, royalty-free license, unlimited in duration, to use + that work under the conditions stated herein. The “Document”, below, + refers to any such manual or work. Any member of the public is a + licensee, and is addressed as “you”. You accept the license if you + copy, modify or distribute the work in a way requiring permission + under copyright law. + + A “Modified Version” of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A “Secondary Section” is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document’s overall + subject (or to related matters) and contains nothing that could fall + directly within that overall subject. (Thus, if the Document is in + part a textbook of mathematics, a Secondary Section may not explain + any mathematics.) The relationship could be a matter of historical + connection with the subject or with related matters, or of legal, + commercial, philosophical, ethical or political position regarding + them. + + The “Invariant Sections” are certain Secondary Sections whose titles + are designated, as being those of Invariant Sections, in the notice + that says that the Document is released under this License. If a + section does not fit the above definition of Secondary then it is + not allowed to be designated as Invariant. The Document may contain + zero Invariant Sections. If the Document does not identify any + Invariant Sections then there are none. + + The “Cover Texts” are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice that + says that the Document is released under this License. A Front-Cover + Text may be at most 5 words, and a Back-Cover Text may be at most 25 + words. + + A “Transparent” copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has been + arranged to thwart or discourage subsequent modification by readers + is not Transparent. An image format is not Transparent if used for + any substantial amount of text. A copy that is not “Transparent” is + called “Opaque”. + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTEX input format, SGML + or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and the + machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The “Title Page” means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, “Title + Page” means the text near the most prominent appearance of the + work’s title, preceding the beginning of the body of the text. + + The “publisher” means any person or entity that distributes copies + of the Document to the public. + + A section “Entitled XYZ” means a named subunit of the Document whose + title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To + “Preserve the Title” of such a section when you modify the Document + means that it remains a section “Entitled XYZ” according to this + definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and has + no effect on the meaning of this License. + +3. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You may + not use technical measures to obstruct or control the reading or + further copying of the copies you make or distribute. However, you + may accept compensation in exchange for copies. If you distribute a + large enough number of copies you must also follow the conditions in + section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + +4. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly have + printed covers) of the Document, numbering more than 100, and the + Document’s license notice requires Cover Texts, you must enclose the + copies in covers that carry, clearly and legibly, all these Cover + Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on + the back cover. Both covers must also clearly and legibly identify + you as the publisher of these copies. The front cover must present + the full title with all words of the title equally prominent and + visible. You may add other material on the covers in addition. + Copying with changes limited to the covers, as long as they preserve + the title of the Document and satisfy these conditions, can be + treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto adjacent + pages. + + If you publish or distribute Opaque copies of the Document numbering + more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will remain + thus accessible at the stated location until at least one year after + the last time you distribute an Opaque copy (directly or through + your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + +5. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document under + the conditions of sections 2 and 3 above, provided that you release + the Modified Version under precisely this License, with the Modified + Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in the + Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title as a + previous version if the original publisher of that version gives + permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has + fewer than five), unless they release you from this requirement. + + C. State on the Title page the name of the publisher of the Modified + Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version + under the terms of this License, in the form shown in the + Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document’s license + notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled “History”, Preserve its Title, and + add to it an item stating at least the title, year, new authors, + and publisher of the Modified Version as given on the Title Page. + If there is no section Entitled “History” in the Document, create + one stating the title, year, authors, and publisher of the + Document as given on its Title Page, then add an item describing + the Modified Version as stated in the previous sentence. + + J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the “History” section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + + K. For any section Entitled “Acknowledgements” or “Dedications”, + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered in + their text and in their titles. Section numbers or the equivalent + are not considered part of the section titles. + + M. Delete any section Entitled “Endorsements”. Such a section may + not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled “Endorsements” + or to conflict in title with any Invariant Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version’s + license notice. These titles must be distinct from any other section + titles. + + You may add a section Entitled “Endorsements”, provided it contains + nothing but endorsements of your Modified Version by various + parties—for example, statements of peer review or that the text has + been approved by an organization as the authoritative definition of + a standard. + + You may add a passage of up to five words as a Front-Cover Text, and + a passage of up to 25 words as a Back-Cover Text, to the end of the + list of Cover Texts in the Modified Version. Only one passage of + Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old one, + on explicit permission from the previous publisher that added the + old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + +6. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your combined + work in its license notice, and that you preserve all their Warranty + Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the original + author or publisher of that section if known, or else a unique + number. Make the same adjustment to the section titles in the list + of Invariant Sections in the license notice of the combined work. + + In the combination, you must combine any sections Entitled “History” + in the various original documents, forming one section Entitled + “History”; likewise combine any sections Entitled + “Acknowledgements”, and any sections Entitled “Dedications”. You + must delete all sections Entitled “Endorsements.” + +7. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert a + copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + +8. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other separate + and independent documents or works, in or on a volume of a storage + or distribution medium, is called an “aggregate” if the copyright + resulting from the compilation is not used to limit the legal rights + of the compilation’s users beyond what the individual works permit. + When the Document is included in an aggregate, this License does not + apply to the other works in the aggregate which are not themselves + derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document’s Cover Texts may be placed on + covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket the + whole aggregate. + +9. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled “Acknowledgements”, + “Dedications”, or “History”, the requirement (section 4) to Preserve + its Title (section 1) will typically require changing the actual + title. + +10. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, and + will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate the + licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the same + material does not give you any rights to use it. + +11. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + http://www.gnu.org/copyleft/. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered version + of this License “or any later version” applies to it, you have the + option of following the terms and conditions either of that + specified version or of any later version that has been published + (not as a draft) by the Free Software Foundation. If the Document + does not specify a version number of this License, you may choose + any version ever published (not as a draft) by the Free Software + Foundation. If the Document specifies that a proxy can decide which + future versions of this License can be used, that proxy’s public + statement of acceptance of a version permanently authorizes you to + choose that version for the Document. + +12. RELICENSING + + “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. A + “Massive Multiauthor Collaboration” (or “MMC”) contained in the site + means any set of copyrightable works thus published on the MMC site. + + “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + “Incorporate” means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is “eligible for relicensing” if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently incorporated + in whole or in part into the MMC, (1) had no cover texts or + invariant sections, and (2) were thus incorporated prior to November + 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +**ADDENDUM: How to use this License for your documents** + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + +:: + + Copyright (C) year your name. + 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, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: + +:: + + with the Invariant Sections being list their titles, with + the Front-Cover Texts being list, and with the Back-Cover Texts + being list. + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + +.. _Concept-Index: + +Concept Index +============= + +.. |image0| image:: arch-api.png + diff --git a/merchant-manual.rst b/merchant-manual.rst new file mode 100644 index 00000000..563a1e9f --- /dev/null +++ b/merchant-manual.rst @@ -0,0 +1,1228 @@ + + +This manual is for the GNU Taler merchant backend (version 0.5.0, 17 +August 2019), + +Copyright © 2016, 2017, 2019 Taler Systems SA + + 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”. + +The GNU Taler manual for Web shops +################################## + +This manual is for the GNU Taler merchant backend (version 0.5.0, 17 +August 2019), + +Copyright © 2016, 2017, 2019 Taler Systems SA + + 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: + +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: + +Architecture overview +--------------------- + +crypto-currency +KUDOS +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: + +- frontend + 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. + +- back office + 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. + +- backend + 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. + +- DBMS + Postgres + 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: + +:: + + Missing diagram image + +RESTful +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 [1]_ 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: + +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: + +Installation of dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following packages need to be installed before we can compile the +backend: + +- 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 sections will provide detailed instructions for installing +the libgnunetutil and GNU Taler exchange dependencies. + +.. _Installing-libgnunetutil: + +Installing libgnunetutil +~~~~~~~~~~~~~~~~~~~~~~~~ + +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: + +:: + + $ 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: + +Installing the GNU Taler exchange +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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: + +Installing the GNU Taler merchant backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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_002fLinux: + +Installing Taler on Debian GNU/Linux +------------------------------------ + +Wheezy +Debian +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 +======================================= + +taler-config +taler.conf +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 <#Using-taler_002dconfig>`__. + +.. _Backend-options: + +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: + + UNIX domain socket + TCP + :: + + [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. + + port + 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 + + currency + KUDOS + :: + + [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 + DBMS + 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 + + Postgres + 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 + exchange + To add an exchange to the list of trusted payment service providers, + you create a section with a name that starts with “exchange-”. In + that section, the following options need to be configured: + + - The “url” option specifies the exchange’s base URL. For example, + to use the Taler demonstrator use: + + :: + + $ taler-config -s EXCHANGE-demo -o URL \ + -V https://exchange.demo.taler.net/ + + - master key + The “master_key” option specifies the exchange’s master public key + in base32 encoding. For the Taler demonstrator, use: + + :: + + $ taler-config -s 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. + +Instances + instance + 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 accounts and key for signing contracts. It is + mandatory to configure a "default" instance. + + - The “KEYFILE” option specifies the file containing the instance’s + private signing key. For example, use: + + :: + + $ taler-config -s INSTANCE-default -o KEYFILE \ + -V '${TALER_CONFIG_HOME}/merchant/instace/default.key' + + - The “NAME” option specifies a human-readable name for the + instance. For example, use: + + :: + + $ taler-config -s INSTANCE-default -o NAME \ + -V 'Kudos Inc.' + + - The optional “TIP_EXCHANGE” and “TIP_EXCHANGE_PRIV_FILENAME” + options are discussed in Tipping visitors + +Accounts + wire format + In order to receive payments, the merchant backend needs to + communicate bank account details to the exchange. For this, the + configuration must include one or more sections named “ACCOUNT-name” + where ``name`` can be replaced by some human-readable word + identifying the account. For each section, the following options + should be provided: + + - The “URL” option specifies a ``payto://``-URL for the account of + the merchant. For example, use: + + :: + + $ taler-config -s ACCOUNT-bank -o NAME \ + -V 'payto://x-taler-bank/bank.demo.taler.net/4' + + - The “WIRE_RESPONSE” option specifies where Taler should store the + (salted) JSON encoding of the wire account. The file given will be + created if it does not exist. For example, use: + + :: + + $ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \ + -V '{$TALER_CONFIG_HOME}/merchant/bank.json' + + - The “PLUGIN” option specifies which wire plugin should be used for + this account. The plugin must support the wire method used by the + URL. For example, use: + + :: + + $ taler-config -s ACCOUNT-bank -o PLUGIN \ + -V taler_bank + + - For each ``instance`` that should use this account, you should set + ``HONOR_instance`` and ``ACTIVE_instance`` to YES. The first + option will cause the instance to accept payments to the account + (for existing contracts), while the second will cause the backend + to include the account as a possible option for new contracts. + + For example, use: + + :: + + $ taler-config -s ACCOUNT-bank -o HONOR_default \ + -V YES + $ taler-config -s ACCOUNT-bank -o ACTIVE_default \ + -V YES + + to use “account-bank” for the “default” instance. + + Depending on which PLUGIN you configured, you may additionally + specfiy authentication options to enable the plugin to use the + account. + + For example, with ``taler_bank`` plugin, use: + + :: + + $ taler-config -s ACCOUNT-bank -o TALER_BANK_AUTH_METHOD \ + -V basic + $ taler-config -s ACCOUNT-bank -o USERNAME \ + -V user42 + $ taler-config -s ACCOUNT-bank -o PASSWORD \ + -V pass42 + + Note that additional instances can be specified using different + tokens in the section name instead of ``default``. + +.. _Sample-backend-configuration: + +Sample backend configuration +---------------------------- + +configuration +The following is an example for a complete backend configuration: + +:: + + [TALER] + CURRENCY = KUDOS + + [MERCHANT] + SERVE = TCP + PORT = 8888 + DATABASE = postgres + + [MERCHANTDB-postgres] + CONFIG = postgres:///donations + + [INSTANCE-default] + KEYFILE = $DATADIR/key.priv + NAME = "Kudos Inc." + + [ACCOUNT-bank] + URL = payto://x-taler-bank/bank.demo.taler.net/4 + WIRE_RESPONSE = $DATADIR/bank.json + PLUGIN = taler_bank + HONOR_default = YES + ACTIVE_default = YES + TALER_BANK_AUTH_METHOD = basic + USERNAME = my_user + PASSWORD = 1234pass + + [EXCHANGE-trusted] + URL = https://exchange.demo.taler.net/ + MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 + CURRENCY = KUDOS + +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: + +Launching the backend +--------------------- + +backend +taler-merchant-httpd +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: + +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 EURL] [-m MURL] + +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 ``EURL`` (``MURL``). + +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 format +-------------------- + +configuration +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``. + + **Note** + + 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_002dconfig: + +Using taler-config +------------------ + +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 ACCOUNT-bank \ + -o WIRE_RESPONSE + $ taler-config -f -s ACCOUNT-bank \ + -o WIRE_RESPONSE + +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: + +Merchant key management +----------------------- + +merchant key +KEYFILE +The option “KEYFILE” in the section “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 INSTANCE-default \ + -o KEYFILE) + +.. _SEPA-configuration: + +Using the SEPA wire transfer method +----------------------------------- + +SEPA +EBICS +The following is a sample configuration for the SEPA wire transfer +method: [2]_. + +Then, to configure the EBICS backend for SEPA payments in EUR, the +following configuration options need to be set: + +:: + + $ taler-config -s TALER -o CURRENCY -V EUR + $ taler-config -s ACCOUNT-e -o PLUGIN -V ebics + $ taler-config -s ACCOUNT-e -o URL \ + -V payto://sepa/XY00111122223333444455556666 + $ taler-config -s ACCOUNT-e -o WIRE_RESPONSE + -V '${DATADIR}/b.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. + +.. _Tipping-visitors: + +Tipping visitors +---------------- + +tipping +Taler can also be used to tip Web site visitors. For example, you may be +running an online survey, and you want to reward those people that have +dutifully completed the survey. If they have installed a Taler wallet, +you can provide them with a tip for their deeds. This section describes +how to setup the Taler merchant backend for tipping. + +There are four basic steps that must happen to tip a visitor. + +.. _Configure-a-reserve-and-exchange-for-tipping: + +Configure a reserve and exchange for tipping +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +gnunet-ecc +reserve key +To tip users, you first need to create a reserve. A reserve is a pool of +money held in escrow at the Taler exchange. This is the source of the +funds for the tips. Tipping will fail (resulting in disappointed +visitors) if you do not have enough funds in your reserve! + +First, we configure the backend. You need to enable tipping for each +instance separately, or you can use an instance only for tipping. To +configure the “default” instance for tipping, use the following +configuration: + +:: + + [INSTANCE-default] + # this is NOT the tip.priv + KEYFILE = signing_key.priv + # replace the URL with the URL of the exchange you will use + TIP_EXCHANGE = https://exchange:443/ + # here put the path to the file created with "gnunet-ecc -g1 tip.priv" + TIP_RESERVE_PRIV_FILENAME = tip.priv + +Note that the KEYFILE option should have already been present for the +instance. It has nothing to do with the “tip.priv” file we created +above, and you should probably use a different file here. + +Instead of manually editing the configuration, you could also run: + +:: + + $ taler-config -s INSTANCE-default \ + -o TIP_RESERVE_PRIV_FILENAME \ + -V tip.priv + $ taler-config -s INSTANCE-default \ + -o TIP_EXCHANGE \ + -V https://exchange:443/ + +Next, to create the ``TIP_RESERVE_PRIV_FILENAME`` file, use: + +:: + + $ gnunet-ecc -g 1 \ + $(taler-config -f -s INSTANCE-default \ + -o TIP-RESERVE_PRIV_FILENAME) + +This will create a file with the private key that will be used to +identify the reserve. You need to do this once for each instance that is +configured to tip. + +Now you can (re)start the backend with the new configuration. + +.. _Fund-the-reserve: + +Fund the reserve +~~~~~~~~~~~~~~~~ + +reserve +close +To fund the reserve, you must first extract the public key from +“tip.priv”: + +:: + + $ gnunet-ecc --print-public-key \ + $(taler-config -f -s INSTANCE-default \ + -o TIP-RESERVE_PRIV_FILENAME) + +In our example, the output for the public key is: + +:: + + QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG + +You now need to make a wire transfer to the exchange’s bank account +using the public key as the wire transfer subject. The exchange’s bank +account details can be found in JSON format at +“https://exchange:443//wire/METHOD” where METHOD is the respective wire +method (i.e. “sepa”). Depending on the exchange’s operator, you may also +be able to find the bank details in a human-readable format on the main +page of the exchange. + +Make your wire transfer and (optionally) check at +“https://exchange:443/reserve/status/reserve_pub=QPE24X...” whether your +transfer has arrived at the exchange. + +Once the funds have arrived, you can start to use the reserve for +tipping. + +Note that an exchange will typically close a reserve after four weeks, +wiring all remaining funds back to the sender’s account. Thus, you +should plan to wire funds corresponding to a campaign of about two weeks +to the exchange initially. If your campaign runs longer, you should wire +further funds to the reserve every other week to prevent it from +expiring. + +.. _Authorize-a-tip: + +Authorize a tip +~~~~~~~~~~~~~~~ + +When your frontend has reached the point where a client is supposed to +receive a tip, it needs to first authorize the tip. For this, the +frontend must use the “/tip-authorize” API of the backend. To authorize +a tip, the frontend has to provide the following information in the body +of the POST request: + +- The amount of the tip + +- The justification (only used internally for the back-office) + +- The URL where the wallet should navigate next after the tip was + processed + +- The tip-pickup URL (see next section) + +In response to this request, the backend will return a tip token, an +expiration time and the exchange URL. The expiration time will indicate +how long the tip is valid (when the reserve expires). The tip token is +an opaque string that contains all the information needed by the wallet +to process the tip. The frontend must send this tip token to the browser +in a special “402 Payment Required” response inside the ``X-Taler-Tip`` +header. + +The frontend should handle errors returned by the backend, such as +missconfigured instances or a lack of remaining funds for tipping. + +.. _Picking-up-of-the-tip: + +Picking up of the tip +~~~~~~~~~~~~~~~~~~~~~ + +The wallet will POST a JSON object to the shop’s “/tip-pickup” handler. +The frontend must then forward this request to the backend. The response +generated by the backend can then be forwarded directly to the wallet. + +.. _Generate-payments: + +Generate payments +----------------- + +testing database +The merchant codebase offers the ``taler-merchant-benchmark`` tool to +populate the database with fake payments. This tool is in charge of +starting a merchant, exchange, and bank processes, and provide them all +the input to accomplish payments. Note that each component will use its +own configuration (as they would do in production). + +The tool takes all of the values it needs from the command line, with +some of them being mandatory. Among those, we have: + +- ``--currency=K`` Use currency *K*, for example to craft coins to + withdraw. + +- ``--bank-url=URL`` Assume that the bank is serving under the base URL + *URL*. This option is only actually used by the tool to check if the + bank was well launched. + +- ``--merchant-url=URL`` Reach the merchant through *URL*, for + downloading contracts and sending payments. + +The tool then comes with two operation modes: *ordinary*, and *corner*. +The first just executes normal payments, meaning that it uses the +default instance and make sure that all payments get aggregated. The +second gives the chance to leave some payments unaggregated, and also to +use merchant instances other than the default (which is, actually, the +one used by default by the tool). + +Note: the abilty of driving the aggregation policy is useful for testing +the backoffice facility. + +Any subcommand is also equipped with the canonical ``--help`` option, so +feel free to issue the following command in order to explore all the +possibilities. For example: + +:: + + $ taler-merchant-benchmark corner --help + +will show all the options offered by the *corner* mode. Among the most +interesting, there are: + +- ``--two-coins=TC`` This option instructs the tool to perform *TC* + many payments that use two coins, because normally only one coin is + spent per payment. + +- ``--unaggregated-number=UN`` This option instructs the tool to + perform *UN* (one coin) payments that will be left unaggregated. + +- ``--alt-instance=AI`` This option instructs the tool to perform + payments using the merchant instance *AI* (instead of the *default* + instance) + +As for the ``ordinary`` subcommand, it is worth explaining the following +options: + +- ``--payments-number=PN`` Instructs the tool to perform *PN* payments. + +- ``--tracks-number=TN`` Instructs the tool to perform *TN* tracking + operations. Note that the **total** amount of operations will be two + times *TN*, since "one" tracking operation accounts for + ``/track/transaction`` and ``/track/transfer``. This command should + only be used to see if the operation ends without problems, as no + actual measurement of performance is provided (despite of the + ’benchmark’ work used in the tool’s name). + +.. [1] + https://docs.docker.com/ + +.. [2] + Supporting SEPA is still work in progress; the backend will accept + this configuration, but the exchange will not work with SEPA today. diff --git a/onboarding.rst b/onboarding.rst new file mode 100644 index 00000000..b2fc829b --- /dev/null +++ b/onboarding.rst @@ -0,0 +1,386 @@ +Developer Onboarding Manual +########################### + + +Taler installation +================== + +Users serving Taler. +-------------------- + +On Gv.Taler.Net, there are four users that are set up to serve Taler on +the internet: + +- ``taler-test``: serves ``*.test.taler.net`` and gets automatically + built by Buildbot. + +- ``taler-internal``: serves ``*.int.taler.net``, and does *NOT* get + automatically built. + +The following two users are *NEVER* automatically built, and they both +serve ``*.demo.taler.net``. At any given time, only one is active and +serves the HTTP requests from the outside; the other one can so be +compiled without any downtime. If the compilation succeeds, the inactive +user can be switched to become active (see next section), and viceversa. + +- ``demo-blue`` + +- ``demo-green`` + +Compile and switch color. +------------------------- + +If the setup is already bootstrapped, then it should only be needed to +login as ’demo-X’ (with X being the inactive color); and then: + +:: + + $ source activate + $ taler-deployment-build + +and then switch the color by logging in as the *demo* user, and switch +the color with the following command: + +:: + + $ taler-deployment-switch-demo-X + +Full bootstrap. +--------------- + +In order to bootstrap a Taler installation under a empty home directory, +do: + +:: + + $ cd $HOME + $ git clone git://git.taler.net/deployment + +Then run the bootstrap script that will download all the repositories. + +:: + + $ ./deployment/bootstrap-taler <env> + + # <env> will make all the services serve *.<env>.taler.net + # + # Currently at Gv.Taler.Net, only 'demo' / 'test' / 'int' have + # DNS and certs configured. + +If successful, then activate the new environment with: + +:: + + source activate + +Compile and install all the components. + +:: + + $ taler-deployment-build + +Create the global configuration file. + +:: + + $ taler-deployment-config-generate + +Create (only) the folders where all the data needed by Taler will be +copied into (keys / JSONs with wire details / ..) + +:: + + $ taler-deployment-hier + +Create all the keys. + +:: + + $ taler-deployment-keyup + +Sign the ``/wire`` response for the exchange. + +:: + + $ taler-deployment-sign + +.. + + **Note** + + If the DB schema of merchant/exchange/auditor changed, at this point + it MIGHT be necessary to reset all the tables. To this regard, + consider running one of the following commands: + + :: + + # To reset the merchant DB. + $ taler-merchant-dbinit -r + + # To reset the exchange DB. + $ taler-exchange-dbinit -r + + # To reset the exchange DB. + $ taler-auditor-dbinit -r + +If all the steps succeeded, then it should be possible to launch all the +services. Give: + +:: + + $ taler-deployment-start + + # or restart, if you want to kill old processes and + # start new ones. + $ taler-deployment-restart + +Verify that all services are up and running: + +:: + + $ taler-deployment-arm -I + $ tail logs/<component>-<date>.log + +How to upgrade the code. +------------------------ + +Some repositories, especially the ones from the released components, +have a *stable* branch, that keeps older and more stable code. +Therefore, upon each release we must rebase those stable branches on the +master. + +The following commands do that: + +:: + + $ cd $REPO + + $ git pull origin master stable + $ git checkout stable + + # option a: resolve conflicts resulting from hotfixes + $ git rebase master + $ ... + + # option b: force stable to master + $ git update-ref refs/heads/stable master + + $ git push # possibly with --force + + # continue development + $ git checkout master + +.. _Testing-components: + +Testing components +================== + +This chapter is a VERY ABSTRACT description of how testing is +implemented in Taler, and in NO WAY wants to substitute the reading of +the actual source code by the user. + +In Taler, a test case is a array of ``struct TALER_TESTING_Command``, +informally referred to as ``CMD``, that is iteratively executed by the +testing interpreter. This latter is transparently initiated by the +testing library. + +However, the developer does not have to defined CMDs manually, but +rather call the proper constructor provided by the library. For example, +if a CMD is supposed to test feature ``x``, then the library would +provide the ``TALER_TESTING_cmd_x ()`` constructor for it. Obviously, +each constructor has its own particular arguments that make sense to +test ``x``, and all constructor are thoroughly commented within the +source code. + +Internally, each CMD has two methods: ``run ()`` and ``cleanup ()``. The +former contains the main logic to test feature ``x``, whereas the latter +cleans the memory up after execution. + +In a test life, each CMD needs some internal state, made by values it +keeps in memory. Often, the test has to *share* those values with other +CMDs: for example, CMD1 may create some key material and CMD2 needs this +key material to encrypt data. + +The offering of internal values from CMD1 to CMD2 is made by *traits*. A +trait is a ``struct TALER_TESTING_Trait``, and each CMD contains a array +of traits, that it offers via the public trait interface to other +commands. The definition and filling of such array happens transparently +to the test developer. + +For example, the following example shows how CMD2 takes an amount object +offered by CMD1 via the trait interface. + +Note: the main interpreter and the most part of CMDs and traits are +hosted inside the exchange codebase, but nothing prevents the developer +from implementing new CMDs and traits within other codebases. + +:: + + /* Withouth loss of generality, let's consider the + * following logic to exist inside the run() method of CMD1 */ + .. + + struct TALER_Amount *a; + /** + * the second argument (0) points to the first amount object offered, + * in case multiple are available. + */ + if (GNUNET_OK != TALER_TESTING_get_trait_amount_obj (cmd2, 0, &a)) + return GNUNET_SYSERR; + ... + + use(a); /* 'a' points straight into the internal state of CMD2 */ + +In the Taler realm, there is also the possibility to alter the behaviour +of supposedly well-behaved components. This is needed when, for example, +we want the exchange to return some corrupted signature in order to +check if the merchant backend detects it. + +This alteration is accomplished by another service called *twister*. The +twister acts as a proxy between service A and B, and can be programmed +to tamper with the data exchanged by A and B. + +Please refer to the Twister codebase (under the ``test`` directory) in +order to see how to configure it. + +.. _Releases: + +Releases +======== + +Release Process and Checklists +------------------------------ + +This document describes the process for releasing a new version of the +various Taler components to the official GNU mirrors. + +The following components are published on the GNU mirrors + +- taler-exchange (exchange.git) + +- taler-merchant (merchant.git) + +- talerdonations (donations.git) + +- talerblog (blog.git) + +- taler-bank (bank.git) + +- taler-wallet-webex (wallet-webex.git) + +Tagging +------- + +Tag releases with an **annotated** commit, like + +:: + + git tag -a v0.1.0 -m "Official release v0.1.0" + git push origin v0.1.0 + +Database for tests +------------------ + +For tests in the exchange and merchant to run, make sure that a database +*talercheck* is accessible by *$USER*. Otherwise tests involving the +database logic are skipped. + +Exchange, merchant +------------------ + +Set the version in ``configure.ac``. The commit being tagged should be +the change of the version. + +For the exchange test cases to pass, ``make install`` must be run first. +Without it, test cases will fail because plugins can’t be located. + +:: + + ./bootstrap + ./configure # add required options for your system + make dist + tar -xf taler-$COMPONENT-$VERSION.tar.gz + cd taler-$COMPONENT-$VERSION + make install check + +Wallet WebExtension +------------------- + +The version of the wallet is in *manifest.json*. The ``version_name`` +should be adjusted, and *version* should be increased independently on +every upload to the WebStore. + +:: + + ./configure + make dist + +Upload to GNU mirrors +--------------------- + +See +*https://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads* + +Directive file: + +:: + + version: 1.2 + directory: taler + filename: taler-exchange-0.1.0.tar.gz + +Upload the files in **binary mode** to the ftp servers. + +.. _Code: + +Code +==== + +Taler code is versioned via Git. For those users without write access, +all the codebases are found at the following URL: + +:: + + git://git.taler.net/<repository> + +A complete list of all the existing repositories is currently found at +``https://git.taler.net/``. Note: ``<repository>`` must NOT have the +``.git`` extension. + +.. _Bugtracking: + +Bugtracking +=========== + +Bug tracking is done with Mantis (https://www.mantisbt.org/). All the +bugs are then showed and managed at ``https://bugs.gnunet.org/``, under +the "Taler" project. A registration on the Web site is needed in order +to use the bug tracker. + +.. _Continuous-integration: + +Continuous integration +====================== + +CI is done with Buildbot (https://buildbot.net/), and builds are +triggered by the means of Git hooks. The results are published at +``https://buildbot.wild.gv.taler.net/``. + +In order to avoid downtimes, CI uses a "blue/green" deployment +technique. In detail, there are two users building code on the system, +the "green" and the "blue" user; and at any given time, one is running +Taler services and the other one is either building the code or waiting +for that. + +There is also the possibility to trigger builds manually, but this is +only reserved to "admin" users. + +.. _Code-coverage: + +Code coverage +============= + +Code coverage is done with the Gcov / Lcov +(http://ltp.sourceforge.net/coverage/lcov.php) combo, and it is run +\*nightly\* (once a day) by a Buildbot worker. The coverage results are +then published at ``https://lcov.taler.net/``. diff --git a/taler-bank.rst b/taler-bank.rst new file mode 100644 index 00000000..c85e0aa4 --- /dev/null +++ b/taler-bank.rst @@ -0,0 +1,190 @@ +The GNU Taler bank manual +######################### + +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). + +About this manual +----------------- + +This manual documents how the demonstrator bank interoperates with the +other GNU Taler components. The demonstrator bank implements a simple +closed banking system for the purpose of illustrating how GNU Taler +works in the Taler demo. It could also be used as a starting point for a +local/regional currency. Finally, “real” banks might use it as a +reference implementation for a tight integration with the GNU Taler +wallet. + +.. _Reference: + +Reference +========= + +.. _Bank_002dWallet-interaction: + +Bank-Wallet interaction +----------------------- + +The HTTP status code ``202 Accepted`` can be used by the bank website to +trigger operations in the user agent. The operation is determined by the +``X-Taler-Operation`` header. The following operations are understood: + +``create-reserve`` + Ask the Taler wallet to create a reserve and call back the bank with + the reserve public key. The following headers are mandatory: + + - ``X-Taler-Callback-Url``: URL that the wallet will visit when the + reserve was created and the user has selected an exchange. + + - ``X-Taler-Wt-Types``: JSON-encoded array of wire transfer types + that this bank supports. + + - ``X-Taler-Amount``: The amount that will be transferred to the + reserve. + + - ``X-Taler-Sender-Wire``: JSON-encoded wire account details of the + sender, that is the user that is currently logged in with the bank + and creates the reserve. + + The following header is optional: + + - ``X-Taler-Suggested-Exchange``: Exchange that the bank recommends + the customer to use. Note that this is a suggestion and can be + ignored by the wallet or changed by the user. + + On successful reserve creation, the wallet will navigate to the + callback URL (effectively requesting it with a GET) with the + following additional request parameters: + + - ``exchange``: The URL of the exchange selected by the user + + - ``wire_details``: The wire details of the exchange. + + - ``reserve_pub``: The reserve public key that the bank should + transmit to the exchange when transmitting the funds. + +``confirm-reserve`` + To secure the operation, the (demo) bank then shows a "CAPTCHA page" + – a real bank would instead show some PIN entry dialog or similar + security method – where the customer can finally prove she their + identity and thereby confirm the withdraw operation to the bank. + + Afterwards, the bank needs to confirm to the wallet that the user + completed the required steps to transfer funds to an exchange to + establish the reserve identified by the ``X-Taler-Reserve-Pub`` + header. + + This does not guarantee that the reserve is already created at the + exchange (since the actual money transfer might be executed + asynchronously), but it informs that wallet that it can start polling + for the reserve. + +.. _Bank_002dExchange-interaction: + +Bank-Exchange interaction +------------------------- + +The interaction between a bank and the exchange happens in two +situations: when a wallet withdraws coins, and when the exchange pays a +merchant. + +Withdraw +~~~~~~~~ + +Once a withdrawal operation with the wallet has been confirmed, the the +bank must wire transfer the withdrawn amount from the customer account +to the exchange’s. After this operation is done, the exchange needs to +be informed so that it will create the reserve. + +For the moment, the bank will use the exchange’s ``/admin/add/incoming`` +API, providing those arguments it got along the ``X-Taler-Callback-Url`` +URL. (In the future, the exchange will poll for this information.) +However, the bank will define two additional values for this API: +``execution_date`` (a operation’s timestamp), and ``transfer_details`` +(just a "seed" to make unique the operation). See +https://docs.taler.net/api/api-exchange.html#administrative-api-bank-transactions. + +The polling mechanism is possbile thanks to the ``/history`` API +provided by the bank. The exchange will periodically use this API to see +if it has received new wire transfers; upon receiving a new wire +transfer, the exchange will automatically create a reserve and allow the +money sender to withdraw. + +``GET /history`` + Ask the bank to return a list of money transactions related to a + caller’s bank account. + + - ``auth`` a string indicating the authentication method to use; + only ``"basic"`` value is accepted so far. The username and + password credentials have to be sent along the HTTP request + headers. Namely, the bank will look for the following two headers: + ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which + will contain those plain text credentials. + + - ``delta`` returns the first ``N`` records younger (older) than + ``start`` if ``+N`` (``-N``) is specified. + + - ``start`` according to delta, only those records with row id + strictly greater (lesser) than start will be returned. This + argument is optional; if not given, delta youngest records will be + returned. + + - ``direction`` optional argument taking values debit or credit, + according to the caller willing to receive both incoming and + outgoing, only outgoing, or only incoming records + + - ``account_number`` optional argument indicating the bank account + number whose history is to be returned. If not given, then the + history of the calling user will be returned + +Exchange pays merchant +~~~~~~~~~~~~~~~~~~~~~~ + +To allow the exchange to send payments to a merchant, the bank exposes +the ``/admin/add/incoming`` API to exchanges. + +``POST /admin/add/incoming`` + Ask the bank to transfer money from the caller’s account to the + receiver’s. + + - ``auth`` a string indicating the authentication method to use; + only ``"basic"`` value is accepted so far. The username and + password credentials have to be sent along the HTTP request + headers. Namely, the bank will look for the following two headers: + ``X-Taler-Bank-Username`` and ``X-Taler-Bank-Password``, which + will contain those plain text credentials. + + - ``amount`` a JSON object complying to the Taler amounts layout. + Namely, this object must contain the following fields: ``value`` + (number), ``fraction`` (number), and ``currency`` (string). + + - ``exchange_url`` a string indicating the calling exchange base + URL. The bank will use this value to define wire transfers subject + lines. + + - ``wtid`` a alphanumeric string that uniquely identifies this + transfer at the exchange database. The bank will use this value + too to define wire transfers subject lines. Namely, subject lines + will have the following format: ``'wtid exchange_url'``. + + - ``debit_account`` number indicating the exchange bank account. + NOTE: this field is currently ignored, as the bank can retrieve + the exchange account number from the login credentials. However, + in future release, an exchange could have multiple account at the + same bank, thereby it will have the chance to specify any of them + in this field. + + - ``credit_account`` bank account number that will receive the + transfer. Tipically the merchant account number. diff --git a/taler-exchange.rst b/taler-exchange.rst new file mode 100644 index 00000000..363a8f98 --- /dev/null +++ b/taler-exchange.rst @@ -0,0 +1,869 @@ +The GNU Taler Exchange Operator Manual +###################################### + +Introduction +============ + +This manual is an early draft that still needs significant editing work +to become readable. + +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 and +operate a GNU Taler exchange. + +Organizational prerequisites +---------------------------- + +Operating a GNU Taler exchange means that you are operating a payment +service provider, which means that you will most likely need a bank +license and/or follow applicable financial regulation. + +GNU Taler payment service providers generally need to ensure high +availability and have *really* good backups (synchronous replication, +asynchronous remote replication, off-site backup, 24/7 monitoring, +etc.). [1]_ This manual will not cover these aspects of operating a +payment service provider. + +We will assume that you can operate a (high-availability, +high-assurance) Postgres database. Furthermore, we expect some moderate +familiarity with the compilation and installation of free software +packages. You need to understand the cryptographic concepts of private +and public keys and must be able to protect private keys stored in files +on disk. An exchange uses an *offline* master key as well as *online* +keys. You are advised to secure your private master key and any copies +on encrypted, always-offline computers. Again, we assume that you are +familiar with good best practices in operational security, including +securing key material. [2]_ + +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. Similarly, the Taler exchange must +interact with a bank. The bank of the exchange holds the exchange’s +funds in an escrow account. + +When customers wire money to the escrow account, the bank notifies the +exchange about the incoming wire transfers. The exchange then creates a +*reserve* based on the subject of the wire transfer. The wallet which +knows the secret key matching the wire transfer subject can then +withdraw coins from the reserve, thereby draining it. The liability of +the exchange against the reserve is thereby converted into a liability +against digital coins issued by the exchange. When the customer later +spends the coins at a merchant, and the merchant *deposits* the coins at +the exchange, the exchange first *aggregates* the amount from multiple +deposits from the same merchant and then instructs its bank to make a +wire transfer to the merchant, thereby fulfilling its obligation and +eliminating the liability. The exchange charges *fees* for some or all +of its operations to cover costs and possibly make a profit. + +*Auditors* are third parties, for example financial regulators, that +verify that the exchange operates correctly. The same software is also +used to calculate the exchange’s profits, risk and liabilities by the +accountants of the exchange. + +The Taler software stack for an exchange consists of the following +components: + +- HTTP frontend + The HTTP frontend interacts with Taler wallets and merchant backends. + It is used to withdraw coins, deposit coins, refresh coins, issue + refunds, map wire transfers to Taler transactions, inquire about the + exchange’s bank account details, signing keys and fee structure. The + binary is the ``taler-exchange-httpd``. + +- Aggregator + The aggregator combines multiple deposits made by the same merchant + and (eventually) triggers wire transfers for the aggregate amount. + The merchant can control how quickly wire transfers are made. The + exchange may be charge a fee per wire transfer to discourage + excessively frequent transfers. The binary is the + ``taler-exchange-aggregator``. + +- Auditor + The auditor verifies that the transactions performed by the exchange + were done properly. It checks the various signatures, totals up the + amounts and alerts the operator to any inconsistencies. It also + computes the expected bank balance, revenue and risk exposure of the + exchange operator. The main binary is the ``taler-auditor``. + +- Wire plugin + A wire plugin enables the HTTP frontend to talk to the bank. Its role + is to allow the exchange to validate bank addresses (i.e. IBAN + numbers), for the aggregator to execute wire transfers and for the + auditor to query bank transaction histories. Wire plugins are + *plugins* as there can be many different implementations to deal with + different banking standards. Wire plugins are automatically located + and used by the exchange, aggregator and auditor. + +- DBMS + Postgres + The exchange requires a DBMS to stores the transaction history for + the Taler exchange and aggregator, and a (typically separate) DBMS + for the Taler auditor. For now, the GNU Taler reference implemenation + only supports Postgres, but the code could be easily extended to + support another DBMS. + +Installation +============ + +Please install the following packages before proceeding with the +exchange compilation. + +- GNU autoconf >= 2.69 + +- GNU automake >= 1.14 + +- GNU libtool >= 2.4 + +- GNU autopoint >= 0.19 + +- GNU libltdl >= 2.4 + +- GNU libunistring >= 0.9.3 + +- libcurl >= 7.26 (or libgnurl >= 7.26) + +- GNU libmicrohttpd >= 0.9.59 + +- GNU libgcrypt >= 1.6 + +- libjansson >= 2.7 + +- Postgres >= 9.6, 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://git.gnunet.org/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://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. + +Configuration +============= + +This chapter provides an overview of the exchange configuration. Or at +least eventually will do so, for now it is a somewhat wild description +of some of the options. + +Configuration format +-------------------- + +configuration +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``. + + **Note** + + 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_002dconfig-exchange: + +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 ACCOUNT-bank \ + -o WIRE_RESPONSE + $ taler-config -f -s ACCOUNT-bank \ + -o WIRE_RESPONSE + +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. + +.. _Keying: + +Keying +------ + +The exchange works with three types of keys: + +- master key + +- sign keys + +- denomination keys (see section Coins) + +- MASTER_PRIV_FILE: Path to the exchange’s master private file. + +- MASTER_PUBLIC_KEY: Must specify the exchange’s master public key. + +.. _Serving: + +Serving +------- + +The exchange can serve HTTP over both TCP and UNIX domain socket. + +The following values are to be configured in the section [exchange]: + +- 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—-). + +.. _Currency: + +Currency +-------- + +The exchange supports only one currency. This data is set under the +respective option currency in section [taler]. + +.. _Bank-account: + +Bank account +------------ + +To configure a bank account in Taler, we need to furnish four pieces of +information: + +- The ``payto://`` URL of the bank account, which uniquely idenfies the + account. Examples for such URLs include + ``payto://sepa/CH9300762011623852957`` for a bank account in the + single European payment area (SEPA) or + ``payto://x-taler-bank/localhost:8080/2`` for the 2nd bank account a + the Taler bank demonstrator running at ``localhost`` on port 8080. + The first part of the URL following ``payto://`` (“sepa” or + “x-taler-bank”) is called the wire method. + +- A matching wire plugin that implements a protocol to interact with + the banking system. For example, the EBICS plugin can be used for + SEPA transfers, or the “taler-bank” plugin can interact with the + Taler bank demonstrator. A wire plugin only supports one particular + wire method. Thus, you must make sure to pick a plugin that supports + the wire method used in the URL. + +- A file containing the signed JSON-encoded bank account details for + the /wire API. This is necessary as Taler supports offline signing + for bank accounts for additional security. + +- Finally, the plugin needs to be provided resources for authentication + to the respective banking service. The format in which the + authentication information must be provided depends on the wire + plugin. + +You can configure multiple accounts for an exchange by creating sections +starting with “account-” for the section name. You can ENABLE for each +account whether it should be used, and for what (incoming or outgoing +wire transfers): + +:: + + [account-1] + URL = "payto://sepa/CH9300762011623852957" + WIRE_RESPONSE = ${TALER_CONFIG_HOME}/account-1.json + + # Currently, only the 'taler_bank' plugin is implemented. + PLUGIN = <plugin_name_here> + + # Use for exchange-aggregator (outgoing transfers) + ENABLE_DEBIT = YES + # Use for exchange-wirewatch (and listed in /wire) + ENABLE_CREDIT = YES + + # Authentication options for the chosen plugin go here. + # (Next sections have examples of authentication mechanisms) + +The command line tool taler-exchange-wire is used to create the +``account-1.json`` file. For example, the utility may be invoked as +follows to create all of the WIRE_RESPONSE files (in the locations +specified by the configuration): + +:: + + $ taler-exchange-wire + +The generated file will be echoed by the exchange when serving +/wire [3]_ requests. + +.. _Wire-plugin-_0060_0060taler_005fbank_0027_0027: + +Wire plugin “taler_bank” +~~~~~~~~~~~~~~~~~~~~~~~~ + +x-taler-bank +taler_bank plugin +The ``taler_bank`` plugin implements the wire method “x-taler-bank”. + +The format of the ``payto://`` URL is +``payto://x-taler-bank/HOSTNAME[:PORT]``. + +For basic authentication, the ``taler_bank`` plugin only supports simple +password-based authentication. For this, the configuration must contain +the “USERNAME” and “PASSWORD” of the respective account at the bank. + +:: + + [account-1] + + # Bank account details here.. + # .. + + # Authentication options for the taler_bank plugin below: + + TALER_BANK_AUTH_METHOD = basic + USERNAME = exchange + PASSWORD = super-secure + +.. _Wire-plugin-_0060_0060ebics_0027_0027: + +Wire plugin “ebics” +~~~~~~~~~~~~~~~~~~~ + +The “ebics” wire plugin is not fully implemented and today does not +support actual wire transfers. + + **Note** + + The rationale behind having multiple 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. + +.. _Wire-fee-structure: + +Wire fee structure +~~~~~~~~~~~~~~~~~~ + +wire fee +fee +For each wire method (“sepa” or “x-taler-wire”, but not per plugin!) the +exchange configuration must specify applicable wire fees. This is done +in configuration sections of the format ``fees-METHOD``. There are two +types of fees, simple wire fees and closing fees. Wire fees apply +whenever the aggregator transfers funds to a merchant. Closing fees +apply whenever the exchange closes a reserve (sending back funds to the +customer). The fees must be constant for a full year, which is specified +as part of the name of the option. + +:: + + [fees-iban] + WIRE-FEE-2018 = EUR:0.01 + WIRE-FEE-2019 = EUR:0.01 + CLOSING-FEE-2018 = EUR:0.01 + CLOSING-FEE-2019 = EUR:0.01 + + [fees-x-taler-bank] + WIRE-FEE-2018 = KUDOS:0.01 + WIRE-FEE-2019 = KUDOS:0.01 + CLOSING-FEE-2018 = KUDOS:0.01 + CLOSING-FEE-2019 = KUDOS:0.01 + +.. _Database: + +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 CONFIG, under section [exchangedb-BACKEND]. + For example, the demo exchange is configured as follows: + +:: + + [exchange] + ... + DB = postgres + ... + + [exchangedb-postgres] + CONFIG = postgres:///talerdemo + +.. _Coins-denomination-keys: + +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: + +Keys duration +------------- + +Both signkeys and denom keys have a starting date. The option +lookahead_provide, under section [exchange], is such that only keys +whose starting date is younger than lookahead_provide will be issued by +the exchange. + +signkeys. The option lookahead_sign is such that, being t the time when +taler-exchange-keyup is run, taler-exchange-keyup will generate n +signkeys, where t + (n \* signkey_duration) = t + lookahead_sign. In +other words, we generate a number of keys which is sufficient to cover a +period of lookahead_sign. As for the starting date, the first generated +key will get a starting time of t, and the j-th key will get a starting +time of x + signkey_duration, where x is the starting time of the +(j-1)-th key. + +denom keys. The option lookahead_sign is such that, being t the time +when taler-exchange-keyup is run, taler-exchange-keyup will generate n +denom keys for each denomination, where t + (n \* duration_withdraw) = t ++ lookahead_sign. In other words, for each denomination, we generate a +number of keys which is sufficient to cover a period of lookahead_sign. +As for the starting date, the first generated key will get a starting +time of t, and the j-th key will get a starting time of x + +duration_withdraw, where x is the starting time of the (j-1)-th key. + +To change these settings, edit the following values in section +[exchange]: + +- SIGNKEY_DURATION: How long should one signing key be used? + +- LOOKAHEAD_SIGN: How much time we want to cover with our signing keys? + Note that if SIGNKEY_DURATION is bigger than LOOKAHEAD_SIGN, + ``taler-exchange-keyup`` will generate a quantity of signing keys + which is sufficient to cover all the gap. + +.. _Deployment: + +Deployment +========== + +.. _Keys-generation: + +Keys generation +--------------- + +Once the configuration is properly set up, all the keys can be generated +by the tool ``taler-exchange-keyup``. The following command generates +denomkeys and signkeys, plus the "blob" that is to be signed by the +auditor. + +:: + + taler-exchange-keyup -o blob + +*blob* contains data about denomkeys that the exchange operator needs to +get signed by every auditor he wishes (or is forced to) work with. + +In a normal scenario, an auditor must have some way of receiving the +blob to sign (Website, manual delivery, ..). Nonetheless, the exchange +admin can fake an auditor signature — for testing purposes — by running +the following command + +:: + + taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE + +Those arguments are all mandatory. + +- ``EXCHANGE_MASTER_PUB`` the base32 Crockford-encoded exchange’s + master public key. Tipically, this value lies in the configuration + option ``[exchange]/master_public_key``. + +- ``BLOB`` the blob generated in the previous step. + +- ``AUDITOR_URL`` the URL that identifies the auditor. + +- ``OUTPUT_FILE`` where on the disk the signed blob is to be saved. + +``OUTPUT_FILE`` must then be copied into the directory specified by the +option ``AUDITOR_BASE_DIR`` under the section ``[exchangedb]``. Assuming +``AUDITOR_BASE_DIR = ${HOME}/.local/share/taler/auditors``, the +following command will "add" the auditor identified by ``AUDITOR_URL`` +to the exchange. + +:: + + cp OUTPUT_FILE ${HOME}/.local/share/taler/auditors + +If the auditor has been correctly added, the exchange’s ``/keys`` +response must contain an entry in the ``auditors`` array mentioning the +auditor’s URL. + +.. _Database-upgrades: + +Database upgrades +----------------- + +Currently, there is no way to upgrade the database between Taler +versions. + +The exchange database can be re-initialized using: + +:: + + $ taler-exchange-dbinit -r + +However, running this command will result in all data in the database +being lost, which may result in significant financial liabilities as the +exchange can then not detect double-spending. Hence this operation must +not be performed in a production system. + +.. _Diagnostics: + +Diagnostics +=========== + +This chapter includes various (very unpolished) sections on specific +topics that might be helpful to understand how the exchange operates, +which files should be backed up. The information may also be helpful for +diagnostics. + +.. _Reserve-management: + +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. + +.. _Database-Scheme: + +Database Scheme +--------------- + +The exchange database must be initialized using taler-exchange-dbinit. +This tool creates the tables required by the Taler exchange to operate. +The tool also allows you to reset the Taler exchange database, which is +useful for test cases but should never be used in production. Finally, +taler-exchange-dbinit has a function to garbage collect a database, +allowing administrators to purge records that are no longer required. + +The database scheme used by the exchange look as follows: + +.. image:: exchange-db.png + +.. _Signing-key-storage: + +Signing key storage +------------------- + +The private online signing keys of the exchange are stored in a +subdirectory "signkeys/" of the "KEYDIR" which is an option in the +"[exchange]" section of the configuration file. The filename is the +starting time at which the signing key can be used in microseconds since +the Epoch. The file format is defined by the struct +TALER_EXCHANGEDB_PrivateSigningKeyInformationP: + +:: + + struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP { + struct TALER_ExchangePrivateKeyP signkey_priv; + struct TALER_ExchangeSigningKeyValidityPS issue; + }; + +.. _Denomination-key-storage: + +Denomination key storage +------------------------ + +The private denomination keys of the exchange are store in a +subdirectory "denomkeys/" of the "KEYDIR" which is an option in the +"[exchange]" section of the configuration file. "denomkeys/" contains +further subdirectories, one per denomination. The specific name of the +subdirectory under "denomkeys/" is ignored by the exchange. However, the +name is important for the "taler-exchange-keyup" tool that generates the +keys. The tool combines a human-readable encoding of the denomination +(i.e. for EUR:1.50 the prefix would be "EUR_1_5-", or for EUR:0.01 the +name would be "EUR_0_01-") with a postfix that is a truncated +Crockford32 encoded hash of the various attributes of the denomination +key (relative validity periods, fee structure and key size). Thus, if +any attributes of a coin change, the name of the subdirectory will also +change, even if the denomination remains the same. + +Within this subdirectory, each file represents a particular denomination +key. The filename is the starting time at which the signing key can be +used in microseconds since the Epoch. The format on disk begins with a +struct TALER_EXCHANGEDB_DenominationKeyInformationP giving the +attributes of the denomination key and the associated signature with the +exchange’s long-term offline key: + +:: + + struct TALER_EXCHANGEDB_DenominationKeyInformationP { + struct TALER_MasterSignatureP signature; + struct TALER_DenominationKeyValidityPS properties; + }; + +This is then followed by the variable-size RSA private key in +libgcrypt’s S-expression format, which can be decoded using +GNUNET_CRYPTO_rsa_private_key_decode(). + +.. _Revocations: + +Revocations +~~~~~~~~~~~ + +When an exchange goes out of business or detects that the private key of +a denomination key pair has been compromised, it may revoke some or all +of its denomination keys. At this point, the hashes of the revoked keys +must be returned as part of the ``/keys`` response under “payback”. +Wallets detect this, and then return unspent coins of the respective +denomination key using the ``/payback`` API. + +When a denomination key is revoked, a revocation file is placed into the +respective subdirectory of “denomkeys/”. The file has the same prefix as +the file that stores the struct +TALER_EXCHANGEDB_DenominationKeyInformationP information, but is +followed by the “.rev” suffix. It contains a 64-byte EdDSA signature +made with the master key of the exchange with purpose +``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``. If such a file is +present, the exchange must check the signature and if it is valid treat +the respective denomination key as revoked. + +Revocation files can be generated using the ``taler-exchange-keyup`` +command-line tool using the ``-r`` option. The Taler auditor will +instruct operators to generate revocations if it detects a key +compromise (which is possible more coins of a particular denomination +were deposited than issued). + +It should be noted that denomination key revocations should only happen +under highly unusual (“emergency”) conditions and not under normal +conditions. + +.. _Auditor-signature-storage: + +Auditor signature storage +------------------------- + +Signatures from auditors are stored in the directory specified in the +exchange configuration section "exchangedb" under the option +"AUDITOR_BASE_DIR". The exchange does not care about the specific names +of the files in this directory. + +Each file must contain a header with the public key information of the +auditor, the master public key of the exchange, and the number of signed +denomination keys: + +:: + + struct AuditorFileHeaderP { + struct TALER_AuditorPublicKeyP apub; + struct TALER_MasterPublicKeyP mpub; + uint32_t dki_len; + }; + +This is then followed by dki_len signatures of the auditor of type +struct TALER_AuditorSignatureP, which are then followed by another +dki_len blocks of type struct TALER_DenominationKeyValidityPS. The +auditor’s signatures must be signatures over the information of the +corresponding denomination key validity structures embedded in a struct +TALER_ExchangeKeyValidityPS structure using the +TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS purpose. + + +.. [1] + Naturally, you could operate a Taler exchange for a toy currency + without any real value on low-cost setups like a Raspberry Pi, but we + urge you to limit the use of such setups to research and education as + with GNU Taler data loss instantly results in financial losses. + +.. [2] + The current implementation does not make provisions for secret + splitting. Still, the use of a hardware security module (HSM) for + protecting private keys is adviseable, so please contact the + developers for HSM integration support. + +.. [3] + https://api.taler.net/api-exchange.html#wire-req + |
