summaryrefslogtreecommitdiff
path: root/taler-auditor-manual.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-04-09 11:46:36 +0200
committerChristian Grothoff <christian@grothoff.org>2020-04-09 11:46:36 +0200
commit822136314dce1c663a403bca04f6a027f7812dc8 (patch)
treef1aa3c204ab405e7d145daaf7629ce69df412add /taler-auditor-manual.rst
parent7892936cb1a125832c48de10fa288df8592432f3 (diff)
downloaddocs-822136314dce1c663a403bca04f6a027f7812dc8.tar.gz
docs-822136314dce1c663a403bca04f6a027f7812dc8.tar.bz2
docs-822136314dce1c663a403bca04f6a027f7812dc8.zip
document auditor failure mode related to #6164
Diffstat (limited to 'taler-auditor-manual.rst')
-rw-r--r--taler-auditor-manual.rst32
1 files changed, 31 insertions, 1 deletions
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index ec6eba2..82b206e 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -509,7 +509,7 @@ historic transactions. Hence this should not be done in a production system.
.. _Revocations:
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
@@ -524,6 +524,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
============================