merge

1 files changed, 47 insertions, 13 deletions

diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index bff96916..1d84d45d 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
 ============================