diff options
Diffstat (limited to 'taler-auditor-manual.rst')
| -rw-r--r-- | taler-auditor-manual.rst | 106 |
1 files changed, 63 insertions, 43 deletions
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index 58dc9463..94e86a8d 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -17,8 +17,13 @@ @author Christian Grothoff -GNU Taler Auditor Operator Manual -################################# +Auditor Operator Manual +####################### + +.. contents:: Table of Contents + :depth: 1 + :local: + Introduction ============ @@ -29,14 +34,7 @@ to become readable. About GNU Taler --------------- -GNU Taler is an open protocol for an electronic payment system with a -free software reference implementation. GNU Taler offers secure, fast -and easy payment processing using well understood cryptographic -techniques. GNU Taler allows customers to remain anonymous, while -ensuring that merchants can be held accountable by governments. Hence, -GNU Taler is compatible with anti-money-laundering (AML) and -know-your-customer (KYC) regulation, as well as data protection -regulation (such as GDPR). +.. include:: frags/about-taler.rst About this manual @@ -65,7 +63,7 @@ all, the goal is to detect nerfarious activity of the exchange operator, which cannot be effectively done on a machine controlled by the exchange operator. -For this, every auditor needs to operate a Postgres database. The data +For this, every auditor needs to operate a PostgreSQL database. The data collected will include sensitive information about Taler users, including withdrawals made by consumers and income received by merchants. As a result, the auditor is expected to provide high confidentiality for the database. In @@ -118,7 +116,7 @@ third parties to verify one's own work. The Taler software stack for an auditor consists of the following components: -- DBMS: Postgres +- DBMS: PostgreSQL The auditor requires a DBMS to store a local copy of the transaction history for the Taler exchange, as well as for its own internal bookkeeping and checkpointing. @@ -128,7 +126,7 @@ components: concern that must be addressed manually. The software only verifies the content of a well-formed exchange database (well-formed with respect to SQL). For now, the GNU Taler reference implementation - only supports Postgres, but the code could be easily extended to + only supports PostgreSQL, but the code could be easily extended to support another DBMS. - The auditor Web service @@ -183,6 +181,8 @@ Installing from source Please install the following packages before proceeding with the exchange compilation. +- Python3 module ``jinja2`` + .. include:: frags/list-of-dependencies.rst - GNU Taler exchange (from `download directory <http://ftpmirror.gnu.org/taler/>`__, @@ -199,6 +199,8 @@ the exchange (which includes the code for the auditor). .. include:: frags/installing-taler-exchange.rst +.. include:: frags/install-before-check.rst + Installing the GNU Taler binary packages on Debian -------------------------------------------------- @@ -264,7 +266,7 @@ 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 + * postgres --- runs the PostgreSQL database Databases and users @@ -312,9 +314,6 @@ This section discusses configuration options related to the auditor. .. include:: frags/configuration-format.rst -.. include:: frags/using-taler-config.rst - - .. _SetupBaseUrl: Initial configuration @@ -323,10 +322,11 @@ Initial configuration You need to tell the Taler auditor configuration where the REST API of the auditor will be available to the public: -.. code-block:: console +.. code-block:: ini # Both for the 'offline' *and* the 'auditor' user: - $ taler-config -s auditor -o BASE_URL -V https://auditor.example.com/ + [auditor] + BASE_URL = https://auditor.example.com/ The ``helper`` user that is used to download information from the exchange needs to know details about the exchange. Similarly, the ``offline`` user @@ -335,11 +335,12 @@ 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 and configure these: -.. code-block:: console +.. code-block:: ini # As the 'helper' and 'offline' users: - $ taler-config -s exchange -o BASE_URL -V https://exchange.example.com/ - $ taler-config -s exchange -o MASTER_PUBLIC_KEY -V $SOMELONGBASE32VALUEHERE + [exchange] + BASE_URL = https://exchange.example.com/ + MASTER_PUBLIC_KEY = $SOMELONGBASE32VALUEHERE .. _AuditorKeys: @@ -375,10 +376,11 @@ of the ``auditor`` user in the ``[auditor]]`` configuration section: You can set this configuration value using: -.. code-block:: console +.. code-block:: ini # As the 'auditor' and 'helper' users: - $ taler-config -s auditor -o PUBLIC_KEY -V $SOMELONGBASE32VALUEHERE + [auditor] + PUBLIC_KEY = $SOMELONGBASE32VALUEHERE .. _AuditorServing: @@ -460,6 +462,12 @@ used when configuring the exchange' database: CONFIG = postgres:///exchangedemo +Legal conditions for using the service +-------------------------------------- + +.. include:: frags/legal.rst + + .. _AuditorDeployment: Deployment @@ -579,9 +587,9 @@ The next key step for the auditor is to configure replication of the *exchange*'s database in-house. This should be performed in two steps as illustrated in the following figure: -.. image:: replication.png +.. image:: images/replication.png -First, the exchange should use standard Postgres replication features to +First, the exchange should use standard PostgreSQL replication features to enable the auditor to obtain a full copy of the exchange's database. Second, the auditor should make a "trusted" local copy, ensuring that it never replicates malicious changes using ``taler-auditor-sync``. Both @@ -591,7 +599,7 @@ We note that as a result of these steps, the auditor will have three databases: its own production primary database (as configured in ``auditordb-postgres``), its on production copy of the exchange's database (``exchangedb-postgress``), and a third, untrusted "ingres" copy of the -exchange database. The untrusted database should run as a separate Postgres +exchange database. The untrusted database should run as a separate PostgreSQL instance and is only accessed via ``taler-auditor-sync`` and the replication mechanism driven by the exchange operator. @@ -603,7 +611,7 @@ 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 +The full copy can be obtained in various ways with PostgreSQL. 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 logical replication, as described in @@ -612,7 +620,7 @@ that asynchronous replication should suffice. The resulting auditor database should be treated as read-only on the auditor side. The ``taler-exchange-dbinit`` tool can be used to setup the schema, or -the schema can be replicated using Postgres's standard mechanisms. The same +the schema can be replicated using PostgreSQL's standard mechanisms. The same applies for schema upgrades: if logical replication is used (which does not replicate schema changes), ``taler-exchange-dbinit`` can be used to migrate the schema(s) in both the ingres and production copies of the exchange's @@ -629,14 +637,14 @@ to perform database replication. This is done using: $ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange The exchange must share the password of the publication with the auditor. A -good ``$NAME`` relates to the auditor's buisness unit name. A secure tunnel +good ``$NAME`` relates to the auditor's business unit name. A secure tunnel must be setup between the exchange and the auditor, for example using SSH or Wireguard. It is also necessary to edit ``main.cf`` of the exchange and on the auditor side to enable logical replication. If an exchange has multiple auditors, it should setup multiple ``egress`` accounts. The exchange must ensure that -the following lines are in the ``main.cf`` Postgres configuaration (the port +the following lines are in the ``main.cf`` PostgreSQL configuration (the port may differ) to enable replication over the network: .. code-block:: @@ -646,7 +654,7 @@ may differ) to enable replication over the network: wal_level= logical Equally, the auditor must configure logical replication in the ``main.cf`` -Postgres configuaration: +PostgreSQL configuration: .. code-block:: @@ -655,11 +663,17 @@ Postgres configuaration: Next, the ``postgres`` user of the auditor's system must first initialize the local tables: +.. code-block:: ini + + # Configure database: + [exchange] + DB = "postgres" + [exchangedb-postgres] + CONFIG = "postgres:///taler-ingress" + .. code-block:: console # As the 'ingress' user of the exchange: - $ taler-config -s exchange -o DB -V "postgres" - $ taler-config -s exchangedb-postgres -o CONFIG -V "postgres:///taler-ingress" $ taler-exchange-dbinit To complete the replication, the ``postgres`` user of the auditor's @@ -673,7 +687,7 @@ system must subscribe: $ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange -For details, we refer to the Postgres manual. +For details, we refer to the PostgreSQL manual. .. note:: @@ -682,9 +696,9 @@ For details, we refer to the Postgres manual. ``DROP`` operations on the tables. Hence, the auditor cannot rely upon the exchange's primary copy to respect schema constraints, especially as we have to presume that the exchange could act maliciously. Furthermore, it - is unclear to what degree Postgres database replication mechanisms are + is unclear to what degree PostgreSQL database replication mechanisms are robust against a malicious master database. Thus, the auditor should - isolate its primary copy of the exchange database, including the Postgres + isolate its primary copy of the exchange database, including the PostgreSQL process, from its actual operational data. @@ -704,7 +718,7 @@ 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 latency from the network between auditor and exchange operator. Thus, we recommend first making an "untrusted" ingress copy of the exchange's -production database using standard Postgres tooling, and then using +production database using standard PostgreSQL tooling, and then using ``taler-auditor-sync`` to create a second "safe" copy. The "safe" copy used by the production system should also run under a different UID. @@ -719,11 +733,17 @@ needs to be changed. To run ``taler-auditor-sync``, you must first configure two configuration files that identify the source and destination databases: -.. code-block:: console +.. code-block:: ini - # As the 'sync' user: - $ taler-config -c src.conf -s exchangedb -o CONFIG -V "postgres:///auditor-ingres/" - $ taler-config -c dst.conf -s exchangedb -o CONFIG -V "postgres:///auditor/" + # src.conf + [exchangedb] + CONFIG = "postgres:///auditor-ingres/" + +.. code-block:: ini + + # dst.conf + [exchangedb] + CONFIG = "postgres:///auditor/" Now you should be able to launch the synchronization process. You can run the process via systemd in the background. For a first one-off test, you should @@ -965,7 +985,7 @@ The auditor's database The database scheme used by the exchange looks as follows: -.. image:: auditor-db.png +.. image:: images/auditor-db.png Invariants checked by the auditor |