-remove obsolete access control docs

2 files changed, 102 insertions, 186 deletions

diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index dbccd826..c9c86c68 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -76,9 +76,21 @@ exchange tools.
 DB
   Plugin to use for the database, e.g. “postgres”.
 
+SERVE
+  Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+  Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+  Access permission mask to use for the "UNIXPATH".
+
 PORT
   Port on which the HTTP server listens, e.g. 8080.
 
+BIND_TO
+  Hostname to which the exchange HTTP server should be bound to, e.g. "localhost".
+
 MASTER_PUBLIC_KEY
   Crockford Base32-encoded master public key, public version of the
   exchange's long-time offline signing key.
@@ -176,10 +188,13 @@ The following options must be in the section "[kyc-provider-XXX]" sections.
 
 COST
   Relative cost of the KYC provider, non-negative number.
+
 LOGIC
   API type of the KYC provider.
+  
 USER_TYPE
   Type of user this provider is for, either INDIVIDUAL or BUSINESS.
+  
 PROVIDED_CHECKS
   List of checks performed by this provider. Space-separated names of checks, must match check names in legitimization rules.
 
@@ -567,9 +582,21 @@ merchant backend.
 DB
    Plugin to use for the database, e.g._“postgres”.
 
+SERVE
+  Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+  Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+  Access permission mask to use for the "UNIXPATH".
+
 PORT
    Port on which the HTTP server listens, e.g. 8080.
 
+BIND_TO
+  Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
+
 LEGAL_PRESERVATION
    How long do we keep data in the database for tax audits after the
    transaction has completed?  Default is 10 years.
@@ -638,6 +665,23 @@ PUBLIC_KEY
 BASE_URL
   Base URL of the auditor, e.g. “https://auditor.demo.taler.net/”
 
+SERVE
+  Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+  Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+  Access permission mask to use for the "UNIXPATH".
+  
+PORT
+   Port on which the HTTP server listens, e.g. 8080.
+
+BIND_TO
+  Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
+
+
+  
 
 AUDITOR POSTGRES BACKEND DATABASE OPTIONS
 -----------------------------------------
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 7dbd7218..68d4f9c0 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -721,32 +721,34 @@ Instance setup
 ==============
 
 First of all, we recommend the use of the single-page administration
-application that is served by default at the base URL of the merchant backend.
-You can use it to perform all steps described in this section (and more!),
-using a simple Web interface instead of the ``wget`` commands given below.
-
-The first step for using the backend involves the creation of a ``default``
-instance. The ``default`` instance can also create / delete / configure other
-instances, similar to the ``root`` account on UNIX.  When no instance exists
-and ``taler-merchant-httpd`` was started without the ``--auth`` option, then
-the backend is reachable without any access control (unless you configured
-some in the reverse proxy).
+application (SPA) that is served by default at the base URL of the merchant
+backend.  You can use it to perform all steps described in this section (and
+more!), using a simple Web interface instead of the ``wget`` commands given
+below.
+
+Regardless of which tool you use, the first step for using the backend
+involves the creation of a ``default`` instance. The ``default`` instance can
+also create / delete / configure other instances, similar to the ``root``
+account on UNIX.  When no instance exists and ``taler-merchant-httpd`` was
+started without the ``--auth`` option, then the backend is reachable without
+any access control (unless you configured some in the reverse proxy).
 
 The following documentation shows how to handle any instance. Thus, if you
 want to have multiple instances, you may need to perform the steps multiple
 times, once for each instance.
 
 .. note::
-  A security concern is that normal API usage leaks instance existence.
+
+  A potential security concern is that normal API usage leaks instance existence.
   This means unauthorized users can distinguish between the case where the
   instance does not exist (HTTP 404) and the case where access is denied
   (HTTP 403).
-  This is all moot behind a properly configured
+  This is concern can be addressed using a properly configured
   :ref:`reverse proxy <reverse-proxy-configuration>`.
 
 
-KUDOS Accounts
---------------
+Configuring Accounts
+--------------------
 
 The main configuration data that must be provided for each instance
 is the bank account information.
@@ -756,32 +758,35 @@ communicate bank account details to the exchange.
 
 The bank account information is provided in the form of a ``payto://``-URI.
 See `RFC 8905 <https://tools.ietf.org/html/rfc8905>`_
-for the format of ``payto://``-URIs.
-
-For first tests, you should sign up for a KUDOS bank
-account at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.
-In this case, the ``payto://``-URI will be of the form
-``payto://x-taler-bank/bank.demo.taler.net/$USERNAME`` where ``$USERNAME``
-must be replaced with the name of the account that was established
-at `https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.
-
+for the format of ``payto://``-URIs.  Note that the "receiver-name" is
+optional in RFC 8905 but mandatory in GNU Taler.
 
-IBAN Accounts
--------------
+For first tests, you may want to sign up for a KUDOS bank account at
+`https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_.  In this case,
+the ``payto://``-URI will be of the form
+``payto://iban/$IBAN?receiver-name=$NAME`` where ``$IBAN`` must be replaced
+with the IBAN shown on the main page of the account shown at
+`https://bank.demo.taler.net/ <https://bank.demo.taler.net/>`_ after logging
+in.
 
 When deploying Taler with the real banking system, you primarily need to
 change the currency of the configuration from KUDOS to the actual currency
-(such as EUR, USD, CHF) and provide a ``payto://``-URI of your real bank
+(such as EUR, USD, CHF) and provide a ``payto://``-URI of your actual bank
 account. In Europe, this will involve knowing your IBAN number. If you have an
-IBAN, the corresponding ``payto://``-URI is simply ``payto://iban/$IBAN`` where
-``$IBAN`` must be replaced with the actual IBAN number.
+IBAN, the corresponding ``payto://``-URI is simply
+``payto://iban/$IBAN?receiver-name=$NAME`` where ``$IBAN`` must be replaced
+with the actual IBAN number and ``$NAME`` with your actual name. Make sure
+to URI-encode your name.  The merchant SPA will do this automatically when
+you use it to configure the bank account.
 
 
-Setup
-------
+Setup without the Web interface
+-------------------------------
 
 With the knowledge of the ``payto://``-URI, instances can be configured by POSTing
-a request to ``/management/instances``.  To create a first instance,
+a request to ``/management/instances`` without using the Web interface.
+This could be useful if you want to create many instances programmatically.
+To create an instance without the Web interface
 create a file ``instance.json`` with an `InstanceConfigurationMessage`
 
 .. code-block:: json
@@ -833,11 +838,11 @@ Secure setup
 .. index:: security
 .. index:: TLS
 
-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.
+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
 -------------------------
@@ -847,8 +852,8 @@ you *should* bind the backend to a UNIX domain socket:
 
 .. code-block:: console
 
-   $ taler-config -s MERCHANT -o SERVE -V UNIX
-   $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+   $ taler-config -s MERCHANT -o SERVE -V unix
+   $ taler-config -s MERCHANT -o UNIXPATH -V "/some/path/here.sock"
 
 Do not use a UNIX domain socket path in "/tmp": systemd (or other init
 systems) may give Web servers a private "/tmp" thereby hiding UNIX domain
@@ -856,8 +861,9 @@ sockets created by other users/processes in "/tmp".
 
 If UNIX domain sockets are for some reason not possible, you *may* use a
 host-based firewall to block access to the TCP port of the merchant backend,
-but this is *not recommended*.  Relying on NAT or network firewalls for access
-control is gross negligence.
+but this is *not recommended*.  If you do need a TCP socket, you should
+instead strongly consider using the "BIND_TO" option to at least bind it only
+to "localhost".
 
 .. _reverse-proxy-configuration:
 
@@ -908,167 +914,33 @@ Note that the above again assumes your domain name is ``example.com`` and that
 you have TLS configured.  Note that you must add the ``https`` header unless
 your site is not available via TLS.
 
-The above configurations are both incomplete. You must still additionally
-set up access control!
-
 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/`` and
-``$BASE_URL/management/`` to the authorized users of the default instance, and
-to ``$BASE_URL/instances/$ID/private/`` to the authorized users of the instance
-``$ID``.
+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.
+By default, the GNU Taler merchant backend simply requires the respective
+HTTP requests to include an "Authorization" header with a "Bearer" token
+set to the respective shared secret which must begin with "secret-token:"
+(following RFC 8959).
 
-Note that all of the other endpoints (without ``/private/`` or ``/management/``)
+Note that all of the other endpoints (without ``/private/``)
 are expected to be fully exposed to the Internet, and wallets may have to
 interact with those endpoints directly without client authentication.
 
-Nginx
-^^^^^
-
-For Nginx, you can implement token-based merchant backend authentication as
-follows:
-
-.. code-block:: nginx
-
-      location ~ /private/ {
-          if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") {
-             return 401;
-          }
-          proxy_pass ...; # as above
-      }
-      location /management/ {
-          if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") {
-             return 401;
-          }
-          proxy_pass ...; # as above
-      }
-
-Here, ``SECURITYTOKEN`` should be replaced with the actual shared secret.  Note
-that the ``~`` ensures that the above matches all endpoints that include the
-string ``/private/``.  If you only run a single instance, you could simply
-specify ``/private/`` without the ``~`` to only configure the access policy for
-the default instance.
-
-If you are running different instances on the same backend, you
-likely will want to specify different access control tokens for
-each instance:
-
-.. code-block:: nginx
-
-      location ~ ^/instances/foo/private/ {
-          if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") {
-             return 401;
-          }
-          proxy_pass ...; # as above
-      }
-      location ~ ^/instances/bar/private/ {
-          if ($http_authorization !~ "(?i)ApiKey BARTOKEN") {
-             return 401;
-          }
-          proxy_pass ...; # as above
-      }
-      location /private/ {
-          if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") {
-             return 401;
-          }
-          proxy_pass ...; # as above
-      }
-      location /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
-      }
-
-Apache
-^^^^^^
-
-For Apache, you should first enable ``mod_rewrite``:
-
-.. code-block:: console
-
-   $ a2enmod rewrite
-
-Then, you can restrict to an access control token using:
-
-.. code-block:: apacheconf
-
-       <Location "/">
-       RewriteEngine On
-       RewriteCond "%{HTTP:AUTHORIZATION}" "!=SECURITYTOKEN"
-       RewriteRule "(.+)/private/" "-" [F]
-       RewriteRule "/management/" "-" [F]
-
-       ProxyPass "unix:/some/path/here.sock|http://example.com/"
-       </Location>
-
-Here, ``SECURITYTOKEN`` should be replaced with the actual shared secret.  Note
-that the ``(.+)`` ensures that the above matches all endpoints that include the
-string ``/private/``.  If you only run a single instance, you could simply
-specify ``/private/`` without the ``(.+)`` to only configure the access policy for
-the default instance.
-
-If you are running different instances on the same backend, you
-likely will want to specify different access control tokens for
-each instance:
-
-.. code-block:: apacheconf
-
-       <Location "/instances/foo/">
-       RewriteEngine On
-       RewriteCond "%{HTTP:AUTHORIZATION}" "!=FOOTOKEN"
-       RewriteRule "/instances/foo/private/" "-" [F]
-
-       ProxyPass ... # as above
-       </Location>
-
-       <Location "/instances/bar/">
-       RewriteEngine On
-       RewriteCond "%{HTTP:AUTHORIZATION}" "!=BARTOKEN"
-       RewriteRule "/instances/bar/private/" "-" [F]
-
-       ProxyPass ... # as above
-       </Location>
-
-       <Location "/">
-       RewriteEngine On
-       RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN"
-       RewriteRule "/private/" "-" [F]
-       RewriteRule "/management/" "-" [F]
-       RewriteRule "(.+)/private/" "-" [F] # reject all others
-
-       ProxyPass ... # as above
-       </Location>
-
-Please note that these are simply examples of how one could use Nginx or
-Apache2 for access control. Both HTTP servers support many other forms of
-authentication, including TLS client certificates, HTTP basic and digest
-authentication and others, which can all be used (possibly in combination) to
-restrict access to the internal API to authorized clients.
-
-System administrators are strongly advised to test their access control
-setup before going into production!
 
 Status code remapping
 ---------------------
 
-Normal API usage leaks instance existence information.
-Distinguishing between 404 (Not found) and 403 (Forbidden)
-is useful for diagnostics.
+Normal API usage leaks instance existence information.  Distinguishing between
+404 (Not found) and 403 (Forbidden) is useful for diagnostics.
 
-For higher security (by leaking less information),
-you can add the following fragment,
-which remaps all 404 response codes to 403.
+For higher security (by leaking less information), you can add the following
+fragment, which remaps all 404 response codes to 403.
 
 Nginx
 ^^^^^