diff options
| author | Florian Dold <florian.dold@gmail.com> | 2019-08-29 13:32:36 +0200 |
|---|---|---|
| committer | Florian Dold <florian.dold@gmail.com> | 2019-08-29 13:32:36 +0200 |
| commit | 4b82b7c171068c4722f10855391b9ca3a6ea20a9 (patch) | |
| tree | 637afae238c00e8ca6beb8e690f13bf161da5c72 | |
| parent | ba9335ec4c3578fdebfbec3072396bcda29d3425 (diff) | |
| download | docs-4b82b7c171068c4722f10855391b9ca3a6ea20a9.tar.gz docs-4b82b7c171068c4722f10855391b9ca3a6ea20a9.tar.bz2 docs-4b82b7c171068c4722f10855391b9ca3a6ea20a9.zip | |
texinfo support
| -rw-r--r-- | Makefile | 7 | ||||
| -rw-r--r-- | _exts/httpdomain/httpdomain.py | 2 | ||||
| -rw-r--r-- | conf.py | 6 | ||||
| -rw-r--r-- | index.rst | 8 | ||||
| -rw-r--r-- | merchant-api.rst | 1703 | ||||
| -rw-r--r-- | merchant-manual.rst | 1228 | ||||
| -rw-r--r-- | taler-bank.rst | 190 | ||||
| -rw-r--r-- | taler-exchange.rst | 869 |
8 files changed, 14 insertions, 3999 deletions
@@ -20,6 +20,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: texinfo-exchange help: @echo "Please use \`make <target>' where <target> is one of" @@ -148,6 +149,12 @@ texinfo: @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." +texinfo-exchange: + $(SPHINXBUILD) -b texinfo . $(BUILDDIR)/texinfo-exchange ./taler-bank.rst -D master_doc=taler-exchange + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo-exchange." + @echo "Run \`make' in that directory to run these through makeinfo" + info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." diff --git a/_exts/httpdomain/httpdomain.py b/_exts/httpdomain/httpdomain.py index a5e34716..f2569b5e 100644 --- a/_exts/httpdomain/httpdomain.py +++ b/_exts/httpdomain/httpdomain.py @@ -631,7 +631,7 @@ class HTTPDomain(Domain): 'any': {} } - indices = [HTTPIndex] + indices = [] @property def routes(self): @@ -272,10 +272,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'taler', u'GNU Taler Documentation', - u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff', - 'neuro', 'One-Click Cash Payments.', - 'Miscellaneous'), + ("taler-exchange-manual", "taler-exchange", "Taler Exchange Manual", "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"), + ("taler-merchant-manual", "taler-merchant", "Taler Merchant Manual", "GNU Taler team", "MENU ENTRY", "DESCRIPTION", "CATEGORY"), ] # Documents to append as an appendix to all manuals. @@ -53,10 +53,10 @@ interfaces between the core components of Taler. :maxdepth: 2 core/index - taler-exchange - merchant-manual - merchant-api - taler-bank + taler-exchange-manual + taler-merchant-manual + taler-merchant-api-tutorial + taler-bank-manual backoffice onboarding global-licensing diff --git a/merchant-api.rst b/merchant-api.rst deleted file mode 100644 index cc4ede93..00000000 --- a/merchant-api.rst +++ /dev/null @@ -1,1703 +0,0 @@ -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 deleted file mode 100644 index 563a1e9f..00000000 --- a/merchant-manual.rst +++ /dev/null @@ -1,1228 +0,0 @@ - - -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/taler-bank.rst b/taler-bank.rst deleted file mode 100644 index c85e0aa4..00000000 --- a/taler-bank.rst +++ /dev/null @@ -1,190 +0,0 @@ -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 deleted file mode 100644 index 363a8f98..00000000 --- a/taler-exchange.rst +++ /dev/null @@ -1,869 +0,0 @@ -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 - |