summaryrefslogtreecommitdiff
path: root/taler-auditor-manual.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-07-12 10:51:45 +0200
committerChristian Grothoff <christian@grothoff.org>2020-07-12 10:51:45 +0200
commit5b41c8882c6cc7a531566c4160165c497deef829 (patch)
tree661a7cb83c133d08253b07a6b313be2853eec36f /taler-auditor-manual.rst
parent746bdde0f88925ce38dd490ab13f2c7e0c8e15fd (diff)
parent6036cea5f598620ac4b6e9553d84bef2aa93ad7c (diff)
downloaddocs-5b41c8882c6cc7a531566c4160165c497deef829.tar.gz
docs-5b41c8882c6cc7a531566c4160165c497deef829.tar.bz2
docs-5b41c8882c6cc7a531566c4160165c497deef829.zip
merge
Diffstat (limited to 'taler-auditor-manual.rst')
-rw-r--r--taler-auditor-manual.rst60
1 files changed, 47 insertions, 13 deletions
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index bff9691..1d84d45 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -59,7 +59,11 @@ to other parties.
To perform this duty, you will need at least (read-only) access to the bank
transactions of the exchange, as well as a continuously synchronized replica
-of the exchange's database.
+of the exchange's database. The general assumption for running the auditor
+is that this is done on a separate system controlled by the auditor. After
+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
collected will include sensitive information about Taler users, including
@@ -259,7 +263,7 @@ Taler components. See for example the exchange manual for details on the
configuration and the ``taler-config`` configuration tool. This section
discusses configuration options related to the auditor.
-.. _Keys:
+.. _AuditorKeys:
Keys
----
@@ -271,7 +275,7 @@ The following values are to be configured in the section [auditor]:
- AUDITOR_PRIV_FILE: Path to the auditor’s private key file.
-.. _Serving:
+.. _AuditorServing:
Serving
-------
@@ -292,7 +296,7 @@ The following values are to be configured in the section [auditor]:
for the unixpath (i.e. 660 = rw-rw—-).
-.. _Bank-account:
+.. _AuditorBank-account:
Bank account
------------
@@ -301,7 +305,7 @@ Bank accounts for the auditor are configured in exactly the
same way as bank accounts for the exchange. See the exchange
documentation for details.
-.. _Database:
+.. _AuditorDatabaseConfiguration:
Database
--------
@@ -334,7 +338,7 @@ tables. After running this tool, the rights to CREATE or DROP tables
are no longer required and should be removed.
-.. _Deployment:
+.. _AuditorDeployment:
Deployment
==========
@@ -352,7 +356,7 @@ Web page offering the respective pairing.
FIXME: explain how that Web page works!
-.. _Exchange:
+.. _AuditorExchange:
Exchange
--------
@@ -371,7 +375,7 @@ master public key.
taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL
-.. _Denominations:
+.. _AuditorDenominations:
Denominations
-------------
@@ -413,7 +417,7 @@ response will contain an entry in the ``auditors`` array mentioning the
auditor’s URL.
-.. _Database:
+.. _AuditorDatabaseInitialization:
Database
--------
@@ -460,7 +464,7 @@ Audit
Performing an audit is done by invoking the ``taler-auditor`` and
``taler-wire-auditor`` tools respectively. Both tools generate JSON
-files, which can then be combined using the ``contrib/render.py''
+files, which can then be combined using the ``contrib/render.py``
script into the TeX report.
::
@@ -508,7 +512,7 @@ several categories of failures of different severity:
- Configuration issues (such was wire fees unavailable)
-.. _Database-upgrades:
+.. _AuditorDatabaseUpgrades:
Database upgrades
-----------------
@@ -538,10 +542,10 @@ historic transactions. Hence this should not be done in a production system.
-.. _Revocations:
+.. _AuditorRevocations:
Revocations
-~~~~~~~~~~~
+-----------
When an auditor detects that the private key of a denomination key pair has
been compromised, one important step is to revoke the denomination key. The
@@ -556,6 +560,36 @@ additional information to demonstrate that these coins were not forged from
the compromised private key but obtained via a legitimate withdraw operation.
+Failures
+--------
+
+Most audit failures are handled by the auditor's regular reporting functionality,
+creating a (hopefully descriptive) PDF report detailing the problems found.
+
+However, there is one category of errors where this is not possible, which evolves
+around arithmetic overflows for amounts. Taler's specification limits amount
+values to at most 2^52. If, during the auditor's calculations, amounts are
+encountered that exceed this threshold, the auditor will not generate a regular
+report, but instead write a log statement explaining where the problem happened
+and exit with a status code of *42*.
+
+The most common expected case when this happens is a corrupted database. This
+could be because the exchange is actively malicious, or more likely due to
+some data corruption. The audit cannot continue until the corruption has been
+addressed. If it is not possible to restore a fully 'correct' version of the
+database, the suggestion is to replace the corrupted (and likely very large)
+amounts with zero (Note: this does not apply to the value of denominations or
+fees, here it is crucial that the correct amounts are restored). While an
+amount of zero would be incorrect, the auditing logic should be able to do its
+calculations with zero instead. After patching the database, the audit can
+be restarted. A full reset is not required, as the audit transaction is aborted
+when the auditor exits with code *42*. After restarting, the resulting audit
+report is likely to indicates errors relating to the corrupted fields (such as
+invalid signatures, arithmetic errors by the exchange, etc.), but at least the
+loss/gain calculations will be meaningful and actually indicative of the scope
+of the error created by the corrupted data.
+
+
Auditor implementation guide
============================