update auditor manual

1 files changed, 152 insertions, 38 deletions

diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index c6d73c0e..d12a63c7 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -235,6 +235,71 @@ the HTTP reverse proxy (typically with TLS certificates) and offline signing.
 Sample configuration files for the HTTP reverse proxy can be found in
 ``/etc/taler-auditor/``.
 
+System setup
+============
+
+UNIX accounts
+-------------
+
+For maximum security, you should setup multiple different users (possibly
+on different machines) to run Taler auditor components. While it is possible
+to skip some of these entirely, or to run all of them as the same user, this
+is not recommended for security.  The recommended set of users includes:
+
+  * auditor --- runs the main auditing process and HTTP backend
+  * sync --- synchronizes the ingres database with the production database
+  * helper --- runs taler-auditor-offline download and upload commands
+  * auditor-ingres --- imports database from exchange production system
+  * auditor-wire --- imports wire transfer data from bank production system
+  * offline --- manages the offline key, on a separate *offline* machine
+
+It is suggested that you setup the first five users on the target system(s)
+using:
+
+.. code-block:: console
+
+   # add-user --disabled-password $USERNAME
+
+Additionally, there are two canonical system users of relevance (which your
+distribution would typically create for you):
+
+  * www-data --- runs the HTTPS frontend (usually nginx or Apache)
+  * postgres --- runs the Postgres database
+
+
+Databases and users
+-------------------
+
+We recommend using the following databases for the auditor:
+
+  * exchange-ingres --- synchronized exchange database over the network
+  * exchange-production --- local copy of exchange database with trusted schema
+  * auditor --- auditor production database with current state of the audit
+  * libeufin --- local state of the auditor-wire tool for the bank transfer data import
+
+As the *postgres* user, you can create these databases using:
+
+.. code-block:: console
+
+   # As the ``postgres`` user:
+   $ createdb -O auditor-ingres exchange-ingres
+   $ createdb -O sync exchange-production
+   $ createdb -O auditor auditor
+   $ createdb -O auditor-wire libeufin
+
+This will ensure that the correct users have write-access to their
+respective database.  Next, you need to grant read-only access to
+some users to databases owned by other users:
+
+.. code-block:: console
+
+   # As the ``auditor-ingres`` user:
+   $ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO sync;' | psql exchange-ingres
+   # As the ``sync`` user:
+   $ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql exchange-production
+   # As the ``auditor-wire`` user:
+   $ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql libeufin
+
 
 Configuration
 =============
@@ -260,7 +325,19 @@ REST API of the auditor will be available to the public:
 
 .. code-block:: console
 
-   # taler-config -s auditor -o BASE_URL -V https://auditor.example.com/
+   # Both for the 'offline' *and* the 'auditor' user:
+   $ taler-config -s auditor -o BASE_URL -V https://auditor.example.com/
+
+The ``helper'' user that is used to download information from the exchange
+needs to know details about the exchange. Here, you need to obtain the
+``MASTER_PUBLIC_KEY`` from the exchange operator (they need to run
+`taler-exchange-offline setup`) and the REST endpoint of the exchange:
+
+.. code-block:: console
+
+   # As the ``helper`` user:
+   $ taler-config -s exchange -o BASE_URL -V https://exchange.example.com/
+   $ taler-config -s exchange -o MASTER_PUBLIC_KEY -V SOMELONGBASE32VALUEHERE
 
 
 .. _AuditorKeys:
@@ -279,14 +356,33 @@ The following values are to be configured in the section ``[auditor]``:
 
 -  ``AUDITOR_PRIV_FILE``: Path to the auditor’s private key file.
 
--  ``PUBLIC_KEY``: Public key of the auditor, in Base32 encoding.
+Note that the default value here should be fine and there is no clear
+need to change it.  What you do need to do as the ``offine`` user
+is to extract the public key:
+
+.. code-block:: console
+
+   # As the ``offline`` user:
+   $ taler-auditor-offline setup
+
+This public key must then be provided in the configuration file
+of the ``auditor`` user in the ``[auditor]]`` configuration section:
+
+-   ``PUBLIC_KEY``: Public key of the auditor, in Base32 encoding.
    Set from value printed by ``taler-auditor-offline setup``.
 
+You can set this configuration value using:
+
+.. code-block:: console
+
+   # As the ``auditor`` user:
+   $ taler-config -s auditor -o MASTER_PUBLIC_KEY -V SOMELONGBASE32VALUEHERE
+
 
 .. _AuditorServing:
 
-Serving
--------
+Configuring the auditor's REST endpoint
+---------------------------------------
 
 The auditor can serve HTTP over both TCP and UNIX domain socket.
 
@@ -309,9 +405,9 @@ The following values are to be configured in the section ``[auditor]``:
 Bank account
 ------------
 
-Bank accounts for the auditor are configured in exactly the
-same way as bank accounts for the exchange. See the exchange
-documentation for details.
+Bank accounts for the auditor (user ``auditor-wire``) are configured in
+exactly the same way as bank accounts for the exchange. See the exchange (and
+LibEuFin) documentation for details.
 
 .. _AuditorDatabaseConfiguration:
 
@@ -369,10 +465,11 @@ Deployment
 
 .. _Wallets:
 
-Before GNU Taler wallets will happily interact with an exchange,
-the respective auditor's public key (to be obtained via ``taler-auditor-offline setup``)
-must be added under the respective currency to the wallet.  This
-is usually expected to be hard-coded into the Taler wallet.
+Before GNU Taler wallets will happily interact with an exchange, the
+respective auditor's public key (as obtained via ``taler-auditor-offline
+setup`` from the ``offline`` user) must be added under the respective currency
+to the wallet.  This is usually expected to be hard-coded into the Taler
+wallet.
 
 Users can also manually add auditors for a particular currency via a
 Web page offering the respective pairing.
@@ -386,24 +483,25 @@ FIXME-DOLD: explain how that Web page works, once it works...
 Exchange
 --------
 
-The next step is to add the exchange's master public key and the base
-URL of the exchange to the list of exchanges audited by the auditor.
-This is done using the ``taler-auditor-exchange`` tool.  The tool
-basically creates the respective record in the auditor's database.
+The next step is to add the exchange's master public key and the base URL of
+the exchange to the list of exchanges audited by the auditor.  This is done
+using the ``taler-auditor-exchange`` tool.  The tool basically creates the
+respective record in the auditor's database.
 
-If this step is skipped, the auditor will malfunction at all future
-stages with a foreign key violation, as it doesn't know the exchange's
-master public key.
+If this step is skipped, the auditor will malfunction at all future stages
+with a foreign key violation, as it does not know the exchange's master public
+key.
 
 .. code-block:: console
 
-   $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL
+  # As the ``auditor'' user:
+  $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL
 
-The equivalent step must be performed by the exchange operator.
-Here, the exchange operator must use the ``taler-exchange-offline``
-tool to add the auditor's public key, base URL and (business) name
-to the list of approved auditors of the exchange. For details,
-see :ref:`Auditor-configuration` in the exchange operator manual.
+An equivalent step must be performed by the exchange operator.  Here, the
+exchange operator must use the ``taler-exchange-offline`` tool to add the
+auditor's public key, base URL and (business) name to the list of approved
+auditors of the exchange. For details, see :ref:`Auditor-configuration` in the
+exchange operator manual.
 
 
 .. _SigningDenominations:
@@ -413,20 +511,22 @@ Signing Denominations
 
 .. index:: maintenance
 
-This step must be performed regularly whenever the exchange is
+These steps must be performed *regularly* whenever the exchange is
 deploying new denomination keys. After the exchange operator
 has signed new keys using the ``taler-exchange-offline`` tool,
 each auditor should run:
 
 .. code-block:: console
 
+   # As the ``helper`` user:
    $ taler-auditor-offline download > input.json
 
-to import the latest set of denomination keys. The key data
-should then be inspected using:
+to import the latest set of denomination keys. The key data should then be
+copied to the offline system and there be inspected using:
 
 .. code-block:: console
 
+   # As the ``offline`` user:
    $ taler-auditor-offline show < input.json
 
 and compared with the data the exchange operator saw when doing the offline
@@ -446,6 +546,7 @@ on its offline system) using:
 
 .. code-block:: console
 
+   # As the ``offline`` user:
    $ taler-auditor-offline sign < input.json > output.json
 
 The resulting ``output.json`` should then be copied to an online system,
@@ -453,6 +554,7 @@ and from there uploaded to the exchange using:
 
 .. code-block:: console
 
+   # As the ``helper`` user:
    $ taler-auditor-offline upload < output.json
 
 The contents of ``output.json`` can again be public and require no special
@@ -495,6 +597,10 @@ mechanism driven by the exchange operator.
 Ingres replication of the exchange production database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Ingres operation should be done using the ``auditor-ingres`` user --- or
+depending on the setup parts of the operation may be done by the ``postgres``
+user directly.
+
 The full copy can be obtained in various ways with Postgres.  It is
 possible to use log shipping with streaming replication as described
 in https://www.postgresql.org/docs/13/warm-standby.html, or to use
@@ -528,13 +634,14 @@ For details, we refer to the Postgres manual.
 Safe replication of the ingres database into the auditor production database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Using ``taler-auditor-sync``, the auditor should make a second "safe" copy of
-the exchange's ingres database.  ``taler-auditor-sync`` basically reads from one
-exchange database and inserts all records found into a second exchange
-database. If the source database violates invariants, the tool halts with an
-error. This way, records violating invariants are never even copied, and in
-particular schema changes and deletions or updates are not propagated into the
-auditor's production database.
+Using ``taler-auditor-sync`` as the ``sync`` user, the auditor should
+make a second "safe" copy of the exchange's ingres database.
+``taler-auditor-sync`` basically reads from one exchange database and inserts
+all records found into a second exchange database. If the source database
+violates invariants, the tool halts with an error. This way, records violating
+invariants are never even copied, and in particular schema changes and
+deletions or updates are not propagated into the auditor's production
+database.
 
 While ``taler-auditor-sync`` could in theory be run directly against the
 exchange's production system, this is likely a bad idea due to the high
@@ -577,6 +684,10 @@ service must have ``INSERT`` (and ``SELECT``) rights on the
 ``deposit_confirmations`` table in the auditor's database.  We expect that in
 future versions additional rights may be required.
 
+For now, we recommend simply running the ``taler-auditor-httpd`` under the
+``auditor`` user. However, it is also possible (and might be more secure) to
+create a separate user with more restrictive permissions for this purpose.
+
 As the ``taler-auditor-httpd`` does not include HTTPS-support, it is
 advisable to run it behind a reverse proxy that offers TLS termination.
 
@@ -586,14 +697,17 @@ advisable to run it behind a reverse proxy that offers TLS termination.
 Audit
 -----
 
-Performing an audit is done by invoking the ``taler-auditor`` shell script.
+Performing an audit is done by invoking the ``taler-auditor`` shell script as
+the ``auditor`` user.
+
 The shell script invokes the various helper processes. For additional
 performance and security, one may want to run the various helpers individually
 and with the respective minimal set of access rights (only
 ``taler-helper-auditor-wire`` needs the credentials to query the bank for wire
-transfers).  The shell script combines the final JSON outputs of the various
-helpers using the ``taler-helper-auditor-render.py`` script into the TeX
-report.  Regardless, the simplest way to obtain a report is to run:
+transfers, alas if ``auditor-wire`` is used to talk to the bank, this issue is
+already addressed).  The shell script combines the final JSON outputs of the
+various helpers using the ``taler-helper-auditor-render.py`` script into the
+TeX report.  Regardless, the simplest way to obtain a report is to run:
 
 .. code-block:: console