diff options
| -rw-r--r-- | taler-auditor-manual.rst | 123 |
1 files changed, 83 insertions, 40 deletions
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst index 74e4ebfd..3bab780f 100644 --- a/taler-auditor-manual.rst +++ b/taler-auditor-manual.rst @@ -217,12 +217,20 @@ Keys ---- The auditor works with one signing key to certify that it is auditing -a particular exchange's denomination keys. +a particular exchange's denomination keys. This key can and should +be kept *offline* (and backed up adequately). As with the exchange's +offline key, it is only used for a few cryptographic signatures and +thus the respective code can be run on modest hardware, like a +Raspberry Pi. The following values are to be configured in the section [auditor]: - ``AUDITOR_PRIV_FILE``: Path to the auditor’s private key file. +- ``PUBLIC_KEY``: Public key of the auditor, in Base32 encoding. + Set from value printed by ``gnunet-ecc -p $AUDITOR_PRIV_FILE``. + + .. _AuditorServing: Serving @@ -258,8 +266,8 @@ documentation for details. Database -------- -The option ``db`` under section [auditor] gets the DB backend’s name the -exchange is going to use. So far, only ``db = postgres`` is supported. After +The option ``DB`` under section [auditor] gets the DB backend’s name the +exchange is going to use. So far, only ``DB = postgres`` is supported. After choosing the backend, it is mandatory to supply the connection string (namely, the database name). This is possible in two ways: @@ -294,14 +302,15 @@ Deployment .. _Wallets: Before GNU Taler wallets will happily interact with an exchange, -the respective auditor's public key (to be obtained via ``gnunet-ecc``) +the respective auditor's public key (to be obtained via ``gnunet-ecc -p``) must be added under the respective currency to the wallet. This is usually expected to be hard-coded into the Taler wallet. Users can also manually add auditors for a particular currency via a Web page offering the respective pairing. -FIXME: explain how that Web page works! +FIXME-DOLD: explain how that Web page works, once it works... + .. _AuditorExchange: @@ -322,31 +331,51 @@ master public key. $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL +The equivalent step must be performed by the exchange operator. +Here, the exchange operator must use the ``taler-exchange-offline`` +tool to add the auditor's public key, base URL and (business) name +to the list of approved auditors of the exchange. For details, +see the exchange operator manual. +# FIXME-ttn: add link please? + + +.. _SigningDenominations: + +Signing Denominations +--------------------- + +.. index:: maintenance + +This step must be performed regularly whenever the exchange is +deploying new denomination keys. After the exchange operator +has signed new keys using the ``taler-exchange-offline`` tool, +each auditor should run -.. _AuditorDenominations: +.. code-block:: console -Denominations -------------- + $ taler-auditor-offline download > input.json -This step must be performed for each denomination (key) offered by the -exchange. As denomination keys expire, this step has to be repeated -periodically whenever new keys are created. +to import the latest set of denomination keys. The key data +should then be inspected using -.. FIXME: this is outdated... +.. code-block:: console -During denomination key setup, -the exchange operator obtains a *blob* with the data about denomination keys -that the exchange operator needs to get signed by every auditor the exchange -wishes (or is forced to) work with. + $ taler-auditor-offline show < input.json -In a normal scenario, an auditor must have some secure business process to -receive the blob to sign (Website, manual delivery, ...). Note that the -blob does not contain confidential data, but signing the wrong keys would -be fatal in that it may allow an illegitimate exchange to convince users -that it is a trustworthy operator and subsequently betray the user's trust -that is anchored in the existence of a trustworthy auditor. +and compared with the data the exchange operator saw when doing the offline +signature. This process should involve directly the humans operating both +systems and may require them to establish a trustworthy connection. The +details how the auditor communicates with the exchange operator are a business +process that is outside of the scope of this document. -Given the JSON data, the auditor would sign it using: +Note that the *input.json* does not contain any confidential data. However, +signing the wrong keys would be fatal in that it may allow an illegitimate +exchange to convince users that it is a trustworthy operator and subsequently +betray the user's trust that is anchored in the existence of a trustworthy +auditor. + +Given the verified JSON input, the auditor can then sign it (typically +on its offline system) using: .. code-block:: console @@ -357,7 +386,8 @@ and from there uploaded to the exchange using: $ taler-auditor-offline upload < output.json -The contents of ``output.json`` can be public and require no special handling. +The contents of ``output.json`` can again be public and require no special +handling. If the auditor has been correctly added, the exchange’s ``/keys`` response will contain an entry in the ``auditors`` array mentioning the @@ -370,10 +400,14 @@ Database -------- The next key step for the auditor is to configure replication of the -exchange's database in-house. The ``taler-exchange-dbinit`` tool should be +*exchange*'s database in-house. The ``taler-exchange-dbinit`` tool can be used to setup the schema. For replication of the actual SQL data, we refer to the Postgres manual. We note that asynchronous replication should suffice. +.. note: + Easy and secure database synchronization between exchange and auditor + is still an open issue the developer team expects to address for Taler v1.0. + Note that during replication, the only statements that may be performed are ``INSERT``\ s. ``CREATE`` / ``DELETE`` / ``DROP`` / ``UPDATE`` are generally not allowed. A @@ -387,6 +421,7 @@ data) and convenient (with respect to automatic and timely synchronization) garbage collection still needs to be developed. + .. _Operation: Operation @@ -397,9 +432,10 @@ Operation Web service ----------- -The ``taler-auditor-httpd`` runs the required REST API for the auditor. -The service must have ``INSERT`` rights against the auditor's database. -FIXME: note which table? +The ``taler-auditor-httpd`` runs the required REST API for the auditor. The +service must have ``INSERT`` (and ``SELECT``) rights on the +``deposit_confirmations`` table in the auditor's database. We expect that in +future versions additional rights may be required. As the ``taler-auditor-httpd`` does not include HTTPS-support, it is advisable to run it behind a reverse proxy that offers TLS termination. @@ -410,10 +446,14 @@ advisable to run it behind a reverse proxy that offers TLS termination. 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`` -script into the TeX report. +Performing an audit is done by invoking the ``taler-auditor`` shell script. +The shell script invokes the various helper processes. For additional +performance and security, one may want to run the various helpers individually +and with the respective minimal set of access rights (only +``taler-helper-auditor-wire`` needs the credentials to query the bank for wire +transfers). The shell script combines the final JSON outputs of the various +helpers using the ``taler-helper-auditor-render.py`` script into the TeX +report. Regardless, the simplest way to obtain a report is to run: .. code-block:: console @@ -477,16 +517,18 @@ specific release notes to ensure this is correct for the specific upgrade. -The auditor database can be re-initialized using: +The auditor database can be reset using: .. code-block:: console - $ 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 -with the bank) when the auditor is next launched, as it will re-verify all -historic transactions. Hence this should not be done in a production system. +*lost*, including steps like enabling an exchange using +``taler-auditor-exchange``. Thus, doing so may result in significant +commputation (and bandwidth consumption with the bank) when the auditor is +next launched, as it will re-download and re-verify all historic transactions. +Hence this should not be done in a production system. @@ -499,6 +541,7 @@ 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 exchange operator includes the details on how to revoke a denomination key, so the auditor should only have to report (and possibly enforce) this step. +-- FIXME-ttn: link to exchange chapter on revocations here? If all denominations of an exchange are revoked, the exchange includes logic to wire back all returned funds to the bank accounts from which they @@ -552,9 +595,9 @@ exchange's bank account, the other components only need access to the database. All auditor subsystems basically start their audit from a certain transaction -index (BIG SERIAL) in the auditor database which identifies where the -last audit concluded. They then check that the transactions claimed in -the exchange's database match up internally, including the cryptographic +index (``BIG SERIAL``) in the auditor database which identifies where the last +audit concluded. They then check that the transactions claimed in the +exchange's database match up internally, including the cryptographic signatures and also with respect to amounts adding up. The auditor also calculates the exchange's profits and expected bank balances. Once all existing transactions are processed, the auditor processes store the current |