diff options
Diffstat (limited to 'texinfo/taler-merchant.texi')
| -rw-r--r-- | texinfo/taler-merchant.texi | 91 |
1 files changed, 52 insertions, 39 deletions
diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi index 23e70812..5c5f9e5b 100644 --- a/texinfo/taler-merchant.texi +++ b/texinfo/taler-merchant.texi @@ -21,7 +21,7 @@ @copying @quotation -GNU Taler 0.8.0pre0, Aug 03, 2021 +GNU Taler 0.8.2, Aug 08, 2021 GNU Taler team @@ -303,10 +303,9 @@ merchant’s signing keys and bank account information are 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 @code{/private/} API endpoints of the merchant backend. -Please carefully review the section on @ref{9,,Secure setup} before -deploying a Taler merchant backend to production. +Apache or Nginx). Such a Web server would be responsible for TLS termination and +access control to the @code{/private/} and @code{/management/} API endpoints of the +merchant backend. Please carefully review the section on @ref{9,,Secure setup} before deploying a Taler merchant backend to production. @node Terminology,Installation,Introduction,Top @anchor{taler-merchant-manual terminology}@anchor{a} @@ -348,7 +347,7 @@ the main Taler configuration (accepted currency, exchanges and auditors). To receive payments, an instance must have configured one or more bank @emph{accounts}. The backend does not have accounts for users, and instances are -also not really 'accounts'. So whenever we use the term @emph{account}, it is about +also not really ‘accounts’. So whenever we use the term @emph{account}, it is about a bank account of a merchant. @node Inventory,Orders and Contracts,Accounts,Terminology @@ -447,7 +446,7 @@ decade), contract information is deleted. 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 +incoming wire transfers of the merchant’s bank account. Thus, merchants must manually provide the backend with wire @emph{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. @@ -465,7 +464,7 @@ backend can detect and report any irregularities that might arise. Taler does not only allow a Website to be paid, but also to make voluntary, non-contractual payments to visitors, called @emph{tips}. Such tips could be -granted as a reward for filling in surveys or watching advertisements. For +granted as a reward for filling in surveys or watching advertizements. 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 @@ -621,7 +620,7 @@ shared object libraries (@code{.so} files) visible to the various installed programs. 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 +backend – all the merchant needs from GNUnet is a number of headers and libraries! @node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source @@ -649,7 +648,7 @@ which requires you to run the last step as @code{root}. You have to specify 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 +backend – all the merchant needs from the Taler exchange is a few headers and libraries! @node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source @@ -1290,7 +1289,7 @@ that section, the following options need to be configured: @item The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL. -For example, to use the Taler demonstrator's auditor, specify: +For example, to use the Taler demonstrator’s auditor, specify: @example $ taler-config -s MERCHANT-AUDITOR-demo \ @@ -1299,7 +1298,7 @@ $ taler-config -s MERCHANT-AUDITOR-demo \ @end example @item -The @code{AUDITOR_KEY} option specifies the auditor's public key +The @code{AUDITOR_KEY} option specifies the auditor’s public key in base32 encoding. For the Taler demonstrator, use: @example @@ -1429,7 +1428,7 @@ and use TLS for improved network privacy, see @ref{9,,Secure setup}. @chapter Instance setup -Before using the backend, you must at least configure the "default" instance. +Before using the backend, you must at least configure the “default” instance. @menu * KUDOS Accounts:: @@ -1478,7 +1477,7 @@ IBAN, the corresponding @code{payto://}-URI is simply @code{payto://iban/$IBAN} With the knowledge of the @code{payto://}-URI, instances can be configured by POSTing -a request to @code{POST /private/instances}. To create a first instance, +a request to @code{/management/instances}. To create a first instance, create a file @code{instance.json} with an InstanceConfigurationMessage @example @@ -1500,7 +1499,7 @@ create a file @code{instance.json} with an InstanceConfigurationMessage In the text above, you must replace @code{$PAYTO_URI} with your actual @code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the setup is for an actual bank. The @code{name} field will be shown as the name of -your shop. The @code{address} field is expected to contain your shop's physical +your shop. The @code{address} field is expected to contain your shop’s physical address. The various defaults specify defaults for transaction fees your shop is willing to cover, how long offers made to the customer are valid, and how long the exchange has before it must wire the funds to your bank @@ -1510,7 +1509,7 @@ For details, see the contract terms specification. You can then create the instance using: @example -$ wget --post-file=instance.json http://localhost:8888/private/instances +$ wget --post-file=instance.json http://localhost:8888/management/instances @end example The base URL for the instance will then be @@ -1556,9 +1555,9 @@ $ taler-config -s MERCHANT -o SERVE -V UNIX $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock @end example -Do not use a UNIX domain socket path in "/tmp": systemd (or other init -systems) may give Web servers a private "/tmp" thereby hiding UNIX domain -sockets created by other users/processes in "/tmp". +Do not use a UNIX domain socket path in “/tmp”: systemd (or other init +systems) may give Web servers a private “/tmp” thereby hiding UNIX domain +sockets created by other users/processes in “/tmp”. If UNIX domain sockets are for some reason not possible, you @emph{may} use a host-based firewall to block access to the TCP port of the merchant backend, @@ -1632,19 +1631,20 @@ setup access control! @section Access control -All endpoints with @code{/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 @code{$BASE_URL/private/} to the authorized users of the -default instance, and to @code{$BASE_URL/instances/$ID/private/} to the -authorized users of the instance @code{$ID}. +All endpoints with @code{/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 @code{$BASE_URL/private/} and +@code{$BASE_URL/management/} to the authorized users of the default instance, and +to @code{$BASE_URL/instances/$ID/private/} to the authorized users of the instance +@code{$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 @code{/private/}) are expected to be -fully exposed to the Internet, and wallets may have to interact with those -endpoints directly without client authentication. +Note that all of the other endpoints (without @code{/private/} or @code{/management/}) +are expected to be fully exposed to the Internet, and wallets may have to +interact with those endpoints directly without client authentication. @menu * Nginx: Nginx<2>. @@ -1667,6 +1667,12 @@ location ~ /private/ @{ @} proxy_pass ...; // as above @} +location /management/ @{ + if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") @{ + return 401; + @} + proxy_pass ...; // as above +@} @end example Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret. Note @@ -1698,6 +1704,12 @@ location /private/ @{ @} proxy_pass ...; # as above @} +location /management/ @{ + if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") @{ + return 401; + @} + proxy_pass ...; # as above +@} location ~ /private/ @{ return 401; # access to instances not explicitly configured is forbidden @} @@ -1721,6 +1733,7 @@ Then, you can restrict to an access control token using: RewriteEngine On RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=SECURITYTOKEN" RewriteRule "(.+)/private/" "-" [F] +RewriteRule "/management/" "-" [F] ProxyPass "unix:/some/path/here.sock|http://example.com/" </Location> @@ -1729,7 +1742,7 @@ ProxyPass "unix:/some/path/here.sock|http://example.com/" Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret. Note that the @code{(.+)} ensures that the above matches all endpoints that include the string @code{/private/}. If you only run a single instance, you could simply -specify @code{/private/} without the @code{~} to only configure the access policy for +specify @code{/private/} without the @code{(.+)} to only configure the access policy for the default instance. If you are running different instances on the same backend, you @@ -1757,6 +1770,7 @@ ProxyPass ... # as above RewriteEngine On RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=MASTERTOKEN" RewriteRule "/private/" "-" [F] +RewriteRule "/management/" "-" [F] RewriteRule "(.+)/private/" "-" [F] # reject all others ProxyPass ... # as above @@ -1832,7 +1846,7 @@ process to hold open file handles for all of these files. You may want to increase the @code{ulimit} of the @code{taler-merchant-httpd} process if you have templates for many languages. -The backend determines the MIME type based on the file's extension. The list +The backend determines the MIME type based on the file’s extension. The list of supported extensions is hard-coded and includes common text and image formats. @@ -1932,7 +1946,7 @@ You now need to make a wire transfer to the exchange’s bank account using the given wire transfer subject. Make your wire transfer and (optionally) check at -“@indicateurl{https://exchange/reserves/QPE24X}...” whether your transfer has arrived at the +“@indicateurl{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 @@ -1951,8 +1965,7 @@ every other week to ensure one is always ready. 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 @code{POST /private/reserves/$RESERVE_PUB/authorize-tip} -API of the backend. To authorize a +a POST to @code{/private/reserves/$RESERVE_PUB/authorize-tip}. To authorize a tip, the frontend has to provide the following information in the body of the POST request: @@ -1990,7 +2003,7 @@ misconfigured instances or a lack of remaining funds for tipping. The wallet will POST a JSON object to the shop’s -@code{POST /tips/$TIP_ID/pickup} handler. +@code{/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. @@ -2203,13 +2216,13 @@ start. The @code{taler-merchant-benchmark} tool will automatically launch and configure the exchange, (Python) bank and other tools required for the benchmark. However, the configuration file must be provided and have consistent options set. The -options that require special care include the exchange's public key (which +options that require special care include the exchange’s public key (which must match the private key in the file specified by the configuration), the currency (which must be consistent across the file), the denomination structure (which must enable payments in the range of 100ths of the unit currency (often called cents)). Furthermore, the benchmark will set the -Exchange bank account password to be "x", so the configuration must also -specify "x" for the passphrase. Finally, the bank must be configured to allow +Exchange bank account password to be “x”, so the configuration must also +specify “x” for the passphrase. Finally, the bank must be configured to allow for substantial debt least the transactions by the benchmark run out of digital cash. @@ -2341,10 +2354,10 @@ rsa_keysize = 1024 @end example -Note that the public key must match the exchange's +Note that the public key must match the exchange’s private key and that the Postgres database must exist before launching the benchmark. You also -will need to ensure that the Exchange's +will need to ensure that the Exchange’s details are set up. For details, see the Exchange Operator Manual. @@ -2413,7 +2426,7 @@ options: @item @code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking operations. Note that the @strong{total} amount of operations will be two -times @emph{TN}, since "one" tracking operation accounts for +times @emph{TN}, since “one” tracking operation accounts for @code{/track/transaction} and @code{/track/transfer}. This command should only be used to see if the operation ends without problems, as no actual measurement of performance is provided (despite of the |