From bf0a7c8dac654f250aae565efafdef79b27a2552 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 4 Apr 2020 14:23:34 +0200 Subject: document current option names --- taler-merchant-manual.rst | 64 +++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 32 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 0ac0ca55..771a1a0e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -50,8 +50,8 @@ operating a basic backend. Architecture overview --------------------- -crypto-currency -KUDOS +:keywords: crypto-currency +:keywords: 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 @@ -224,7 +224,7 @@ the libgnunetutil and GNU Taler exchange dependencies. Installing libgnunetutil ~~~~~~~~~~~~~~~~~~~~~~~~ -GNUnet +:keywords: 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. @@ -250,7 +250,7 @@ which requires you to run the last step as ``root``. Installing the GNU Taler exchange ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -exchange +:keywords: exchange After installing GNUnet, you can download and install the exchange as follows: @@ -276,7 +276,7 @@ installed GNUnet to ``/usr/local`` in the previous step. Installing the GNU Taler merchant backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -backend +:keywords: backend The following steps assume all dependencies are installed. Use the following commands to download and install the merchant backend: @@ -303,8 +303,8 @@ GNUnet to ``/usr/local`` in the previous steps. Installing Taler on Debian GNU/Linux ------------------------------------ -Wheezy -Debian +:keywords: Wheezy +:keywords: Debian Debian wheezy is too old and lacks most of the packages required. On Debian jessie, only GNU libmicrohttpd needs to be compiled from @@ -359,8 +359,8 @@ if you used the Debian wheezy instructions above, you need to pass How to configure the merchant’s backend ======================================= -taler-config -taler.conf +:keywords: taler-config +:keywords: 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 @@ -384,8 +384,8 @@ Service address The following option sets the transport layer address used by the merchant backend: - UNIX domain socket - TCP +:keywords: UNIX domain socket +:keywords: TCP :: [MERCHANT]/SERVE = TCP | UNIX @@ -404,7 +404,7 @@ Service address operating system, the use of a UNIX domain socket is recommended to avoid accidentally exposing the backend to the network. - port +:keywords: port To run the Taler backend on TCP port 8888, use: :: @@ -416,8 +416,8 @@ Currency Which currency the Web shop deals in, i.e. “EUR” or “USD”, is specified using the option - currency - KUDOS +:keywords: currency +:keywords: KUDOS :: [TALER]/CURRENCY @@ -431,7 +431,7 @@ Currency $ taler-config -s TALER -o CURRENCY -V KUDOS Database - DBMS +:keywords: DBMS In principle is possible for the backend to support different DBMSs. The option @@ -451,7 +451,7 @@ Database [merchantdb-postgres]/config - Postgres +:keywords: 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 @@ -481,7 +481,7 @@ Database -V postgres:///$DBNAME Exchange - exchange +:keywords: 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: @@ -510,7 +510,7 @@ Exchange per currency. Instances - instance +:keywords: 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 @@ -536,7 +536,7 @@ Instances options are discussed in Tipping visitors Accounts - wire format +:keywords: 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” @@ -586,7 +586,7 @@ Accounts Sample backend configuration ---------------------------- -configuration +:keywords: configuration The following is an example for a complete backend configuration: :: @@ -615,8 +615,8 @@ The following is an example for a complete backend configuration: USERNAME = my_user PASSWORD = 1234pass - [EXCHANGE-trusted] - URL = https://exchange.demo.taler.net/ + [merchant-exchange-trusted] + EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 CURRENCY = KUDOS @@ -636,7 +636,7 @@ them. Launching the backend --------------------- -backend +:keywords: backend taler-merchant-httpd Assuming you have configured everything correctly, you can launch the merchant backend using: @@ -776,7 +776,7 @@ Advanced topics Configuration format -------------------- -configuration +:keywords: 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 @@ -849,7 +849,7 @@ configuration file used in our demos. See under ``deployment/config``. Using taler-config ------------------ -taler-config +:keywords: 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. @@ -903,8 +903,8 @@ option. Merchant key management ----------------------- -merchant key -KEYFILE +:keywords: merchant key +:keywords: 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. @@ -922,7 +922,7 @@ public key using the ``gnunet-ecc`` command-line tool: Tipping visitors ---------------- -tipping +:keywords: 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, @@ -936,8 +936,8 @@ There are four basic steps that must happen to tip a visitor. Configure a reserve and exchange for tipping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -gnunet-ecc -reserve key +:keywords: gnunet-ecc +:keywords: 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 @@ -992,8 +992,8 @@ Now you can (re)start the backend with the new configuration. Fund the reserve ~~~~~~~~~~~~~~~~ -reserve -close +:keywords: reserve +:keywords: close To fund the reserve, you must first extract the public key from “tip.priv”: -- cgit v1.2.3 From a42a6a69879208f8960384e4ecf2426bc467e67e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 4 Apr 2020 17:22:51 +0200 Subject: update docs --- core/api-exchange.rst | 2 +- core/api-merchant.rst | 37 +++++++++++++++++++++++++++++++++++++ taler-merchant-manual.rst | 23 ++++++++++++++++++++++- 3 files changed, 60 insertions(+), 2 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/core/api-exchange.rst b/core/api-exchange.rst index c6186284..536458ec 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -96,7 +96,7 @@ possibly by using HTTPS. .. ts:def:: ExchangeKeysResponse interface ExchangeKeysResponse { - // libtool-style representation of the Taler protocol version, see + // libtool-style representation of the Exchange protocol version, see // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning // The format is "current:revision:age". version: string; diff --git a/core/api-merchant.rst b/core/api-merchant.rst index b9dac413..e60ea8b0 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -25,6 +25,22 @@ Merchant Backend API .. contents:: Table of Contents + +-------------------- +Compatibility Checks +-------------------- + +.. http:get:: /config + + Return the protocol version and currency supported by this merchant backend. + This endpoint is deprecated, clients should migrate to the (identical) + /public/version API. + + **Response:** + + :status 200 OK: + The exchange accepted all of the coins. The body is a `VersionResponse`. + ------------------ Receiving Payments ------------------ @@ -973,6 +989,27 @@ The ``/public/*`` endpoints are publicly exposed on the internet and accessed both by the user's browser and their wallet. +.. http:get:: /public/config + + Return the protocol version and currency supported by this merchant backend. + + **Response:** + + :status 200 OK: + The exchange accepted all of the coins. The body is a `VersionResponse`. + + .. ts:def:: VersionResponse + + interface VersionResponse { + // libtool-style representation of the Merchant protocol version, see + // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning + // The format is "current:revision:age". + version: string; + + // Currency supported by this backend. + currency: string; + } + .. http:post:: /public/pay Pay for a proposal by giving a deposit permission for coins. Typically used by diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 771a1a0e..825c7149 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -52,6 +52,7 @@ Architecture overview :keywords: crypto-currency :keywords: 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 @@ -225,6 +226,7 @@ Installing libgnunetutil ~~~~~~~~~~~~~~~~~~~~~~~~ :keywords: 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. @@ -251,6 +253,7 @@ Installing the GNU Taler exchange ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :keywords: exchange + After installing GNUnet, you can download and install the exchange as follows: @@ -277,6 +280,7 @@ Installing the GNU Taler merchant backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :keywords: backend + The following steps assume all dependencies are installed. Use the following commands to download and install the merchant backend: @@ -305,6 +309,7 @@ Installing Taler on Debian GNU/Linux :keywords: Wheezy :keywords: Debian + Debian wheezy is too old and lacks most of the packages required. On Debian jessie, only GNU libmicrohttpd needs to be compiled from @@ -361,6 +366,7 @@ How to configure the merchant’s backend :keywords: taler-config :keywords: 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 @@ -386,6 +392,7 @@ Service address :keywords: UNIX domain socket :keywords: TCP + :: [MERCHANT]/SERVE = TCP | UNIX @@ -418,6 +425,7 @@ Currency :keywords: currency :keywords: KUDOS + :: [TALER]/CURRENCY @@ -432,6 +440,7 @@ Currency Database :keywords: DBMS + In principle is possible for the backend to support different DBMSs. The option @@ -452,6 +461,7 @@ Database [merchantdb-postgres]/config :keywords: 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 @@ -482,6 +492,7 @@ Database Exchange :keywords: 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: @@ -511,6 +522,7 @@ Exchange Instances :keywords: 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 @@ -537,6 +549,7 @@ Instances Accounts :keywords: 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” @@ -587,6 +600,7 @@ Sample backend configuration ---------------------------- :keywords: configuration + The following is an example for a complete backend configuration: :: @@ -637,7 +651,8 @@ Launching the backend --------------------- :keywords: backend -taler-merchant-httpd +:keywords: taler-merchant-httpd + Assuming you have configured everything correctly, you can launch the merchant backend using: @@ -777,6 +792,7 @@ Configuration format -------------------- :keywords: 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 @@ -850,6 +866,7 @@ Using taler-config ------------------ :keywords: 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. @@ -905,6 +922,7 @@ Merchant key management :keywords: merchant key :keywords: 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. @@ -923,6 +941,7 @@ Tipping visitors ---------------- :keywords: 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, @@ -938,6 +957,7 @@ Configure a reserve and exchange for tipping :keywords: gnunet-ecc :keywords: 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 @@ -994,6 +1014,7 @@ Fund the reserve :keywords: reserve :keywords: close + To fund the reserve, you must first extract the public key from “tip.priv”: -- cgit v1.2.3 From 8af00dec7fb5743b343d8a212aff0f1224f7338a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 22 May 2020 12:17:14 +0200 Subject: new GNUnet dependencies --- taler-merchant-manual.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 825c7149..6959e311 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -205,9 +205,13 @@ backend: - GNU libgcrypt >= 1.6 +- libsodium >= 1.0 + +- libargon2 >= 20171227 (GNUnet 0.13 needs it to build, not actively used by GNU Taler) + - libjansson >= 2.7 -- Postgres >= 9.4, including libpq +- Postgres >= 9.6, including libpq - libgnunetutil (from Git) -- cgit v1.2.3 From ce1034a12e0e1857a13c696384fc5dd41c3e3b4d Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 22 May 2020 12:17:34 +0200 Subject: new GNUnet dependencies --- taler-merchant-manual.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 6959e311..ca952d29 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -201,7 +201,7 @@ backend: - libcurl >= 7.26 (or libgnurl >= 7.26) -- GNU libmicrohttpd >= 0.9.39 +- GNU libmicrohttpd >= 0.9.59 - GNU libgcrypt >= 1.6 -- cgit v1.2.3 From a7ca300846ba7d94cb8d2660299977bb26a6ce0f Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 30 May 2020 18:58:09 +0200 Subject: update manual to reference DB schema --- core/api-merchant.rst | 5 +- merchant-db.png | Bin 0 -> 459305 bytes taler-exchange-manual.rst | 2 +- taler-merchant-manual.rst | 146 +++++++++++++++++++++++++++++----------------- 4 files changed, 95 insertions(+), 58 deletions(-) create mode 100644 merchant-db.png (limited to 'taler-merchant-manual.rst') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 5b0f9355..517faeef 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -1924,9 +1924,6 @@ Giving Customer Tips // Total amount requested for this pickup_id. requested_amount: Amount; - // Total amount processed by the exchange for this pickup. - exchange_amount: Amount; - } @@ -1976,6 +1973,8 @@ Giving Customer Tips The tip identifier is unknown. :status 409 Conflict: Some of the denomination key hashes of the request do not match those currently available from the exchange (hence there is a conflict between what the wallet requests and what the merchant believes the exchange can provide). + :status 410 Gone: + The tip has expired. .. ts:def:: TipPickupRequest diff --git a/merchant-db.png b/merchant-db.png new file mode 100644 index 00000000..cd5f7bd6 Binary files /dev/null and b/merchant-db.png differ diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 2e29dbe3..2e84ab54 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -776,7 +776,7 @@ 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: +The database scheme used by the exchange looks as follows: .. image:: exchange-db.png diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index ca952d29..245e29b9 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -112,60 +112,6 @@ 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 @@ -329,6 +275,8 @@ commands: libtool \ libltdl-dev \ libunistring-dev \ + libsodium-dev \ + libargon2-dev \ libcurl4-gnutls-dev \ libgcrypt20-dev \ libjansson-dev \ @@ -353,6 +301,8 @@ For more recent versions of Debian, you should instead run: libtool \ libltdl-dev \ libunistring-dev \ + libsodium-dev \ + libargon2-dev \ libcurl4-gnutls-dev \ libgcrypt20-dev \ libjansson-dev \ @@ -1172,3 +1122,91 @@ options: .. [2] Supporting SEPA is still work in progress; the backend will accept this configuration, but the exchange will not work with SEPA today. + + + +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. + +.. _Database-Scheme: + +Database Scheme +--------------- + +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, +taler-merchant-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 merchant looks as follows: + +.. image:: merchant-db.png + + + +Legacy +====== + +This chapter contains some legacy documentation we need to update +before it can be considered even reasonably accurate. + +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. -- cgit v1.2.3 From 5d3aef5d035c1a78c930b44d19485396d190e09e Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 23 Jun 2020 23:12:59 +0200 Subject: fix RST warnings --- anastasis.rst | 29 ++++++++++++++--------------- core/api-common.rst | 8 ++++++++ core/api-exchange.rst | 3 ++- core/api-merchant.rst | 37 ++++++++++++++++++------------------- core/api-sync.rst | 4 +++- developers-manual.rst | 31 ++++++++++++++++++------------- taler-auditor-manual.rst | 22 +++++++++++----------- taler-merchant-manual.rst | 6 +----- taler-nfc-guide.rst | 13 ++++++------- 9 files changed, 81 insertions(+), 72 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/anastasis.rst b/anastasis.rst index c27b66df..d0012c7a 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -255,16 +255,16 @@ individual **key share**, we use different salts ("erd" and "eks" respectively). (iv_i, key_i) = HKDF(key_id, nonce_i, "eks", [optional data], keysize + ivsize) (encrypted_key_share_i, aes_gcm_tag_i) = AES256_GCM(key_share_i, key_i, iv_i) -**encrypted_recovery_document**: The encrypted **recovery document** which contains the escrow methods, policies +**encrypted_recovery_document**: The encrypted **recovery document** which contains the escrow methods, policies and the encrypted **core secret**. -**nonce0**: Nonce which is used to generate *key0* and *iv0* which are used for the encryption of the *recovery document*. +**nonce0**: Nonce which is used to generate *key0* and *iv0* which are used for the encryption of the *recovery document*. Nonce must contain the string "ERD". **optional data**: Key material that optionally is contributed from the authentication method to further obfuscate the key share from the escrow provider. -**encrypted_key_share_i**: The encrypted **key_share** which the escrow provider must release upon successful authentication. -Here, **i** must be a positive number used to iterate over the various **key shares** used for the various **escrow methods** +**encrypted_key_share_i**: The encrypted **key_share** which the escrow provider must release upon successful authentication. +Here, **i** must be a positive number used to iterate over the various **key shares** used for the various **escrow methods** at the various providers. **nonce_i**: Nonce which is used to generate *key_i* and *iv_i* which are used for the encryption of the *key share*. **i** must be @@ -356,7 +356,7 @@ Obtain salt **Response:** Returns a `SaltResponse`_. - + .. _SaltResponse: .. ts:def:: SaltResponse @@ -509,7 +509,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. Upload a new version of the customer's encrypted recovery document. While the document's structure is described in JSON below, the upload should just be the bytestream of the raw data (i.e. 32 bytes nonce followed - by 16 bytes tag followed by the encrypted document). + by 16 bytes tag followed by the encrypted document). If request has been seen before, the server should do nothing, and otherwise store the new version. The body must begin with a nonce, an AES-GCM tag and continue with the ciphertext. The format is the same as specified for the response of the GET method. The @@ -644,8 +644,7 @@ In the following, UUID is always defined and used according to `RFC 4122`_. } -.. _manage-truth: - +.. _Truth: Managing truth ^^^^^^^^^^^^^^ @@ -692,7 +691,7 @@ charge per truth operation using GNU Taler. // Contains the information of an interface `EncryptedKeyShare`, but simply // as one binary block (in Crockford Base32 encoding for JSON). key_share_data: []; //bytearray - + // Key share method, i.e. "security question", "SMS", "e-mail", ... method: string; @@ -720,7 +719,7 @@ charge per truth operation using GNU Taler. .. http:get:: /truth/$UUID[?response=$RESPONSE] Get the stored encrypted key share. If $RESPONSE is specified by the client, the server checks - if $RESPONSE matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth). + if $RESPONSE matches the expected response specified before within the TruthUploadRequest_ (see encrypted_truth). Also, the user has to provide the correct *truth_encryption_key* with every get request (see below). When $RESPONSE is correct, the server responses with the encrypted key share. The encrypted key share is returned simply as a byte array and not in JSON format. @@ -768,7 +767,7 @@ charge per truth operation using GNU Taler. // // HKDF for the key generation must include the // string "eks" as salt. - // Depending on the method, + // Depending on the method, // the HKDF may additionally include // bits from the response (i.e. some hash over the // answer to the security question) @@ -811,10 +810,10 @@ FIXME: details! Video identification (vid) ^^^^^^^^^^^^^^^^^^^^^^^^^^ -Requires the user to identify via video-call. The user is expected to delete all metadata revealing -information about him/her from the images before uploading them. Since the respective images must -be passed on to the video identification service in the event of password recovery, it must be -ensured that no further information about the user can be derived from them. +Requires the user to identify via video-call. The user is expected to delete all metadata revealing +information about him/her from the images before uploading them. Since the respective images must +be passed on to the video identification service in the event of password recovery, it must be +ensured that no further information about the user can be derived from them. FIXME: details! diff --git a/core/api-common.rst b/core/api-common.rst index 93d6d09e..272dfd6c 100644 --- a/core/api-common.rst +++ b/core/api-common.rst @@ -267,6 +267,14 @@ Integers // JavaScript numbers restricted to integers type Integer = number; +Objects +^^^^^^^ + +.. ts:def:: Object + + // JavaScript objects, no further restrictions + type Object = object; + Keys ^^^^ diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 979eca86..9b18a18d 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -1330,11 +1330,12 @@ typically also view the balance.) } +.. _exchange_refund: + ------- Refunds ------- -.. _refund: .. http:POST:: /coins/$COIN_PUB/refund Undo deposit of the given coin, restoring its value. diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 1c99a79e..5c50709a 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -325,8 +325,7 @@ Dynamic Merchant Instances **Response** :status 204 No content: - The backend has successfully removed the instance. The response is a - `PostInstanceRemoveResponse`. + The backend has successfully removed the instance. The body is empty. :status 404 Not found: The instance is unknown to the backend. :status 409 Conflict: @@ -991,7 +990,7 @@ Payment processing The backend will return an `abort response `, which includes verbatim the error codes received from the exchange's - :ref:`refund <_refund>` API. The frontend should pass the replies verbatim to + :ref:`refund ` API. The frontend should pass the replies verbatim to the browser/wallet. .. ts:def:: AbortRequest @@ -1038,12 +1037,12 @@ Payment processing // can generate a substantially shorter response. interface RefundResult { // HTTP status of the request to the exchange. - exchange_http_status: integer; + exchange_http_status: Integer; // The full reply from the exchange. Note only actually - // a if the `exchange_status` is 200, otherwise + // a if the \exchange_http_status\ is 200, otherwise // the error message as defined by the refund API. For - // aborts, the `rtransaction_id` is always 0. + // aborts, the \rtransaction_id\ is always 0. exchange_reply: RefundSuccess; } @@ -1278,7 +1277,7 @@ Payment processing exchange_code?: Integer; // If available, HTTP reply from the exchange. - exchange_reply?: json; + exchange_reply?: Object; // Refund transaction ID. rtransaction_id: Integer; @@ -1299,8 +1298,8 @@ Payment processing // to the wallet and thus not included. interface RefundConfirmation { - // HTTP status of the exchange request, 200 required for refund confirmations. - exchange_status: 200; + // HTTP status of the exchange request, 200 (integer) required for refund confirmations. + exchange_status: "200"; // the EdDSA :ref:`signature` (binary-only) with purpose // `TALER_SIGNATURE_EXCHANGE_CONFIRM_REFUND` using a current signing key of the @@ -1342,7 +1341,7 @@ Payment processing The backend refuses to delete the order. -.. _refund: +.. _merchant_refund: -------------- Giving Refunds @@ -1502,7 +1501,7 @@ Tracking Wire Transfers // and should probably return it here as well. interface WireFeeConflictDetails { // Numerical `error code `: - code: TALER_EC_POST_TRANSFERS_JSON_BAD_WIRE_FEE; + code: "TALER_EC_POST_TRANSFERS_JSON_BAD_WIRE_FEE"; // Text describing the issue for humans. hint: string; @@ -1540,7 +1539,7 @@ Tracking Wire Transfers interface TrackTransferConflictDetails { // Numerical `error code ` - code: TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS; + code: "TALER_EC_POST_TRANSFERS_CONFLICTING_REPORTS"; // Text describing the issue for humans. hint: string; @@ -1558,15 +1557,15 @@ Tracking Wire Transfers // hardly needed _here_. Once we add automated reports for // the Taler auditor, we need to generate this data anyway // and should probably return it here as well. - exchange_transfer: TrackTransferResponse?; + exchange_transfer?: TrackTransferResponse; // Public key of the exchange used to sign the response to // our deposit request. - deposit_exchange_pub: EdDSAPublicKey; + deposit_exchange_pub: EddsaPublicKey; // Signature of the exchange signing the (conflicting) response. - // Signs over a `struct TALER_DepositConfirmationPS`. - deposit_exchange_sig: EdDSASignature; + // Signs over a \struct TALER_DepositConfirmationPS\. + deposit_exchange_sig: EddsaSignature; // Hash of the merchant's bank account the wire transfer went to h_wire: HashCode; @@ -1575,10 +1574,10 @@ Tracking Wire Transfers h_contract_terms: HashCode; // At what time the exchange received the deposit. Needed - // to verify the `exchange_sig`. + // to verify the \exchange_sig\. deposit_timestamp: Timestamp; - // At what time the refund possibility expired (needed to verify ``exchange_sig``). + // At what time the refund possibility expired (needed to verify \exchange_sig\). refund_deadline: Timestamp; // Public key of the coin for which we have conflicting information. @@ -1717,7 +1716,7 @@ Giving Customer Tips :status 200 OK: The backend is waiting for the reserve to be established. The merchant must now perform the wire transfer indicated in the `ReserveCreateConfirmation`. - :status 408 Timeout: + :status 408 Request Timeout: The exchange did not respond on time. :status 409 Conflict: The exchange does not support the requested wire method. diff --git a/core/api-sync.rst b/core/api-sync.rst index 2add73ef..67d1e214 100644 --- a/core/api-sync.rst +++ b/core/api-sync.rst @@ -411,4 +411,6 @@ Web Security Considerations To ensure that the Taler Web extension (and others) can access the service despite Web "security", all service endpoints must set the -"Access-Control-Allow-Origin: *". +header:: + + Access-Control-Allow-Origin: * diff --git a/developers-manual.rst b/developers-manual.rst index 8c3a3501..6e0bc309 100644 --- a/developers-manual.rst +++ b/developers-manual.rst @@ -28,7 +28,7 @@ Developer's Manual .. note:: - This manual contains information for developers working on GNU Taler + This manual contains information for developers working on GNU Taler and related components. It is not intended for a general audience. .. contents:: Table of Contents @@ -636,13 +636,13 @@ About Privilege Levels This is the breakdown of privilege levels in Weblate: -* **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) + * **Users**/**Viewers** = Can log in, view Translations (*applies to new users*) -* **Reviewers** = Can contribute Translations to existing *Components* + * **Reviewers** = Can contribute Translations to existing *Components* -* **Managers** = Can create new *Components* of existing *Projects* + * **Managers** = Can create new *Components* of existing *Projects* -* **Superusers** = Can create new *Projects* + * **Superusers** = Can create new *Projects* Upgrading Privileges -------------------- @@ -661,20 +661,25 @@ Reference: https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#compone In Weblate, a *Component* is a subset of a *Project* and each Component contains N translations. A Component is generally associated with a Git repo. -To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add* from the upper-right corner. +To create a Component, log into https://weblate.taler.net/ with your *Manager* or higher credentials and choose **+ Add** from the upper-right corner. What follows is a sort of Wizard. You can find detailed docs at https://docs.weblate.org/. Here are some important notes about connecting your Component to the Taler Git repository: Under *https://weblate.taler.net/create/component/vcs/*: -* **Source code repository** - Generally ``git+ssh://git@git.taler.net/```. Check with ``git remote -v``. -* **Repository branch** - Choose the correct branch to draw from and commit to. -* **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/``` Check with ``git remote -v``. -* **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ```` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string. -* **Merge style** - *Rebase*, in line with GNU Taler development procedures + * **Source code repository** - Generally ``git+ssh://git@git.taler.net/```. Check with ``git remote -v``. -* **Translation license** - *GNU General Public License v3.0 or Later* -* **Adding new translation** - Decide how to handle adding new translations + * **Repository branch** - Choose the correct branch to draw from and commit to. + + * **Repository push URL** - This is generally ``git+ssh://git@git.taler.net/``` Check with ``git remote -v``. + + * **Repository browser** - This is the www URL of the Git repo's file browser. Example ``https://git.taler.net/.git/tree/{{filename}}?h={{branch}}#n{{line}}`` where ```` gets replaced but ``{{filename}}`` and other items in braces are actual variables in the string. + + * **Merge style** - *Rebase*, in line with GNU Taler development procedures + + * **Translation license** - *GNU General Public License v3.0 or Later* + + * **Adding new translation** - Decide how to handle adding new translations How to Create a Translation --------------------------- diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index f5cca273..97ba2a5d 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -263,7 +263,7 @@ Taler components. See for example the exchange manual for details on the configuration and the ``taler-config`` configuration tool. This section discusses configuration options related to the auditor. -.. _Keys: +.. _AuditorKeys: Keys ---- @@ -275,7 +275,7 @@ The following values are to be configured in the section [auditor]: - AUDITOR_PRIV_FILE: Path to the auditor’s private key file. -.. _Serving: +.. _AuditorServing: Serving ------- @@ -296,7 +296,7 @@ The following values are to be configured in the section [auditor]: for the unixpath (i.e. 660 = rw-rw—-). -.. _Bank-account: +.. _AuditorBank-account: Bank account ------------ @@ -305,7 +305,7 @@ Bank accounts for the auditor are configured in exactly the same way as bank accounts for the exchange. See the exchange documentation for details. -.. _Database: +.. _AuditorDatabaseConfiguration: Database -------- @@ -338,7 +338,7 @@ tables. After running this tool, the rights to CREATE or DROP tables are no longer required and should be removed. -.. _Deployment: +.. _AuditorDeployment: Deployment ========== @@ -356,7 +356,7 @@ Web page offering the respective pairing. FIXME: explain how that Web page works! -.. _Exchange: +.. _AuditorExchange: Exchange -------- @@ -375,7 +375,7 @@ master public key. taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL -.. _Denominations: +.. _AuditorDenominations: Denominations ------------- @@ -417,7 +417,7 @@ response will contain an entry in the ``auditors`` array mentioning the auditor’s URL. -.. _Database: +.. _AuditorDatabaseInitialization: Database -------- @@ -464,7 +464,7 @@ Audit Performing an audit is done by invoking the ``taler-auditor`` and ``taler-wire-auditor`` tools respectively. Both tools generate JSON -files, which can then be combined using the ``contrib/render.py'' +files, which can then be combined using the ``contrib/render.py`` script into the TeX report. :: @@ -487,7 +487,7 @@ anymore), this is not recommended in a production setup. -.. _Database-upgrades: +.. _AuditorDatabaseUpgrades: Database upgrades ----------------- @@ -510,7 +510,7 @@ historic transactions. Hence this should not be done in a production system. -.. _Revocations: +.. _AuditorRevocations: Revocations ----------- diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 245e29b9..dfa6492e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1119,10 +1119,6 @@ options: .. [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. - Diagnostics @@ -1133,7 +1129,7 @@ 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. -.. _Database-Scheme: +.. _MerchantDatabaseScheme: Database Scheme --------------- diff --git a/taler-nfc-guide.rst b/taler-nfc-guide.rst index 20239352..88fa13d5 100644 --- a/taler-nfc-guide.rst +++ b/taler-nfc-guide.rst @@ -45,7 +45,7 @@ using `curl `_ to make HTTP(S) requests. can be opened, and give a warning if it is detected that the devices does not have Internet connectivity. - The following :http:post:`/order` request to the merchant backend creates a + The following :http:post:`/private/orders` request to the merchant backend creates a simple order: .. code-block:: sh @@ -63,20 +63,20 @@ using `curl `_ to make HTTP(S) requests. } EOF ) - $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/order + $ curl -XPOST -H"$auth_header" -d "$order_req" "$backend_base_url"/private/orders { "order_id": "2019.255-02YDHMXCBQP6J" } 2. The merchant checks the payment status of the order using - :http:get:`/check-payment`: + :http:get:`/private/orders/$ORDER_ID`: .. code-block:: sh $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' $ curl -XGET -H"$auth_header" \ - "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J" + "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" # Response: { "taler_pay_uri": "taler://pay/backend.demo.taler.net/-/-/2019.255-02YDHMXCBQP6J", @@ -121,7 +121,7 @@ using `curl `_ to make HTTP(S) requests. $ backend_base_url=https://backend.demo.taler.net/ $ auth_header='Authorization: ApiKey sandbox' $ curl -XGET -H"$auth_header" \ - "$backend_base_url/check-payment?order_id=2019.255-02YDHMXCBQP6J" + "$backend_base_url/private/orders/2019.255-02YDHMXCBQP6J" # Response: { "paid": true, @@ -135,7 +135,7 @@ using `curl `_ to make HTTP(S) requests. before responding with the fulfillment page. For in-store payments, the merchant must periodically check the payment status. - Instead of polling in a busy loop, the ``long_poll_ms`` parameter of :http:get:`/check-payment` + Instead of polling in a busy loop, the ``timeout_ms`` parameter of :http:get:`/private/orders/$ORDER_ID` should be used. @@ -281,4 +281,3 @@ The request tunneling request/response JSON messages have the following schema: // May contain error details if 'status==0' body?: object; } - -- cgit v1.2.3 From 4c8e4a88a75db50b58b4eaf20dee04e99c4bd86a Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 24 Jun 2020 19:41:54 +0200 Subject: remove outdated merchant documentation, remark where more is needed --- conf.py | 6 +- fdl-1.3.rst | 26 +-- taler-merchant-api-tutorial.rst | 5 +- taler-merchant-manual.rst | 439 ++++++++++++++-------------------------- 4 files changed, 173 insertions(+), 303 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/conf.py b/conf.py index c7c1666b..64ce8c47 100644 --- a/conf.py +++ b/conf.py @@ -77,16 +77,16 @@ master_doc = 'index' # General information about the project. project = u'GNU Taler' -copyright = u'2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)' +copyright = u'2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+)' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '0.6pre1' +version = '0.8pre0' # The full version, including alpha/beta/rc tags. -release = '0.6.0pre1' +release = '0.8.0pre0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/fdl-1.3.rst b/fdl-1.3.rst index 6dec4945..49bf2d3e 100644 --- a/fdl-1.3.rst +++ b/fdl-1.3.rst @@ -12,7 +12,7 @@ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. 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 @@ -36,7 +36,7 @@ published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. 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 @@ -124,7 +124,7 @@ these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING -^^^^^^^^^^^^^^^^^^^ +------------------- You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the @@ -140,7 +140,7 @@ You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. 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 @@ -178,7 +178,7 @@ Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. 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 @@ -264,7 +264,7 @@ give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified @@ -289,7 +289,7 @@ sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”. 6. 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 @@ -303,7 +303,7 @@ License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. 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 @@ -322,7 +322,7 @@ equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION -^^^^^^^^^^^^^^ +-------------- Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing @@ -342,7 +342,7 @@ If a section in the Document is Entitled “Acknowledgements”, Title (section 1) will typically require changing the actual title. 9. TERMINATION -^^^^^^^^^^^^^^ +-------------- You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, @@ -370,7 +370,7 @@ reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. 10. 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 @@ -390,7 +390,7 @@ used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document. 11. RELICENSING -^^^^^^^^^^^^^^^ +--------------- “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides @@ -419,7 +419,7 @@ 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 diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index f97f96c1..6442e7c2 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -66,7 +66,7 @@ components: The following image illustrates the various interactions of these key components: -|image0| +.. image:: arch-api.png The backend provides the cryptographic protocol support, stores Taler-specific financial information and communicates with the GNU Taler @@ -736,6 +736,3 @@ locations 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. - - -.. |image0| image:: arch-api.png diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index dfa6492e..8fcb487e 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -50,8 +50,8 @@ operating a basic backend. Architecture overview --------------------- -:keywords: crypto-currency -:keywords: KUDOS +.. index:: crypto-currency +.. index:: 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 @@ -60,33 +60,31 @@ 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. +.. index:: frontend +.. index:: back office +.. index:: backend +.. index:: DBMS +.. index:: Postgres + The Taler software stack for a merchant consists of four main components: -- frontend - A frontend which interacts with the customer’s browser. The 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 +- 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 +- 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. +- 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. @@ -94,11 +92,10 @@ components: The following image illustrates the various interactions of these key components: -:: +.. image:: arch-api.png - Missing diagram image +.. index:: RESTful -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 @@ -128,7 +125,7 @@ system. .. _Installation-of-dependencies: Installation of dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following packages need to be installed before we can compile the backend: @@ -173,9 +170,9 @@ the libgnunetutil and GNU Taler exchange dependencies. .. _Installing-libgnunetutil: Installing libgnunetutil -~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^ -:keywords: GNUnet +.. index:: GNUnet Before you install libgnunetutil, you must download and install the dependencies mentioned in the previous section, otherwise the build may @@ -200,9 +197,9 @@ which requires you to run the last step as ``root``. .. _Installing-the-GNU-Taler-exchange: Installing the GNU Taler exchange -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:keywords: exchange +.. index:: exchange After installing GNUnet, you can download and install the exchange as follows: @@ -227,9 +224,9 @@ installed GNUnet to ``/usr/local`` in the previous step. .. _Installing-the-GNU-Taler-merchant-backend: Installing the GNU Taler merchant backend -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:keywords: backend +.. index:: backend The following steps assume all dependencies are installed. @@ -257,8 +254,8 @@ GNUnet to ``/usr/local`` in the previous steps. Installing Taler on Debian GNU/Linux ------------------------------------ -:keywords: Wheezy -:keywords: Debian +.. index:: Wheezy +.. index:: Debian Debian wheezy is too old and lacks most of the packages required. @@ -318,8 +315,8 @@ if you used the Debian wheezy instructions above, you need to pass How to configure the merchant’s backend ======================================= -:keywords: taler-config -:keywords: taler.conf +.. index:: taler-config +.. index:: taler.conf The installation already provides reasonable defaults for most of the configuration options. However, some must be provided, in particular the @@ -336,22 +333,33 @@ see `Using taler-config <#Using-taler_002dconfig>`__. Backend options --------------- +.. index:: DBMS +.. index:: Postgres +.. index:: UNIX domain socket +.. index:: TCP +.. index:: port +.. index:: currency +.. index:: KUDOS +.. index:: exchange +.. index:: instance +.. index:: wire format + 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: +^^^^^^^^^^^^^^^ -:keywords: UNIX domain socket -:keywords: TCP +The following option sets the transport layer address used by the +merchant backend: :: [MERCHANT]/SERVE = TCP | UNIX - If given, +If given, - ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT`` @@ -360,13 +368,12 @@ Service address 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. +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. -:keywords: port - To run the Taler backend on TCP port 8888, use: +To run the Taler backend on TCP port 8888, use: :: @@ -374,70 +381,68 @@ Service address $ 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 +^^^^^^^^ + +Which currency the Web shop deals in, i.e. “EUR” or “USD”, is +specified using the option -:keywords: currency -:keywords: 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/: +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 -:keywords: DBMS +^^^^^^^^ - In principle is possible for the backend to support different DBMSs. - The option +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. +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. +In addition to selecting the DBMS software, the backend requires +DBMS-specific options to access the database. - For postgres, you need to provide: +For postgres, you need to provide: :: [merchantdb-postgres]/config -:keywords: 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 +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: +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 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: +To configure the Taler backend to use this database, run: :: @@ -445,11 +450,11 @@ Database -V postgres:///$DBNAME Exchange -:keywords: 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: +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: @@ -468,92 +473,28 @@ Exchange $ 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. +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 -:keywords: 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: +Auditor +^^^^^^^ - :: +FIXME: document here how to add an auditor to the list of +trusted auditors! - $ 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 -:keywords: 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' - - - 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. - - Note that additional instances can be specified using different - tokens in the section name instead of ``default``. .. _Sample-backend-configuration: Sample backend configuration ---------------------------- -:keywords: configuration +.. index:: configuration The following is an example for a complete backend configuration: @@ -570,24 +511,14 @@ The following is an example for a complete backend configuration: [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 - HONOR_default = YES - ACTIVE_default = YES - TALER_BANK_AUTH_METHOD = basic - USERNAME = my_user - PASSWORD = 1234pass - [merchant-exchange-trusted] + # FIXME: check this is up-to-date! EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 CURRENCY = KUDOS + [FIXME: add example for AUDITOR!] + Given the above configuration, the backend will use a database named ``donations`` within Postgres. @@ -604,8 +535,8 @@ them. Launching the backend --------------------- -:keywords: backend -:keywords: taler-merchant-httpd +.. index:: backend +.. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the merchant backend using: @@ -632,6 +563,37 @@ 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. +.. _Instances: + +Instances +========= + +The backend allows the user to run multiple instances of shops with +distinct business entities against a single backend. Each instance +uses its own bank accounts and key for signing contracts. It is +mandatory to configure at least the "default" instance. + +Instances can be configured by POSTing the necessary requests to the +backend (possibly via a Web interface -- once we implement that). + +FIXME: more details on how to setup instances here! + + +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. + +FIXME: more details on how to setup accounts here! + + .. _Testing: Testing @@ -683,7 +645,7 @@ 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. +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 @@ -745,7 +707,7 @@ Advanced topics Configuration format -------------------- -:keywords: configuration +.. index:: configuration In Taler realm, any component obeys to the same pattern to get configuration values. According to this pattern, once the component has @@ -819,7 +781,7 @@ configuration file used in our demos. See under ``deployment/config``. Using taler-config ------------------ -:keywords: taler-config +.. index:: taler-config The tool ``taler-config`` can be used to extract or manipulate configuration values; however, the configuration use the well-known INI @@ -859,42 +821,22 @@ compare: :: - $ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE - $ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE + $ taler-config -s PATHS \ + -o TALER_DATA_HOME + $ taler-config -f -s PATHS \ + -o TALER_DATA_HOME 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 ------------------------ - -:keywords: merchant key -:keywords: 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) - .. _Tipping-visitors: Tipping visitors ---------------- -:keywords: tipping +.. index:: 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 @@ -904,118 +846,48 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:keywords: gnunet-ecc -:keywords: 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. +FIXME: write current explanation! .. _Fund-the-reserve: Fund the reserve -~~~~~~~~~~~~~~~~ - -:keywords: reserve -:keywords: close +^^^^^^^^^^^^^^^^ -To fund the reserve, you must first extract the public key from -“tip.priv”: +.. index:: reserve +.. index:: close -:: - - $ 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: +In our example, the output for the wire transfer subject 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. +using the public key as the wire transfer subject. Make your wire transfer and (optionally) check at -“https://exchange:443/reserve/status/reserve_pub=QPE24X...” whether your -transfer has arrived at the exchange. +“https://exchange/reserves/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. +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 setup another reserve +every other week to ensure one is always ready. .. _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: +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 “/private/reserves/$RID/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 @@ -1040,18 +912,19 @@ 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 wallet will POST a JSON object to the shop’s “/tips/$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: +.. _Benchmarking: -Generate payments ------------------ +Benchmarking +------------ + +.. index:: testing database -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 -- cgit v1.2.3 From cd10263cc144e7a3987f70b7b02d7c980a87b058 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 24 Jun 2020 20:46:02 +0200 Subject: specify current merchant configuration --- taler-merchant-manual.rst | 308 +++++++++++++++++++++++++++------------------- 1 file changed, 182 insertions(+), 126 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 8fcb487e..f8515c0a 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -312,6 +312,7 @@ 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 ======================================= @@ -386,7 +387,6 @@ Currency Which currency the Web shop deals in, i.e. “EUR” or “USD”, is specified using the option - :: [TALER]/CURRENCY @@ -449,45 +449,92 @@ To configure the Taler backend to use this database, run: $ taler-config -s MERCHANTDB-postgres -o CONFIG \ -V postgres:///$DBNAME +.. index: MASTER_KEY + 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: +To add an exchange to the list of trusted payment service providers, you +create a section with a name that starts with “MERCHANT-EXCHANGE-”. In that +section, the following options need to be configured: - - The “url” option specifies the exchange’s base URL. For example, - to use the Taler demonstrator use: + - The “EXCHANGE_BASE_URL” option specifies the exchange’s base URL. For example, + to use the Taler demonstrator, specify: :: - $ taler-config -s EXCHANGE-demo -o URL \ + $ taler-config -s MERCHANT-EXCHANGE-demo \ + -o EXCHANGE_BASE_URL \ -V https://exchange.demo.taler.net/ - - master key - The “master_key” option specifies the exchange’s master public 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 \ + $ taler-config -s MERCHANT-EXCHANGE-demo \ + -o MASTER_KEY \ -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 -Note that multiple exchanges can be added to the system by using -different tokens in place of ``demo`` in the example above. Note -that all of the exchanges must use the same currency. If you need -to support multiple currencies, you need to configure a backend -per currency. + - The “CURRENCY” option specifies the exchange’s currency. + For the Taler demonstrator, use: + + :: + + $ taler-config -s MERCHANT-EXCHANGE-demo \ + -o CURRENCY \ + -V KUDOS + +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 the currency does not match the main +currency from the "TALER" section, the exchange is ignored. If you need to +support multiple currencies, you need to configure a backend per currency. Auditor ^^^^^^^ -FIXME: document here how to add an auditor to the list of -trusted auditors! +To add an auditor to the list of trusted auditors (which implies +that all exchanges audited by this auditor will be trusted!) +you create a section with a name that starts with “MERCHANT-AUDITOR-”. In +that section, the following options need to be configured: + + - The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example, + to use the Taler demonstrator's auditor, specify: + + :: + + $ taler-config -s MERCHANT-AUDITOR-demo \ + -o AUDITOR_BASE_URL \ + -V https://exchange.demo.taler.net/ + + - The “AUDITOR_KEY” option specifies the auditor's public key + in base32 encoding. For the Taler demonstrator, use: + + :: + + $ taler-config -s MERCHANT-AUDITOR-demo \ + -o AUDITOR_KEY \ + -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 + + - The “CURRENCY” option specifies the auditor’s currency. + For the Taler demonstrator, use: + + :: + + $ taler-config -s MERCHANT-AUDITOR-demo \ + -o CURRENCY \ + -V KUDOS +Note that multiple auditors can be added to the system by using different +tokens in place of ``demo`` in the example above. Note that all of the +auditors must use the same currency: If the currency does not match the main +currency from the "TALER" section, the auditor is ignored. If you need to +support multiple currencies, you need to configure a backend per currency. + .. _Sample-backend-configuration: @@ -511,13 +558,19 @@ The following is an example for a complete backend configuration: [MERCHANTDB-postgres] CONFIG = postgres:///donations - [merchant-exchange-trusted] - # FIXME: check this is up-to-date! + [merchant-exchange-NAME] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 + # If currency does not match [TALER] section, the exchange + # will be ignored! CURRENCY = KUDOS - [FIXME: add example for AUDITOR!] + [merchant-auditor-NAME] + AUDITOR_BASE_URL = https://auditor.demo.taler.net/ + AUDITOR_KEY = DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11 + # If currency does not match [TALER] section, the auditor + # will be ignored! + CURRENCY = KUDOS Given the above configuration, the backend will use a database named ``donations`` within Postgres. @@ -594,112 +647,6 @@ a ``payto://``-URL. FIXME: more details on how to setup accounts here! -.. _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 /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 =============== @@ -1026,6 +973,115 @@ Legacy 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 /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 + + + Installing Taler using Docker ----------------------------- -- cgit v1.2.3 From b1d2864aa3c80a223a782352aa5fb64f4d613424 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 25 Jun 2020 22:54:04 +0200 Subject: improve merchant manual --- taler-merchant-manual.rst | 158 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 135 insertions(+), 23 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index f8515c0a..d6f07efb 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -152,11 +152,13 @@ backend: - libargon2 >= 20171227 (GNUnet 0.13 needs it to build, not actively used by GNU Taler) +- libsqlite3 >= 3.0 (GNUnet 0.13 needs it to build, not actively used by GNU Taler) + - libjansson >= 2.7 - Postgres >= 9.6, including libpq -- libgnunetutil (from Git) +- GNUnet (from Git) - GNU Taler exchange (from Git) @@ -169,20 +171,20 @@ the libgnunetutil and GNU Taler exchange dependencies. .. _Installing-libgnunetutil: -Installing libgnunetutil -^^^^^^^^^^^^^^^^^^^^^^^^ +Installing GNUnet +^^^^^^^^^^^^^^^^^ .. index:: 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. +Before you install GNUnet, you must download and install the dependencies +mentioned in the previous section, otherwise the build may succeed, but could +fail to export some of the tooling required by GNU Taler. -To download and install libgnunetutil, proceed as follows: +To download and install GNUnet, proceed as follows: :: - $ git clone https://gnunet.org/git/gnunet/ + $ git clone https://git.gnunet.org/gnunet/ $ cd gnunet/ $ ./bootstrap $ ./configure [--prefix=GNUNETPFX] @@ -194,6 +196,11 @@ To download and install libgnunetutil, proceed as follows: If you did not specify a prefix, GNUnet will install to ``/usr/local``, which requires you to run the last step as ``root``. +There is no need to actually run a GNUnet peer to use the Taler merchant +backend -- all the merchant needs from GNUnet is a number of headers and +libraries! + + .. _Installing-the-GNU-Taler-exchange: Installing the GNU Taler exchange @@ -206,7 +213,7 @@ follows: :: - $ git clone git://taler.net/exchange + $ git clone https://git.taler.net/exchange/ $ cd exchange $ ./bootstrap $ ./configure [--prefix=EXCHANGEPFX] \ @@ -216,10 +223,15 @@ follows: $ 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. +If you did not specify a prefix, the exchange will install to ``/usr/local``, +which requires you to run the last step as ``root``. You have to specify +``--with-gnunet=/usr/local`` if you installed GNUnet to ``/usr/local`` in the +previous step. + +There is no need to actually run a Taler exchange to use the Taler merchant +backend -- all the merchant needs from the Taler exchange is a few headers and +libraries! + .. _Installing-the-GNU-Taler-merchant-backend: @@ -234,7 +246,7 @@ Use the following commands to download and install the merchant backend: :: - $ git clone git://taler.net/merchant + $ git clone https://git.taler.net/merchant/ $ cd merchant $ ./bootstrap $ ./configure [--prefix=PFX] \ @@ -243,12 +255,24 @@ Use the following commands to download and install the merchant backend: $ # Each dependency can be fetched from non standard locations via $ # the '--with-' option. See './configure --help'. $ make - $ make install + # 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-exchange=/usr/local`` and/or +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. +Depending on the prefixes you specified for the installation and the +distribution you are using, you may have to edit ``/etc/ld.so.conf``, adding +lines for ``GNUNETPFX/lib/`` and ``EXCHANGEPFX/lib/`` and ``PFX/lib/`` +(replace the prefixes with the actual paths you used). Afterwards, you should +run ``ldconfig``. Without this step, it is possible that the linker may not +find the installed libraries and launching the Taler merchant backend would +then fail. + + .. _Installing-Taler-on-Debian-GNU_002fLinux: Installing Taler on Debian GNU/Linux @@ -381,6 +405,8 @@ 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 ^^^^^^^^ @@ -399,6 +425,7 @@ https://exchange.demo.taler.net/: $ taler-config -s TALER -o CURRENCY -V KUDOS + Database ^^^^^^^^ @@ -429,7 +456,7 @@ run :: - $ sudu -u postgres createuser -d $USER + $ sudo -u postgres createuser -d $USER as the Postgres database administrator (usually ``postgres``) to grant ``$USER`` the ability to create new databases. Next, you should @@ -449,6 +476,21 @@ To configure the Taler backend to use this database, run: $ taler-config -s MERCHANTDB-postgres -o CONFIG \ -V postgres:///$DBNAME +Now you should create the tables and indices. To do this, run as ``$USER``: + + :: + + $ taler-merchant-dbinit + + +You can improve your security posture if you now REVOKE the rights to CREATE, +DROP or ALTER tables from ``$USER``. However, if you do so, please be aware +that you may have to temporarily GRANT those rights again when you update the +merchant backend. For details on how to REVOKE or GRANT these rights, consult +the Postgres documentation. + + + .. index: MASTER_KEY Exchange @@ -592,15 +634,18 @@ Launching the backend .. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the -merchant backend using: +merchant backend as ``$USER`` 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 +To ensure the process runs always in the background and also after rebooting, +you should use systemd, cron or some other init system of your operating +system to launch the process. Consult the documentation of your operating +system for how to start and stop daemons. + +If everything worked as expected, the command :: @@ -614,7 +659,8 @@ should return the message 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. +and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__. + .. _Instances: @@ -632,6 +678,8 @@ backend (possibly via a Web interface -- once we implement that). FIXME: more details on how to setup instances here! + + Accounts -------- @@ -647,10 +695,74 @@ a ``payto://``-URL. FIXME: more details on how to setup accounts here! +Upgrade procedure +================= + +This is the general upgrade procedure. Please see the release notes +for your specific version to check if a particular release has special +upgrade requirements. + +Please note that upgrades are ONLY supported for released version of the +merchant. Attempting to upgrade from or to a version in Git is not supported +and may result in subtle data loss. + +To safely upgrade the merchant, you should first stop the existing +taler-merchant-httpd process, backup your merchant database (see Postgres +manual), and then install the latest version of the code. + +If you REVOKED database permissions, ensure that the rights to CREATE, +DROP, and ALTER tables are GRANTed to ``$USER`` again. Then, run: + + :: + + $ taler-merchant-dbinit + +to upgrade the database to the latest schema. After that, you may again +REVOKE the database permissions. Finally, restart the HTTP service, either via +your systemd or init system, or directly using: + + :: + + $ taler-merchant-httpd + + Advanced topics =============== +.. _Secure-setup: + +Secure setup +------------ + +.. index:: security +.. index:: TLS + +For additional security, you may want to have the backend bind to a UNIX +domain socket and use an HTTP reverse proxy for TLS termination: + + :: + + $ taler-config -s MERCHANT -o SERVE -V UNIX + $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock + +Assuming your domain name is /example.com/ and you have TLS configured, +a possible reverse proxy directive for Nginx would be: + + :: + + proxy_pass http://unix:/some/path/here.sock; + proxy_redirect off; + proxy_set_header Host $host; + 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 configuration. + + + Configuration format -------------------- @@ -726,7 +838,7 @@ configuration file used in our demos. See under ``deployment/config``. .. _Using-taler_002dconfig: Using taler-config ------------------- +^^^^^^^^^^^^^^^^^^ .. index:: taler-config -- cgit v1.2.3 From e25c00421f555d8fe371b135451f06dedd0e11b5 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 25 Jun 2020 23:10:17 +0200 Subject: improving merchant backend documentation --- taler-merchant-manual.rst | 310 ++++++++++++++++++++++++++-------------------- 1 file changed, 176 insertions(+), 134 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index d6f07efb..9f44960a 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -673,11 +673,36 @@ uses its own bank accounts and key for signing contracts. It is mandatory to configure at least the "default" instance. Instances can be configured by POSTing the necessary requests to the -backend (possibly via a Web interface -- once we implement that). +backend. To create a first instance, create a file ``instance.json`` +with an `InstanceConfigurationMessage`: -FIXME: more details on how to setup instances here! +:: + + { + payto_uris : [ "payto://iban/IBANNUMBERHERE" ], + id : "default", + name: "example.com", + address: { country : "zz" }, + jurisdiction: { country : "zz" }, + default_max_wire_fee: "KUDOS:1", + default_wire_fee_amortization: 100, + default_max_deposit_fee: "KUDOS:1", + default_wire_transfer_delay: { d_ms : 1209600000 }, + default_pay_delay: { d_ms : 1209600000 }, + } + +You can then create the instance using: +:: + $ wget --post-file=instance.json http://localhost:8888/private/instances +The base URL for the instance will then be +``http://localhost:8888/instances/default``. You can create additional +instances by changing the "id" value to identifies other than "default". + +Endpoints to modify (reconfigure), permanently disable (while keeping the data) +or purge (deleting all associated data) instances exist as well and are documented +in the `Merchant Backend API documentation <#merchant-api>`__. Accounts @@ -689,10 +714,50 @@ 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. +The bank account information is provided in the form of a ``payto://``-URL. + +See RFC XXXX for the format of ``payto://``-URLs. + + +.. _Inventory: + +Inventory management +==================== + + + + + +.. _Secure-setup: + +Secure setup +============ + +.. index:: security +.. index:: TLS + +For additional security, you may want to have the backend bind to a UNIX +domain socket and use an HTTP reverse proxy for TLS termination: + + :: + + $ taler-config -s MERCHANT -o SERVE -V UNIX + $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock + +Assuming your domain name is /example.com/ and you have TLS configured, +a possible reverse proxy directive for Nginx would be: + + :: + + proxy_pass http://unix:/some/path/here.sock; + proxy_redirect off; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Host "example.com"; + proxy_set_header X-Forwarded-Proto "https"; -FIXME: more details on how to setup accounts here! +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 configuration. Upgrade procedure @@ -726,40 +791,116 @@ your systemd or init system, or directly using: $ taler-merchant-httpd +.. _Tipping-visitors: -Advanced topics -=============== +Tipping visitors +================ -.. _Secure-setup: +.. index:: tipping -Secure setup ------------- +NOTE: This section is dated and should be reviewed! -.. index:: security -.. index:: TLS +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. -For additional security, you may want to have the backend bind to a UNIX -domain socket and use an HTTP reverse proxy for TLS termination: +There are four basic steps that must happen to tip a visitor. - :: +FIXME: write current explanation! - $ taler-config -s MERCHANT -o SERVE -V UNIX - $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock +.. _Fund-the-reserve: -Assuming your domain name is /example.com/ and you have TLS configured, -a possible reverse proxy directive for Nginx would be: +Fund the reserve +---------------- - :: +.. index:: reserve +.. index:: close - proxy_pass http://unix:/some/path/here.sock; - proxy_redirect off; - proxy_set_header Host $host; - proxy_set_header X-Forwarded-Host "example.com"; - proxy_set_header X-Forwarded-Proto "https"; +In our example, the output for the wire transfer subject is: -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 configuration. +:: + + QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG + +You now need to make a wire transfer to the exchange’s bank account +using the public key as the wire transfer subject. + +Make your wire transfer and (optionally) check at +“https://exchange/reserves/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 setup another reserve +every other week to ensure one is always ready. + +.. _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 “/private/reserves/$RID/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 “/tips/$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. + + + + +Advanced topics +=============== + +.. _MerchantDatabaseScheme: + +Database Scheme +--------------- + +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, +taler-merchant-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 merchant looks as follows: + +.. image:: merchant-db.png @@ -890,92 +1031,7 @@ While the configuration file is typically located at to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c`` option. -.. _Tipping-visitors: - -Tipping visitors ----------------- - -.. index:: 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. - -FIXME: write current explanation! - -.. _Fund-the-reserve: - -Fund the reserve -^^^^^^^^^^^^^^^^ - -.. index:: reserve -.. index:: close - -In our example, the output for the wire transfer subject 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. - -Make your wire transfer and (optionally) check at -“https://exchange/reserves/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 setup another reserve -every other week to ensure one is always ready. - -.. _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 “/private/reserves/$RID/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 “/tips/$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. .. _Benchmarking: @@ -984,6 +1040,8 @@ Benchmarking .. index:: testing database +NOTE: This section is dated and should be reviewed! + 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 @@ -1061,27 +1119,6 @@ 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. -.. _MerchantDatabaseScheme: - -Database Scheme ---------------- - -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, -taler-merchant-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 merchant looks as follows: - -.. image:: merchant-db.png - - - -Legacy -====== - This chapter contains some legacy documentation we need to update before it can be considered even reasonably accurate. @@ -1194,6 +1231,11 @@ purpose, issue the following command: + + +Legacy +====== + Installing Taler using Docker ----------------------------- -- cgit v1.2.3 From 7f6d92f19506e45e4e526d34af5210214e063311 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 25 Jun 2020 23:37:08 +0200 Subject: cleanup --- taler-exchange-manual.rst | 7 +++---- taler-merchant-manual.rst | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 2e84ab54..86abce8d 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -483,9 +483,8 @@ The generated file will be echoed by the exchange when serving Wire fee structure ~~~~~~~~~~~~~~~~~~ -.. meta:: - :keywords: wire fee - :keywords: fee +.. index:: wire fee +.. index:: fee For each wire method (“sepa” or “x-taler-wire”) the exchange configuration must specify applicable wire fees. This is done @@ -916,7 +915,7 @@ TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS purpose. -.. _Benchmarking: +.. _ExchangeBenchmarking: Benchmarking ============ diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 9f44960a..7e3eac6d 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1033,7 +1033,7 @@ option. -.. _Benchmarking: +.. _MerchantBenchmarking: Benchmarking ------------ -- cgit v1.2.3 From 18012a7d0568cda761b6f7886fa445e4e8f8ff65 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 26 Jun 2020 17:42:30 +0200 Subject: terminology for merchant backend --- taler-merchant-api-tutorial.rst | 23 +++- taler-merchant-manual.rst | 289 +++++++++++++++++++++++++++++++--------- 2 files changed, 247 insertions(+), 65 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-api-tutorial.rst b/taler-merchant-api-tutorial.rst index 6442e7c2..eb9505ce 100644 --- a/taler-merchant-api-tutorial.rst +++ b/taler-merchant-api-tutorial.rst @@ -1,5 +1,26 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2020 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License along with + TALER; see the file COPYING. If not, see + + @author Marcello Stanisci + @author Florian Dold + @author Christian Grothoff + +.. _merchant-api-tutorial: + GNU Taler Merchant API Tutorial -################################### +############################### Introduction ============ diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 7e3eac6d..6ffd193d 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -73,21 +73,24 @@ components: 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. + assumed to exist at the merchant. + The `Merchant API Tutorial <#merchant-api-tutorial>`__ gives an + introduction for how to integrate Taler with Web shop frontends. - A back office application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied. This component is - again not included with Taler, but rather assumed to exist at the - merchant. This manual will describe how to integrate such a component - to handle payments managed by Taler. + not included with Taler, but rather assumed to exist at the + merchant. The `Merchant Backend API <#merchant-api>`__ provides + the API specification that should be reviewed to integrate such a + back office with the 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. + 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 Postgres, but the code could be easily extended to support another - DBMS. + DBMS. Please review the Postgres documentation for details on + how to configure the database. The following image illustrates the various interactions of these key components: @@ -96,13 +99,150 @@ components: .. index:: 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. +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. + +A typical deployment will additionally include a full-blown Web server (like +Apache or Nginx). Such a Web server would be responsible for TLS termination +and access control to the /private/ API endpoints of the merchant backend. +Please carefully review the section on `Secure setup <#Secure-setup>`__ before +deploying a Taler merchant backend to production. + + +Terminology +=========== + +This chapter describes some of the key concepts used throughout the manual. + +Instances +--------- + +.. index:: instance + +The backend allows the user to run multiple *instances* of shops with distinct +business entities sharing a single backend. Each instance uses its own bank +accounts and key for signing contracts. All major accounting functionality is +separate per instance. What is shared is the database, HTTP(S) address and +the main Taler configuration (accepted currency, exchanges and auditors). + +Accounts +-------- + +.. index:: account + +To receive payments, an instance must have configured one or more bank +*accounts*. The backend does not have accounts for users, and instances are +also not really 'accounts'. So whenever we use the term *account*, it is about +a bank account of a merchant. + +Inventory +--------- + +.. index:: inventory +.. index:: product +.. index:: lock +.. index:: unit +.. index:: order + +The Taler backend offers inventory management as an optional function. +Inventory is tracked per instance and consists of *products* sold in +*units*. Inventory can be finite or infinite (for digital products). +Products may include previews (images) to be shown to the user and other +meta-data. Inventory management allows the frontend to *lock* products, +reserving them for a particular (unpaid) *order*. The backend can keep +track of how many units of a product remain in stock and ensure that +the number of units sold does not exceed the number of units in stock. + +Inventory management is optional, and it is possible for the frontend to +include products in orders that are not in the inventory, or to override +prices of products in the inventory. + +Orders and Contracts +-------------------- + +.. index:: order +.. index:: contract +.. index:: claim +.. index:: pay +.. index:: refund +.. index:: wire deadline +.. index:: lock +.. index:: legal expiration + +In Taler, users pay merchants for orders. An order is first created by the +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. + +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 +offer expires and any stock of products *locked* by the order is released, +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 until 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 +decade), contract information is deleted. + +Transfers +--------- + +.. index:: transfer +.. index:: wire transfer + +The Taler backend can be used to verify that the exchange correctly wired all +of the funds to the merchant. However, the backend does not have access to the +incoming wire transfers of the merchant's bank account. Thus, merchants must +manually provide the backend with wire *transfer* data that specifies the wire +transfer subject and the amount that was received. Given this information, the +backend can detect and report any irregularities that might arise. + +Tipping +------- + +.. index:: tip +.. index:: grant +.. index:: pick up + +Taler does not only allow a Website to be paid, but also to make voluntary, +non-contractual payments to visitors, called *tips*. Such tips could be +granted as a reward for filling in surveys or watching advertisements. For +tips, there is no contract, tips are always voluntary actions by the Web +site that do not arise from a contractual obligation. Before a Web site +can create tips, it must establish a reserve. Once a reserve has been +established, the merchant can *grant* tips, allowing wallets to *pick up* +the tip. + +Reserves +-------- + +.. index:: reserve +.. index:: close + +A *reserve* is a pool of electronic cash at an exchange under the control of +a private key. Merchants withdraw coins from a reserve when granting +tips. A reserve is established by first generating the required key material +in the merchant backend, and then wiring the desired amount of funds to the +exchange. + +An exchange will automatically *close* a reserve after a fixed period of time +(typically about a month), wiring any remaining funds back to the merchant. + Installation ============ @@ -211,17 +351,17 @@ Installing the GNU Taler exchange After installing GNUnet, you can download and install the exchange as follows: -:: + :: - $ git clone https://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-' option. See './configure --help'. - $ make - # make install + $ git clone https://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-' 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``. You have to specify @@ -244,18 +384,18 @@ The following steps assume all dependencies are installed. Use the following commands to download and install the merchant backend: -:: + :: - $ git clone https://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-' option. See './configure --help'. - $ make - # make install + $ git clone https://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-' 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``. @@ -287,7 +427,7 @@ 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 \ @@ -313,7 +453,7 @@ commands: For more recent versions of Debian, you should instead run: -:: + :: # apt-get install \ autoconf \ @@ -587,7 +727,7 @@ Sample backend configuration The following is an example for a complete backend configuration: -:: + :: [TALER] CURRENCY = KUDOS @@ -634,9 +774,9 @@ Launching the backend .. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the -merchant backend as ``$USER`` using: +merchant backend as ``$USER`` using -:: + :: $ taler-merchant-httpd @@ -647,13 +787,13 @@ system for how to start and stop daemons. 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. @@ -662,21 +802,19 @@ Production systems should be configured to bind to a UNIX domain socket and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__. -.. _Instances: +.. index:: instance +.. _Instance-setup: -Instances -========= +Instance setup +============== -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 at least the "default" instance. +Before using the backend, you must at least configure the "default" instance. Instances can be configured by POSTing the necessary requests to the backend. To create a first instance, create a file ``instance.json`` -with an `InstanceConfigurationMessage`: +with an `InstanceConfigurationMessage` -:: + :: { payto_uris : [ "payto://iban/IBANNUMBERHERE" ], @@ -693,7 +831,8 @@ with an `InstanceConfigurationMessage`: You can then create the instance using: -:: + :: + $ wget --post-file=instance.json http://localhost:8888/private/instances The base URL for the instance will then be @@ -719,14 +858,6 @@ The bank account information is provided in the form of a ``payto://``-URL. See RFC XXXX for the format of ``payto://``-URLs. -.. _Inventory: - -Inventory management -==================== - - - - .. _Secure-setup: @@ -736,14 +867,26 @@ Secure setup .. index:: security .. index:: TLS -For additional security, you may want to have the backend bind to a UNIX -domain socket and use an HTTP reverse proxy for TLS termination: +The Taler backend does not include even the most basic forms of +access control or transport layer security. Thus, production +setups **must** deploy the Taler backend behind an HTTP(S) server +that acts as a *reverse proxy*, performs TLS termination and +authentication and then forwards requests to the backend. + +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: :: $ taler-config -s MERCHANT -o SERVE -V UNIX $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock +Reverse proxy configuration +--------------------------- + Assuming your domain name is /example.com/ and you have TLS configured, a possible reverse proxy directive for Nginx would be: @@ -757,7 +900,25 @@ a possible reverse proxy directive for Nginx would be: 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 configuration. +changing the ``SERVE`` configuration. + +Access control +-------------- + +All endpoints with /private/ in the URL must be restricted to authorized users +of the respective instance. Specifically, the HTTP server must be configured +to only allow access to ``$BASE_URL/private/`` to the authorized users of the +default instance, and to ``$BASE_URL/instances/$ID/private/`` to the +authorized users of the instance ``$ID``. + +How access control is done (TLS client authentication, HTTP basic or digest +authentication, etc.) is completely up to the merchant and does not matter to +the Taler merchant backend. + +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. + Upgrade procedure -- cgit v1.2.3 From 0c7af9e8bba6007afd2820dd189d93614a3017ee Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 26 Jun 2020 20:28:11 +0200 Subject: update merchant documentation --- core/api-merchant.rst | 8 +++---- taler-merchant-manual.rst | 58 +++++++++++++++++++++++++++++++---------------- 2 files changed, 41 insertions(+), 25 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/core/api-merchant.rst b/core/api-merchant.rst index 5c50709a..c56cff0c 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -24,10 +24,7 @@ Merchant Backend API ==================== WARNING: This document describes the version 1 of the merchant backend -API, which is NOT yet implemented at all! - -TODO: https://bugs.gnunet.org/view.php?id=5987#c15127 - is not yet addressed by this specification! +API, which is NOT yet implemented in Git master! The ``*/private/*`` endpoints are only supposed to be exposed to the merchant internally, and must not be exposed on the @@ -35,7 +32,8 @@ Internet. Most endpoints given here can be prefixed by a base URL that includes the specific instance selected (BASE_URL/instances/$INSTANCE/). If -``/instances/`` is missing, the default instance is to be used. +``/instances/`` is missing from the request path, the ``default`` instance is +used. .. contents:: Table of Contents diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 6ffd193d..8652e13d 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -74,13 +74,13 @@ components: 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. - The `Merchant API Tutorial <#merchant-api-tutorial>`__ gives an + The :ref:`Merchant API Tutorial ` gives an introduction for how to integrate Taler with Web shop frontends. - A back office application that enables the shop operators to view customer orders, match them to financial transfers, and possibly approve refunds if an order cannot be satisfied. This component is not included with Taler, but rather assumed to exist at the - merchant. The `Merchant Backend API <#merchant-api>`__ provides + merchant. The :ref:`Merchant Backend API ` provides the API specification that should be reviewed to integrate such a back office with the Taler backend. - A Taler-specific payment backend which makes it easy for the frontend @@ -110,7 +110,7 @@ the Taler backend. A typical deployment will additionally include a full-blown Web server (like Apache or Nginx). Such a Web server would be responsible for TLS termination and access control to the /private/ API endpoints of the merchant backend. -Please carefully review the section on `Secure setup <#Secure-setup>`__ before +Please carefully review the section on :ref:`Secure setup ` before deploying a Taler merchant backend to production. @@ -799,7 +799,7 @@ should return the message Please note that your backend is right now likely globally reachable. Production systems should be configured to bind to a UNIX domain socket -and use TLS for improved network privacy, see `Secure setup <#Secure-setup>`__. +and use TLS for improved network privacy, see :ref:`Secure setup `. .. index:: instance @@ -810,9 +810,9 @@ Instance setup Before using the backend, you must at least configure the "default" instance. -Instances can be configured by POSTing the necessary requests to the -backend. To create a first instance, create a file ``instance.json`` -with an `InstanceConfigurationMessage` +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` :: @@ -841,7 +841,7 @@ instances by changing the "id" value to identifies other than "default". Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented -in the `Merchant Backend API documentation <#merchant-api>`__. +in the :ref:`Merchant Backend API documentation `. Accounts @@ -959,17 +959,13 @@ Tipping visitors .. index:: tipping -NOTE: This section is dated and should be reviewed! - 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. - -FIXME: write current explanation! +There are three basic steps that must happen to tip a visitor. .. _Fund-the-reserve: @@ -977,7 +973,27 @@ Fund the reserve ---------------- .. index:: reserve -.. index:: close + +First, the reserve must be setup in the merchant backend. A reserve +is always tied to a particular instance. To create a reserve with +10 KUDOS at instance "default" using the demo exchange, use: + + :: + + $ taler-merchant-setup-reserve \ + -a KUDOS:10 \ + -e https://exchange.demo.taler.net/ \ + -m http://localhost:8888/instances/default + +The above command assumes that the merchant runs on localhost on +port 8888. The current implementation of the tool does not yet support +transmission of authentication information to the backend +(`see bug 6418 `_). + +The command will output a payto:// URI which specifies where to +wire the funds and which wire transfer subject to use. + +FIXME: add full example output. In our example, the output for the wire transfer subject is: @@ -986,7 +1002,7 @@ In our example, the output for the wire transfer subject 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. +using the given wire transfer subject. Make your wire transfer and (optionally) check at “https://exchange/reserves/QPE24X...” whether your transfer has arrived at the @@ -1008,7 +1024,8 @@ 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 “/private/reserves/$RID/tip-authorize” API of the backend. To authorize a +the :http:post:`/private/reserves/$RESERVE_PUB/authorize-tip` +API of the backend. To authorize a tip, the frontend has to provide the following information in the body of the POST request: @@ -1037,7 +1054,8 @@ missconfigured instances or a lack of remaining funds for tipping. Picking up of the tip --------------------- -The wallet will POST a JSON object to the shop’s “/tips/$TIP/pickup” handler. +The wallet will POST a JSON object to the shop’s +:http:post:`/tips/$TIP_ID/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. @@ -1128,7 +1146,7 @@ Note that, in this stage of development, the file component. For example, both an exchange and a bank can read values from it. -The repository ``git://taler.net/deployment`` contains examples of +The `deployment repository `_ contains examples of configuration file used in our demos. See under ``deployment/config``. **Note** @@ -1416,12 +1434,12 @@ 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`` +repository, we start by checking out the ``git://git.taler.net/deployment`` codebase: :: - $ git clone git://taler.net/deployment + $ git clone git://git.taler.net/deployment Now we actually build the merchant’s image. From the same directory as above: -- cgit v1.2.3 From 3f1f866aa002236da754b26284823b83c6010a2b Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 28 Jun 2020 22:06:31 +0200 Subject: bump required version --- taler-exchange-manual.rst | 2 +- taler-merchant-manual.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 86abce8d..703b3267 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -176,7 +176,7 @@ exchange compilation. - libcurl >= 7.26 (or libgnurl >= 7.26) -- GNU libmicrohttpd >= 0.9.59 +- GNU libmicrohttpd >= 0.9.71 - GNU libgcrypt >= 1.6 diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 8652e13d..a064efce 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -284,7 +284,7 @@ backend: - libcurl >= 7.26 (or libgnurl >= 7.26) -- GNU libmicrohttpd >= 0.9.59 +- GNU libmicrohttpd >= 0.9.71 - GNU libgcrypt >= 1.6 -- cgit v1.2.3 From a951ebe385efd96dbe84ed9798efe0949feae824 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 4 Jul 2020 23:55:17 +0200 Subject: begin to document benchmark setup --- manpages/taler.conf.5.rst | 3 +++ taler-merchant-manual.rst | 37 ++++++++++++++++++++++++++++++++++--- 2 files changed, 37 insertions(+), 3 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index bfdece3c..82bff393 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -239,6 +239,9 @@ DURATION_WITHDRAW DURATION_SPEND How long do clients have to spend these coins? +DURATION_LEGAL + How long does the exchange have to keep records for this denomination? + FEE_WITHDRAW What fee is charged for withdrawal? diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index a064efce..d6ea1bf7 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1221,6 +1221,40 @@ Benchmarking NOTE: This section is dated and should be reviewed! +Setup: create Exchange account and two user accounts ``42`` and ``43`` at +the bank: + +:: + + $ 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: + +:: + + $ taler-bank-manage django changepassword_unsafe Exchange PASSWORD + +Configure merchant and exchange, then run: + +:: + + $ taler-exchange-dbinit + $ taler-exchange-keyup + $ taler-merchant-dbinit + +Launch bank, exchange and merchant backends: + +:: + + $ taler-bank-manage serve-http + $ taler-exchange-httpd + $ taler-merchant-httpd + + + + 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 @@ -1230,9 +1264,6 @@ 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. -- cgit v1.2.3 From ec491ae8d7fe7444db68a8a4683c3dcafb994b3c Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 4 Jul 2020 23:59:23 +0200 Subject: wip --- taler-merchant-manual.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'taler-merchant-manual.rst') diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index d6ea1bf7..f48fb07a 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -1221,6 +1221,13 @@ Benchmarking 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! + + Setup: create Exchange account and two user accounts ``42`` and ``43`` at the bank: @@ -1248,11 +1255,9 @@ Launch bank, exchange and merchant backends: :: - $ taler-bank-manage serve-http - $ taler-exchange-httpd - $ taler-merchant-httpd - - + $ taler-bank-manage serve-http & + $ taler-exchange-httpd & + $ taler-merchant-httpd & The merchant codebase offers the ``taler-merchant-benchmark`` tool to -- cgit v1.2.3