diff options
Diffstat (limited to 'taler-merchant-manual.rst')
| -rw-r--r-- | taler-merchant-manual.rst | 525 |
1 files changed, 306 insertions, 219 deletions
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 6d148068..60fe441f 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -16,7 +16,7 @@ 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 +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 @@ -27,14 +27,14 @@ offering regular currencies today. About this manual ----------------- -This tutorial targets system administrators who want to install a GNU +This manual 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 +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 +This first chapter of the manual 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 @@ -87,7 +87,7 @@ components: to process financial transactions with Taler. This manual primarily describes how to install and configure this backend. - A DBMS which stores the transaction history for the Taler backend. - For now, the GNU Taler reference implemenation only supports + For now, the GNU Taler reference implementation only supports Postgres, but the code could be easily extended to support another DBMS. Please review the Postgres documentation for details on how to configure the database. @@ -180,6 +180,17 @@ merchant, where the merchant specifies the specific terms of the order. After an order is created, it is *claimed* by a wallet. Once an order is claimed by a specific wallet, only that wallet will be able to pay for this order, to the exclusion of other wallets even if they see the same order URL. +Sharing order URLs is explicitly allowed: if a user shares and order URL +with another user, that other user should be given the opportunity to +purchase the same product. + +To prevent unauthorized wallets from claiming an order, merchants can specify +that claims require authorization in the form of a *claim token*. This is +useful in case the order ID is predictable (say because an existing order ID +scheme from the merchant frontend is used) and at the same time malicious +actors claiming orders is problematic (say because of limited stocks). The use +of claim tokens is optional, but if a claim token is used, it must be provided +to the wallet as part of the order URI. A wallet may *pay* for a claimed order, at which point the order turns into a (paid) contract. Orders have an expiration date after which the commercial @@ -189,12 +200,11 @@ allowing the stock to be sold in other orders. Once a contract has been paid, the merchant should fulfill the contract. It is possible for the merchant to *refund* a contract order, for example if the contract cannot be fulfilled after all. Refunds are only possible after the -customer paid and before the -exchange has *wired* the payment to the merchant. Once the funds have been -wired, refunds are no longer allowed by the Taler exchange. The *wire -deadline* specifies the latest time by which an exchange must wire the funds, -while the (earlier) *refund deadline* specifies the earliest time when an -exchange may wire the funds. +customer paid and before the exchange has *wired* the payment to the +merchant. Once the funds have been wired, refunds are no longer allowed by the +Taler exchange. The *wire deadline* specifies the latest time by which an +exchange must wire the funds, while the (earlier) *refund deadline* specifies +the earliest time when an exchange may wire the funds. Contract information is kept for legal reasons, typically to provide tax records in case of a tax audit. After the *legal expiration* (by default a @@ -285,8 +295,6 @@ backend: - libcurl >= 7.26 (or libgnurl >= 7.26) -- GNU libmicrohttpd >= 0.9.71 - - libqrencode >= 4.0.0 - GNU libgcrypt >= 1.6 @@ -301,13 +309,16 @@ backend: - Postgres >= 9.6, including libpq -- GNUnet (from Git) +- GNU libmicrohttpd >= 0.9.71 -- GNU Taler exchange (from Git) +- GNUnet (from Git or see release announcement) -Except for the last two, these are available in most GNU/Linux -distributions and should just be installed using the respective package -manager. +- GNU Taler exchange (from Git or see release announcement) + +Except for the last two, these are available in most GNU/Linux distributions +and should just be installed using the respective package manager. Be careful +with GNU libmicrohttpd; here, some distributions only include an older version +that will not work. The following sections will provide detailed instructions for installing the libgnunetutil and GNU Taler exchange dependencies. @@ -745,7 +756,7 @@ The following is an example for a complete backend configuration: [merchant-exchange-NAME] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ - MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 + MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0 # If currency does not match [TALER] section, the exchange # will be ignored! CURRENCY = KUDOS @@ -762,7 +773,7 @@ Given the above configuration, the backend will use a database named The backend will deposit the coins it receives to the exchange at https://exchange.demo.taler.net/, which has the master key -"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00". +"FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0". Please note that ``doc/config.sh`` will walk you through all configuration steps, showing how to invoke ``taler-config`` for each of @@ -813,14 +824,49 @@ Instance setup Before using the backend, you must at least configure the "default" instance. -Instances can be configured by POSTing a request to -:http:post:`/private/instances`. To create a first instance, create a file -``instance.json`` with an `InstanceConfigurationMessage` + +KUDOS Accounts +-------------- + +The main configuration data that must be provided for each instance +is the bank account information. + +In order to receive payments, the merchant backend needs to +communicate bank account details to the exchange. + +The bank account information is provided in the form of a ``payto://``-URI. +See RFC 8905 for the format of ``payto://``-URIs. + +For first tests, you should sign up for a KUDOS bank +account at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_. +In this case, the payto://-URI will be of the form +"payto://x-taler-bank/bank.demo.taler.net/$USERNAME" where "$USERNAME" +must be replaced with the name of the account that was established +at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_. + + +IBAN Accounts +------------- + +When deploying Taler with the real banking system, you primarily need to +change the currency of the configuration from KUDOS to the actual currency +(such as EUR, USD, CHF) and provide a payto://-URI of your real bank +account. In Europe, this will involve knowing your IBAN number. If you have an +IBAN, the corresponding payto://-URI is simply "payto://iban/$IBAN" where +"$IBAN" must be replaced with the actual IBAN number. + + +Setup +------ + +With the knowledge of the payto://-URI, instances can be configured by POSTing +a request to :http:post:`/private/instances`. To create a first instance, +create a file ``instance.json`` with an `InstanceConfigurationMessage` :: { - payto_uris : [ "payto://iban/IBANNUMBERHERE" ], + payto_uris : [ "$PAYTO_URI" ], id : "default", name: "example.com", address: { country : "zz" }, @@ -832,6 +878,16 @@ Instances can be configured by POSTing a request to default_pay_delay: { d_ms : 1209600000 }, } +In the text above, you must replace "$PAYTO_URI" with your actual +payto://-URI. Also, be sure to replace KUDOS with the fiat currency if the +setup is for an actual bank. The "name" field will be shown as the name of +your shop. The "address" field is expected to contain your shop's physical +address. The various defaults specify defaults for transaction fees your shop +is willing to cover, how long offers made to the customer are valid, and how +long the exchange has before it must wire the funds to your bank +account. Those defaults can be modified for individual orders. +For details, see the :ref:`contract terms <contract-terms>` specification. + You can then create the instance using: :: @@ -847,21 +903,6 @@ or purge (deleting all associated data) instances exist as well and are document in the :ref:`Merchant Backend API documentation <merchant-api>`. -Accounts --------- - -The main configuration data that must be provided for each instance -is the bank account information. - -In order to receive payments, the merchant backend needs to -communicate bank account details to the exchange. - -The bank account information is provided in the form of a ``payto://``-URL. - -See RFC XXXX for the format of ``payto://``-URLs. - - - .. _Secure-setup: Secure setup @@ -880,18 +921,30 @@ Using UNIX domain sockets ------------------------- To ensure that the merchant backend is not exposed directly to the network, -you should bind the backend to a UNIX domain socket: +you *should* bind the backend to a UNIX domain socket: :: $ taler-config -s MERCHANT -o SERVE -V UNIX $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock +Do not use a UNIX domain socket path in "/tmp": systemd (or other init +systems) may give Web servers a private "/tmp" thereby hiding UNIX domain +sockets created by other users/processes in "/tmp". + +If UNIX domain sockets are for some reason not possible, you *may* use a +host-based firewall to block access to the TCP port of the merchant backend, +but this is *not recommended*. Relying on NAT or network firewalls for access +control is gross negligence. + + Reverse proxy configuration --------------------------- -Assuming your domain name is /example.com/ and you have TLS configured, -a possible reverse proxy directive for Nginx would be: +Nginx +^^^^^ + +For Nginx, a possible basic reverse proxy configuration would be: :: @@ -901,9 +954,39 @@ a possible reverse proxy directive for Nginx would be: proxy_set_header X-Forwarded-Host "example.com"; proxy_set_header X-Forwarded-Proto "https"; -Leave out the last line if your Nginx reverse proxy does not have HTTPS -enabled. Make sure to restart the /taler-merchant-httpd/ process after -changing the ``SERVE`` configuration. +Note that the above assumes your domain name is /example.com/ and that you +have TLS configured. Leave out the last line if your Nginx reverse proxy does +not have HTTPS enabled. Make sure to restart the /taler-merchant-httpd/ +process after changing the ``SERVE`` configuration. + +Apache +^^^^^^ + +In Apache, make sure you have "mod_proxy", "mod_proxy_http" and +"mod_headers" enabled: + + :: + a2enmod proxy + a2enmod proxy_http + a2enmod headers + +Then configure your Apache reverse proxy like this (you may change the +endpoint): + + :: + + <Location "/"> + ProxyPass "unix:/some/path/here.sock|http://example.com/" + RequestHeader add "X-Forwarded-Proto" "https" + </Location> + +Note that the above again assumes your domain name is /example.com/ and that +you have TLS configured. Note that you must add the "https" header unless +your site is not available via TLS. + +The above configuration(s) are both incomplete. You must still additionally +setup access control! + Access control -------------- @@ -922,6 +1005,119 @@ Note that all of the other endpoints (without /private/) are expected to be fully exposed to the Internet, and wallets may have to interact with those endpoints directly without client authentication. +Nginx +^^^^^ + +For Nginx, you can implement token-based merchant backend authentication as +follows: + + :: + + location ~ /private/ { + if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") { + return 401; + } + proxy_pass ...; // as above + } + +Here, "SECURITYTOKEN" should be replaced with the actual shared secret. Note +that the "~" ensures that the above matches all endpoints that include the +string "/private/. If you only run a single instance, you could simply +specify "/private/" without the "~" to only configure the access policy for +the default instance. + +If you are running different instances on the same backend, you +likely will want to specify different access control tokens for +each instance: + + :: + + location ~ ^/instances/foo/private/ { + if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") { + return 401; + } + proxy_pass ...; // as above + } + location ~ ^/instances/bar/private/ { + if ($http_authorization !~ "(?i)ApiKey BARTOKEN") { + return 401; + } + proxy_pass ...; // as above + } + location /private/ { + if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") { + return 401; + } + proxy_pass ...; // as above + } + location ~ /private/ { + return 401; // access to instances not explicitly configured is forbidden + } + +Apache +^^^^^^ + +For Apache, you should first enable "mod_rewrite": + + :: + a2enmod rewrite + +Then, you can restrict to an access control token using: + + :: + <Location "/"> + RewriteEngine On + RewriteCond "%{HTTP:AUTHORIZATION}" "!=SECURITYTOKEN" + RewriteRule "(.+)/private/" "-" [F] + + ProxyPass "unix:/some/path/here.sock|http://example.com/" + </Location> + +Here, "SECURITYTOKEN" should be replaced with the actual shared secret. Note +that the "(.+)" ensures that the above matches all endpoints that include the +string "/private/. If you only run a single instance, you could simply +specify "/private/" without the "~" to only configure the access policy for +the default instance. + +If you are running different instances on the same backend, you +likely will want to specify different access control tokens for +each instance: + + :: + <Location "/instances/foo/"> + RewriteEngine On + RewriteCond "%{HTTP:AUTHORIZATION}" "!=FOOTOKEN" + RewriteRule "/instances/foo/private/" "-" [F] + + ProxyPass ... # as above + </Location> + + <Location "/instances/bar/"> + RewriteEngine On + RewriteCond "%{HTTP:AUTHORIZATION}" "!=BARTOKEN" + RewriteRule "/instances/bar/private/" "-" [F] + + ProxyPass ... # as above + </Location> + + <Location "/"> + RewriteEngine On + RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN" + RewriteRule "/private/" "-" [F] + RewriteRule "(.+)/private/" "-" [F] # reject all others + + ProxyPass ... # as above + </Location> + +Please note that these are simply examples of how one could use Nginx or +Apache2 for access control. Both HTTP servers support many other forms of +authentication, including TLS client certificates, HTTP basic and digest +authentication and others, which can all be used (possibly in combination) to +restrict access to the internal API to authorized clients. + +System admininistrators are strongly advised to test their access control +setup before going into production! + Customization ============= @@ -962,7 +1158,9 @@ Limitations ----------- All of the static files must fit into memory and it must be possible for the -process to hold open file handles for all of these files. +process to hold open file handles for all of these files. You may want +to increase the "ulimit" of the taler-merchant-httpd process if you have +templates for many languages. The backend determines the mime type based on the file's extension. The list of supported extensions is hard-coded and includes common text and image @@ -1100,7 +1298,7 @@ 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. +misconfigured instances or a lack of remaining funds for tipping. .. _Picking-up-of-the-tip: @@ -1123,7 +1321,7 @@ Advanced topics Database Scheme --------------- -The merchant database must be initialized using taler-merchant-dbinit. +The merchant database must be initialized using /taler-merchant-dbinit/. This tool creates the tables required by the Taler merchant to operate. The tool also allows you to reset the Taler merchant database, which is useful for test cases but should never be used in production. Finally, @@ -1265,78 +1463,91 @@ option. +Advanced experimental features +============================== + +This section describes features that most merchants will not +need, or will not need initially. + .. _MerchantBenchmarking: Benchmarking ------------ -.. index:: testing database - -NOTE: This section is dated and should be reviewed! - -FIXME: which coin denominations are needed for the benchmark? - -FIXME: provide "minimum" configuration file! - -FIXME: explain Postgres setup! - +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). -Setup: create Exchange account and two user accounts ``42`` and ``43`` at -the bank: +The main goal of the benchmarking tool is to serve as a starting point (!) for +merchants that are interested in developing stress tests to see how far their +infrastructure can scale. -:: +The current tool has already a few options, but we expect that to deliver +*relevant* results it will need to be customized to better reflect the +workload of a particular merchant. This customization would at this point +likely involve writing (C) code. We welcome contributions to make it easier +to customize the benchmark and/or to cover more realistic workloads from the +start. - $ taler-bank-manage django add_bank_account Exchange - $ taler-bank-manage django add_bank_account 42 - $ taler-bank-manage django add_bank_account 43 -Setup exchange password using: +Benchmark setup +--------------- -:: +The taler-merchant-benchmark tool will automatically launch and configure the +exchange, (Python) bank and other tools required for the benchmark. However, +the configuration file must be provided and have consistent options set. The +options that require special care include the exchange's public key (which +must match the private key in the file specified by the configuration), the +currency (which must be consistent across the file), the denomination +structure (which must enable payments in the range of 100ths of the unit +currency (often called cents). Furthermore, the benchmark will set the +Exchange bank account password to be "x", so the configuration must also +specify "x" for the passphrase. Finally, the bank must be configured to allow +for substantial debt least the transactions by the benchmark run out of +digital cash. - $ taler-bank-manage django changepassword_unsafe Exchange PASSWORD +A relatively minimal configuration could look like this: -Configure merchant and exchange, then run: +.. literalinclude:: merchant-benchmark.conf -:: - $ taler-exchange-dbinit - $ taler-exchange-keyup - $ taler-merchant-dbinit +Note that the public key must match the exchange's +private key and that the Postgres database must +exist before launching the benchmark. You also +will need to ensure that the Exchange's +details are setup, usually by running -Launch bank, exchange and merchant backends: + :: -:: + taler-exchange-wire -c $CONFIG_FILE + taler-exchange-keyup -c $CONFIG_FILE - $ taler-bank-manage serve-http & - $ taler-exchange-httpd & - $ taler-merchant-httpd & +where "$CONFIG_FILE" should be replaced by +the configuration file that is to be used. -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). +Running the benchmark command +----------------------------- The tool takes all of the values it needs from the command line, with -some of them being mandatory. Among those, we have: - -- ``--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. +one of them being mandatory: -- ``--merchant-url=URL`` Reach the merchant through *URL*, for - downloading contracts and sending payments. +- ``--exchange-account=SECTION`` Specifies which configuration + section specifies the bank account for the exchange that + should be used for the benchmark. For the example + configuration above, the SECTION value provided must be + "exchange-account-exchange". -The tool then comes with two operation modes: *ordinary*, and *corner*. +The tool 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 +Note: the ability of driving the aggregation policy is useful for testing the backoffice facility. Any subcommand is also equipped with the canonical ``--help`` option, so @@ -1357,10 +1568,6 @@ interesting, there are: - ``--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: @@ -1374,135 +1581,15 @@ options: actual measurement of performance is provided (despite of the ’benchmark’ work used in the tool’s name). -.. [1] - https://docs.docker.com/ - - - -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. - -This chapter contains some legacy documentation we need to update -before it can be considered even reasonably accurate. - - -Taler payments generator ------------------------- - -This tool does not exist anymore right now... - -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 +Temporarily Abandoned Features +============================== +.. [1] + https://docs.docker.com/ -Legacy -====== Installing Taler using Docker ----------------------------- |