From f3bdacc82bd86c4895dd5ec62b4093a8716f8503 Mon Sep 17 00:00:00 2001 From: Marcello Stanisci Date: Wed, 21 Sep 2016 14:01:09 +0200 Subject: addressing warnings and error in compilation --- api-bank.rst | 4 +- api-exchange.rst | 27 ++++----- api-merchant.rst | 1 + dev-merchant.rst | 1 + dev-wallet-wx.rst | 2 + example-essay-store.rst | 2 + impl-exchange.rst | 155 ------------------------------------------------ impl-merchant.rst | 73 ----------------------- index.rst | 4 +- integration-bank.rst | 6 +- operate-exchange.rst | 155 ++++++++++++++++++++++++++++++++++++++++++++++++ operate-merchant.rst | 72 ++++++++++++++++++++++ 12 files changed, 252 insertions(+), 250 deletions(-) delete mode 100644 impl-exchange.rst delete mode 100644 impl-merchant.rst create mode 100644 operate-exchange.rst create mode 100644 operate-merchant.rst diff --git a/api-bank.rst b/api-bank.rst index afb2ba28..48b7075e 100644 --- a/api-bank.rst +++ b/api-bank.rst @@ -35,10 +35,10 @@ namely exchanges. **Response:** -:status 200 OK: The request has been correctly handled, so the funds have been transferred to -the recipient's account +:status 200 OK: The request has been correctly handled, so the funds have been transferred to the recipient's account :status 400 Bad Request: The bank replies a `BankIncomingError`_ object + **Details:** .. _BankDepositRequest: diff --git a/api-exchange.rst b/api-exchange.rst index 63ac477c..3087a8e8 100644 --- a/api-exchange.rst +++ b/api-exchange.rst @@ -233,8 +233,7 @@ Obtaining wire-transfer information // A single /wire response can contain an arbitrary number of these // string-object pairs. However, the keys must be unique. string : Object; - - } + } Possible encodings for the objects are right now the following: @@ -242,7 +241,7 @@ Obtaining wire-transfer information .. _tsref-type-WireTestResponse: .. code-block:: tsref - interface WireTestResponse { + interface WireTestResponse { // Mandatory indicator that this is a TEST wire response. type: "test"; @@ -251,14 +250,13 @@ Obtaining wire-transfer information // URI of the bank bank_uri: string; - } - .. _WireSepaResponse: + .. _WireSepaResponse: .. _tsref-type-WireSepaResponse: .. code-block:: tsref - interface WireSepaResponse { + interface WireSepaResponse { // Mandatory indicator that this is a SEPA wire response. type: "sepa"; @@ -271,13 +269,12 @@ Obtaining wire-transfer information // BIC of the bank. bic: string; - // the EdDSA signature_ (binary-only) with purpose + // the EdDSA signature (binary-only) with purpose // `TALER_SIGNATURE_EXCHANGE_PAYMENT_METHOD_SEPA` signing over the hash over the // 0-terminated strings representing the receiver's name, IBAN and the BIC. sig: EddsaSignature; } - ------------------ Withdrawal ------------------ @@ -445,9 +442,9 @@ exchange. .. _deposit-par: --------------------- +------- Deposit --------------------- +------- Deposit operations are requested by a merchant during a transaction. For the deposit operation, the merchant has to obtain the deposit permission for a coin @@ -543,9 +540,9 @@ denomination. has enough residual value that has not already been deposited or melted. + .. _DepositSuccess: .. code-block:: tsref - .. _DepositSuccess: interface DepositSuccess { // The string constant "DEPOSIT_OK" status: string; @@ -562,7 +559,7 @@ denomination. // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. pub: EddsaPublicKey; - } + } .. _DepositDoubleSpendError: .. code-block:: tsref @@ -1150,10 +1147,10 @@ Refunds } + .. _RefundSuccess: .. code-block:: tsref - .. _RefundSuccess: - interface RefundSuccess { + interface RefundSuccess { // The string constant "REFUND_OK" status: string; @@ -1167,7 +1164,7 @@ Refunds // explicitly as the client might otherwise be confused by clock skew as to // which signing key was used. pub: EddsaPublicKey; - } + } ------------------------------ Administrative API: Key update diff --git a/api-merchant.rst b/api-merchant.rst index ff347979..8815e750 100644 --- a/api-merchant.rst +++ b/api-merchant.rst @@ -228,6 +228,7 @@ The following API are made available by the merchant's `backend` to the merchant :query id: ID of the transaction we want to trace (an integer) :query receiver: identificative token for the merchant instance which is to be tracked (optional). See :ref:`instances`. + **Response:** :status 200 OK: diff --git a/dev-merchant.rst b/dev-merchant.rst index bb809128..cb834659 100644 --- a/dev-merchant.rst +++ b/dev-merchant.rst @@ -22,6 +22,7 @@ Introduction TBD .. _merchant-arch: + ------ Design ------ diff --git a/dev-wallet-wx.rst b/dev-wallet-wx.rst index 5995226e..8ba29975 100644 --- a/dev-wallet-wx.rst +++ b/dev-wallet-wx.rst @@ -170,12 +170,14 @@ Internationalisation Strings in the JavaScript code are internationalised using the following functions: - *i18n*: translate string with arbitrary arguments, the result is returned as string. + .. code-block:: js i18n`You have ${n} coins.` - *i18n.parts*: Interpolate i18nized values with arbitrary objects. Useful for example to include HTML elements. + .. code-block:: js i18n.parts`Visit ${link} to get more coins.` diff --git a/example-essay-store.rst b/example-essay-store.rst index 102e54db..2a240f86 100644 --- a/example-essay-store.rst +++ b/example-essay-store.rst @@ -41,7 +41,9 @@ offer URL returns a HTML page that can either show a pay-form in case Taler is n in the user's browser or download the contract from the merchant. If the user has Taler installed and wants to pay, the wallet will POST the coins to a URL of the form: + `https://blog.demo.taler.net/pay?uuid=${contract_hashcode}` + The URL comes with the contract's hashcode because each contract is an entry in the merchant's state, so it can mark it as ``payed`` whenever it receives coins. diff --git a/impl-exchange.rst b/impl-exchange.rst deleted file mode 100644 index ce2cb4d7..00000000 --- a/impl-exchange.rst +++ /dev/null @@ -1,155 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA - 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 Christian Grothoff - -====================== -Operating the Exchange -====================== - -+++++++++++++ -Configuration -+++++++++++++ - -The following data and facilities have to be set up, in order to run an exchange: - -* Keying -* Serving -* Currency -* Bank account -* Coins -* Database - -In this document, we assume that ``$HOME/.config/taler.conf`` is being customized. - ------- -Keying ------- - -The exchange works with three types of keys: - -* `master key` -* `sign keys` -* `denomination keys` (see section `Coins`) - -`master key`: in section `[exchange]`, edit the two following values: - -* `master_priv_file`: Path to the exchange's master private file. -* `master_public_key`: Must specify the exchange's master public key. - -`sign keys`: the following two options under `[exchange_keys]` section control `sign keys`: - -* `lookahead_sign`: How long should one signing key be used? -* `signkey_duration`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. - -.. note:: - `signkeys` will be used in future versions of Taler. - -------- -Serving -------- - -The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this -configuration *twice*, because it opens one connection for ordinary REST calls, and one -for "/admin" and "/test" REST calls, because the operator may want to restrict the access to "/admin". - -The following values are to be configured under the section `[exchange]` and `[exchange-admin]`: - -* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket -* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`. -* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix` -* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----). - -The exchange can be started with the `-D` option to disable the administrative -functions entirely. It is recommended that the administrative API is only -accessible via a properly protected UNIX domain socket. - --------- -Currency --------- - -The exchange supports only one currency. This data is set under the respective -option `currency` in section `[taler]`. - ------------- -Bank account ------------- - -The command line tool `taler-exchange-wire` is used to create a file with -the JSON response to /wire requests using the exchange's offline -master key. The resulting file's path needs to be added to the configuration -under the respective option for the wire transfer method, i.e. -`sepa_response_file` in section `[exchange-wire-incoming-sepa]` when the -`wireformat` option in the configuration file allows `sepa` transactions. For example, -the utility may be invoked as follows:: - - taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json - -Note that the value given to option `-t` must match the value in the JSON's field ``"type"``. `exchange.json` will be the same JSON given to ``-j`` plus the field -``"sig"``, which holds the signature of the JSON given in option ``-j`` made with exchange's master key. Finally, if `taler-exchange-wire` will not find any master -key at the location mentioned in `master_priv_file`, it will automatically generate (and use) one. - --------- -Database --------- - -The option `db` under section `[exchange]` gets the DB backend's name the exchange -is going to use. So far, only `db = postgres` is supported. After choosing the backend, -it is mandatory to supply the connection string (namely, the database name). This is -possible in two ways: - -* via an environment variable: `TALER_EXCHANGEDB_POSTGRES_CONFIG`. -* via configuration option `db_conn_str`, under section `[exchangedb-BACKEND]`. For example, the demo exchange is configured as follows: - -.. code-block:: text - - [exchange] - ... - db = postgres - ... - - [exchange-postgres] - db_conn_str = postgres:///talerdemo - -------------------------- -Coins (denomination keys) -------------------------- - -Sections specifying denomination (coin) information start with "coin\_". By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. `[coin_eur_ct_10]` for a 10 cent piece. However, only the "coin\_" prefix is mandatory. Each "coin\_"-section must then have the following options: - -* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10". -* `duration_withdraw`: How long can a coin of this type be withdrawn? This limits the losses incurred by the exchange when a denomination key is compromised. -* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type? -* `duration_spend`: How long is a coin of the given type valid? Smaller values result in lower storage costs for the exchange. -* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`. -* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`. -* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`. -* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin. - ------------------------ -Keys duration ------------------------ - -Both `signkeys` and `denom keys` have a :ref:`starting date ` (see :ref:`how ` this date is calculated). -The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys whose starting date is -younger than `lookahead_provide` will be issued by the exchange. - -+++++++++ -Utilities -+++++++++ - ------------------- -Reserve management ------------------- - -Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their withdrawal key. -The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database. diff --git a/impl-merchant.rst b/impl-merchant.rst deleted file mode 100644 index 45c83baf..00000000 --- a/impl-merchant.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. - This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016 INRIA - 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 - -============================== -Operating the Merchant Backend -============================== - -+++++++++++++ -Configuration -+++++++++++++ - -The following data and facilities have to be set up, in order to run an exchange: - -* Keying -* Currency -* Database -* Instances -* Exchanges - ------- -Keying ------- - -The merchant backend can serve HTTP over both TCP and UNIX domain socket. - -The following values are to be configured under the section `[merchant]`: - -* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket -* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`. -* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix` -* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----). - --------- -Currency --------- - -The merchant backend supports only one currency. This data is set under the respective -option `currency` in section `[taler]`. - --------- -Database --------- - -The option `db` under section `[merchant]` gets the DB backend's name the merchant -is going to use. So far, only `db = postgres` is supported. After choosing the backend, -it is mandatory to supply the connection string (namely, the database name). This is -possible in two ways: - -* via an environment variable: `TALER_MERCHANTDB_POSTGRES_CONFIG`. -* via configuration option `config`, under section `[merchantdb-BACKEND]`. For example, -the demo merchant is configured as follows: - -.. code-block:: text - - [merchant] - ... - db = postgres - ... - - [merchantdb-postgres] - config = postgres:///talerdemo diff --git a/index.rst b/index.rst index 15b06e0f..41e7bc05 100644 --- a/index.rst +++ b/index.rst @@ -53,8 +53,8 @@ It focuses on how to install, configure and run the required software. global_licensing configuration-basics - impl-exchange - impl-merchant + operate-exchange + operate-merchant versioning ------------------------ diff --git a/integration-bank.rst b/integration-bank.rst index b8e24937..1dc2ec8d 100644 --- a/integration-bank.rst +++ b/integration-bank.rst @@ -26,11 +26,11 @@ As a result of the reserve creation request, the following steps will happen in 2. Upon confirmation, the wallet fetches the desired amount from the user-filled form and prompts the user for the *exchange base URL*. Then ask the user to confirm creating the reserve. - 2. The wallet will create a key pair for the reserve. - 3. The wallet will request the CAPTCHA page to the bank. In that request's parameters it + 3. The wallet will create a key pair for the reserve. + 4. The wallet will request the CAPTCHA page to the bank. In that request's parameters it communicates the desired amount, the reserve's public key and the exchange base URL to the bank - 4. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve + 5. Upon successful resolution of the CAPTCHA by the user, the bank initiates the reserve creation according to the gotten parameters. Together with `200 OK` status code sent back to the wallet, it gets also a `ReserveCreated`_ object. diff --git a/operate-exchange.rst b/operate-exchange.rst new file mode 100644 index 00000000..b276d06d --- /dev/null +++ b/operate-exchange.rst @@ -0,0 +1,155 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA + 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 Christian Grothoff + +====================== +Operating the Exchange +====================== + ++++++++++++++ +Configuration ++++++++++++++ + +The following data and facilities have to be set up, in order to run an exchange: + +* Keying +* Serving +* Currency +* Bank account +* Coins +* Database + +In this document, we assume that ``$HOME/.config/taler.conf`` is being customized. + +------ +Keying +------ + +The exchange works with three types of keys: + +* `master key` +* `sign keys` +* `denomination keys` (see section `Coins`) + +`master key`: in section `[exchange]`, edit the two following values: + +* `master_priv_file`: Path to the exchange's master private file. +* `master_public_key`: Must specify the exchange's master public key. + +`sign keys`: the following two options under `[exchange_keys]` section control `sign keys`: + +* `lookahead_sign`: How long should one signing key be used? +* `signkey_duration`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. + +.. note:: + `signkeys` will be used in future versions of Taler. + +------- +Serving +------- + +The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this +configuration *twice*, because it opens one connection for ordinary REST calls, and one +for "/admin" and "/test" REST calls, because the operator may want to restrict the access to "/admin". + +The following values are to be configured under the section `[exchange]` and `[exchange-admin]`: + +* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket +* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`. +* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix` +* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----). + +The exchange can be started with the `-D` option to disable the administrative +functions entirely. It is recommended that the administrative API is only +accessible via a properly protected UNIX domain socket. + +-------- +Currency +-------- + +The exchange supports only one currency. This data is set under the respective +option `currency` in section `[taler]`. + +------------ +Bank account +------------ + +The command line tool `taler-exchange-wire` is used to create a file with +the JSON response to /wire requests using the exchange's offline +master key. The resulting file's path needs to be added to the configuration +under the respective option for the wire transfer method, i.e. +`sepa_response_file` in section `[exchange-wire-incoming-sepa]` when the +`wireformat` option in the configuration file allows `sepa` transactions. For example, +the utility may be invoked as follows:: + + taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json + +Note that the value given to option `-t` must match the value in the JSON's field ``"type"``. `exchange.json` will be the same JSON given to ``-j`` plus the field +``"sig"``, which holds the signature of the JSON given in option ``-j`` made with exchange's master key. Finally, if `taler-exchange-wire` will not find any master +key at the location mentioned in `master_priv_file`, it will automatically generate (and use) one. + +-------- +Database +-------- + +The option `db` under section `[exchange]` gets the DB backend's name the exchange +is going to use. So far, only `db = postgres` is supported. After choosing the backend, +it is mandatory to supply the connection string (namely, the database name). This is +possible in two ways: + +* via an environment variable: `TALER_EXCHANGEDB_POSTGRES_CONFIG`. +* via configuration option `db_conn_str`, under section `[exchangedb-BACKEND]`. For example, the demo exchange is configured as follows: + +.. code-block:: text + + [exchange] + ... + db = postgres + ... + + [exchange-postgres] + db_conn_str = postgres:///talerdemo + +------------------------- +Coins (denomination keys) +------------------------- + +Sections specifying denomination (coin) information start with "coin\_". By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. `[coin_eur_ct_10]` for a 10 cent piece. However, only the "coin\_" prefix is mandatory. Each "coin\_"-section must then have the following options: + +* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10". +* `duration_withdraw`: How long can a coin of this type be withdrawn? This limits the losses incurred by the exchange when a denomination key is compromised. +* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type? +* `duration_spend`: How long is a coin of the given type valid? Smaller values result in lower storage costs for the exchange. +* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`. +* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`. +* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`. +* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin. + +----------------------- +Keys duration +----------------------- + +Both `signkeys` and `denom keys` have a :ref:`starting date `. +The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys whose starting date is +younger than `lookahead_provide` will be issued by the exchange. + ++++++++++ +Utilities ++++++++++ + +------------------ +Reserve management +------------------ + +Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their withdrawal key. +The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database. diff --git a/operate-merchant.rst b/operate-merchant.rst new file mode 100644 index 00000000..572c7d6d --- /dev/null +++ b/operate-merchant.rst @@ -0,0 +1,72 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014, 2015, 2016 INRIA + 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 + +============================== +Operating the Merchant Backend +============================== + ++++++++++++++ +Configuration ++++++++++++++ + +The following data and facilities have to be set up, in order to run an exchange: + +* Keying +* Currency +* Database +* Instances +* Exchanges + +------ +Keying +------ + +The merchant backend can serve HTTP over both TCP and UNIX domain socket. + +The following values are to be configured under the section `[merchant]`: + +* `SERVE`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket +* `PORT`: set to the TCP port to listen on if `SERVE` is `tcp`. +* `UNIXPATH`: set to the UNIX domain socket path to listen on if `SERVE` is `unix` +* `UNIXPATH_MODE`: number giving the mode with the access permission mask for the `UNIXPATH` (i.e. 660 = rw-rw----). + +-------- +Currency +-------- + +The merchant backend supports only one currency. This data is set under the respective +option `currency` in section `[taler]`. + +-------- +Database +-------- + +The option `db` under section `[merchant]` gets the DB backend's name the merchant +is going to use. So far, only `db = postgres` is supported. After choosing the backend, +it is mandatory to supply the connection string (namely, the database name). This is +possible in two ways: + +* via an environment variable: `TALER_MERCHANTDB_POSTGRES_CONFIG`. +* via configuration option `config`, under section `[merchantdb-BACKEND]`. For example, the demo merchant is configured as follows: + +.. code-block:: text + + [merchant] + ... + db = postgres + ... + + [merchantdb-postgres] + config = postgres:///talerdemo -- cgit v1.2.3