summaryrefslogtreecommitdiff
path: root/taler-auditor-manual.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-07-12 10:50:14 +0200
committerChristian Grothoff <christian@grothoff.org>2020-07-12 10:50:14 +0200
commit746bdde0f88925ce38dd490ab13f2c7e0c8e15fd (patch)
tree01a3ac99abbe1486e5025342c522d956abc3d1b7 /taler-auditor-manual.rst
parentd7b03164470739c9a9d246bf02b2ca4f8368467e (diff)
downloaddocs-746bdde0f88925ce38dd490ab13f2c7e0c8e15fd.tar.gz
docs-746bdde0f88925ce38dd490ab13f2c7e0c8e15fd.tar.bz2
docs-746bdde0f88925ce38dd490ab13f2c7e0c8e15fd.zip
import lists of invariant checks from CodeBlau report as basis
Diffstat (limited to 'taler-auditor-manual.rst')
-rw-r--r--taler-auditor-manual.rst270
1 files changed, 259 insertions, 11 deletions
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index ec6eba2..bff9691 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -482,20 +482,54 @@ interactions with the bank (which may not even have the wire transfer records
anymore), this is not recommended in a production setup.
+Reading the report
+------------------
+
+The auditor's report needs to be read carefully, as it includes
+several categories of failures of different severity:
+
+ - Delayed operations, where an operation was expected to have
+ happened, but did not happen yet, possibly because of a
+ disagreement in system time or overloading of the system.
+ These failures only require action if the delays are
+ significant.
+
+ - Inconsistencies in the data that have no clear financial
+ impact.
+
+ - Inconsistencies in the data that show that the exchange
+ made an unexpected loss (such as accepting a coin for
+ deposit with an invalid signature).
+
+ - Inconsistencies in the data that show that the exchange
+ caused some other party to make a loss (such as not wiring
+ the correct amount to a merchant).
+
+ - Configuration issues (such was wire fees unavailable)
+
.. _Database-upgrades:
Database upgrades
-----------------
-Currently, there is no way to upgrade the database between Taler
-versions.
+To upgrade the database between Taler versions can be done by
+running:
+
+::
+
+ $ taler-auditor-dbinit
+
+However, the above is the general rule. Please review the
+specific release notes to ensure this is correct for the
+specific upgrade.
+
The auditor database can be re-initialized using:
::
- $ taler-auditor-dbinit -R
+ $ taler-auditor-dbinit -r
However, running this command will result in all data in the database being
lost, which may result in significant commputation (and bandwidth consumption
@@ -504,8 +538,6 @@ historic transactions. Hence this should not be done in a production system.
-
-
.. _Revocations:
Revocations
@@ -557,6 +589,228 @@ The database scheme used by the exchange look as follows:
.. image:: auditor-db.png
+Invariants checked by the auditor
+---------------------------------
+
+The auditor verifies a large number of invariants that must hold for a Taler
+exchange. One objective in the design of the auditor was to check each
+invariant only once, both to minimize cost and to avoid duplicate reporting of
+problems where possible. As a result, not every invariant is checked in every
+pass where it might seem applicable.
+
+
+
+Invariants checked by the taler-helper-auditor-aggregation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is from CodeBlau's analysis. A proper write-up is pending.
+CodeBlau reports the following checks:
+
+ - arithmetic inconsistencies
+
+ - disagreement in fee for deposit between auditor and exchange db
+
+ - disagreement in fee for melt between auditor and exchange db
+
+ - disagreement in fee for refund between auditor and exchange db
+
+ - aggregation of fee is negative
+
+ - aggregation (contribution): Expected coin contributions differ:
+ coin value without fee, total deposit without refunds
+
+ - wire out fee is negative
+
+ - coin arithmetic inconsistencies
+
+ - refund (merchant) is negative
+
+ - refund (balance) is negative
+
+ - spend > value
+
+ - coin denomination signature invalid
+
+ - start date before previous end date
+
+ - end date after next start date
+
+ - wire out inconsistencies in amount
+
+ - row inconsistencies
+
+ - wire account given is malformed
+
+ - h(wire) does not match wire
+
+ - failed to compute hash of given wire data
+
+ - database contains wrong hash code for wire details
+
+ - no transaction history for coin claimed in aggregation
+
+ - could not get coin details for coin claimed in aggregation
+
+ - could not find denomination key for coin claimed in aggregation
+
+ - coin denomination signature invalid
+
+ - target of outgoing wire transfer do not match hash of wire from deposit
+
+ - date given in aggregate does not match wire transfer date
+
+ - wire fee signature invalid at given time
+
+ - specified wire address lacks method
+
+ - wire fee unavailable for given time
+
+
+Invariants checked by the taler-helper-auditor-coins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is from CodeBlau's analysis. A proper write-up is pending.
+CodeBlau reports the following checks:
+
+ - emergency on denomination over loss
+
+ - value of coins deposited exceed value of coins issued
+
+ - emergency on number of coins, num mismatch
+
+ - arithmetic inconsistencies
+
+ - melt contribution vs. fee
+
+ - melt (cost)
+
+ - refund fee
+
+ - row inconsistencies
+
+ - revocation signature invalid
+
+ - denomination key not found
+
+ - denomination key for fresh coin unknown to auditor
+
+ - denomination key for dirty coin unknown to auditor
+
+ - denomination key for deposited coin unknown to auditor
+
+ - coin validity in known_coin, by checking denomination signatures
+
+ - coin validity in melt, by checking signatures
+
+ - refresh hanging, zero reveals (harmless)
+
+ - verify deposit signature
+
+ - verify refund signature
+
+ - recoup, check coin
+
+ - recoup, check signature
+
+ - recoup, denomination not revoked
+
+
+
+Invariants checked by the taler-helper-auditor-deposits
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This tool verifies that the deposit confirmations reported by
+merchants directly to the auditor are also included in the
+database we got from the exchange. This is to ensure that
+the exchange cannot defraud merchants by simply not reporting
+deposits to the auditor.
+
+
+
+Invariants checked by the taler-helper-auditor-reserves
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is from CodeBlau's analysis. A proper write-up is pending.
+CodeBlau reports the following checks:
+
+ - report arithmetic inconsistency
+
+ - closing aggregation fee
+
+ - global escrow balance
+
+ - denomination key validity withdraw inconsistencies
+
+ - bad signature losses in withdraw
+
+ - bad signature losses in recoup
+
+ - bad signature losses in recoup-master
+
+ - reserve balance, insufficient, losses and gains
+
+ - reserve balance, summary wrong
+
+ - reserve not closed after expiration time
+
+ - could not determine closing fee / closing-fee unavailable
+
+ - denomination key not found for withdraw
+
+ - denomination key not in revocation set for recoup
+
+ - target account not verified, auditor does not know reserve
+
+ - target account does not match origin account
+
+
+Invariants checked by the taler-helper-auditor-wire
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This auditor is special in that it is the only pass that is required to have
+*read-only* access to the exchange's bank account (privilege separation). Its
+main role is to verify that the wire transfers in the exchange's database and
+those reported by the bank are identical.
+
+This is from CodeBlau's analysis. A proper write-up is pending.
+CodeBlau reports the following checks:
+
+ - check pending
+
+ - wire missing
+
+ - execution date mismatch
+
+ - wire out consistency
+
+ - wire transfer not made (yet?)
+
+ - receiver account mismatch
+
+ - wire amount does not match
+
+ - justification for wire transfer not found
+
+ - duplicate subject hash
+
+ - duplicate wire offset
+
+ - incoming wire transfer claimed by exchange not found
+
+ - wire subject does not match
+
+ - wire amount does not match
+
+ - debit account url does not match
+
+ - execution date mismatch
+
+ - closing fee above total amount
+
+
+
+
+
Testing the auditor
-------------------
@@ -575,12 +829,6 @@ cover as many code paths as possible in both the exchange and the auditor. It
should also ideally create all interesting possible variations of the exchange
database fields (within the constraints of the database schema).
-.. TODO
-
- The current code coverage is known to be inadequate,
- as refunds and recoups could not yet been tested due
- to limitations of the CLI wallet.
-
In general, test-auditor.sh runs the tests against an "old" database where
some transactions are past the due-date (and hence the aggregator would trigger
wire transfers), as well as a freshly generated exchange database where the