[taler-docs] branch master updated: address ttn comments

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 0cc41c0  address ttn comments
0cc41c0 is described below

commit 0cc41c007f771f5bf8897e39565e426b44cfd7c1
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Dec 17 16:30:16 2020 +0100

    address ttn comments
---
 manpages/taler-exchange-offline.1.rst |  2 +-
 taler-auditor-manual.rst              | 44 ++++++++++++++---------------------
 2 files changed, 19 insertions(+), 27 deletions(-)

diff --git a/manpages/taler-exchange-offline.1.rst 
b/manpages/taler-exchange-offline.1.rst
index a441f49..cdedd20 100644
--- a/manpages/taler-exchange-offline.1.rst
+++ b/manpages/taler-exchange-offline.1.rst
@@ -26,7 +26,7 @@ the exchange’s long-term offline signing key and should be 
run in a secure
 (offline) environment under strict controls.  The tool takes a list of
 subcommands as arguments which are then processed sequentially.
 
-The tool includes two subcommands to interact with the *online* exchange's
+The tool includes two subcommands to interact *online* with the exchange's
 REST APIs.  The "download" subcommand downloads the future public keys from the
 running exchange.  The resulting data serves as input to the "sign" and "show"
 subcommands.  The "upload" subcommand uploads the signatures created with the
diff --git a/taler-auditor-manual.rst b/taler-auditor-manual.rst
index 1301f63..74e4ebf 100644
--- a/taler-auditor-manual.rst
+++ b/taler-auditor-manual.rst
@@ -330,7 +330,11 @@ Denominations
 
 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.  During denomination key setup,
+periodically whenever new keys are created.
+
+.. FIXME: this is outdated...
+
+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.
@@ -338,30 +342,22 @@ wishes (or is forced to) work with.
 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.  Given the blob, the auditor would sign it using:
+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.
 
-.. What does "fatal" mean precisely -- audit fail, system fail?  --ttn
+Given the JSON data, the auditor would sign it using:
 
 .. code-block:: console
 
-   $ taler-auditor-sign -m EXCHANGE_MASTER_PUB \
-       -r BLOB -u AUDITOR_URL -o OUTPUT_FILE
-
-Those arguments are all mandatory.
+   $ taler-auditor-offline sign < input.json > output.json
 
--  ``EXCHANGE_MASTER_PUB``: the base32 Crockford-encoded exchange’s
-   master public key.
+The resulting ``output.json`` should then be copied to an online system,
+and from there uploaded to the exchange using:
 
--  ``BLOB``: the blob generated by the ``taler-exchange-keyup`` tool.
+   $ taler-auditor-offline upload < output.json
 
--  ``AUDITOR_URL``: the URL that identifies the auditor.
-
--  ``OUTPUT_FILE``: where on the disk the signed blob is to be saved.
-
-``OUTPUT_FILE`` must then be provided to the exchange and there copied into
-the directory specified by the option ``AUDITOR_BASE_DIR`` under the section
-``[exchangedb]``.  The contents of ``OUTPUT_FILE`` can be public and require
-no special handling.
+The contents of ``output.json`` can 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
@@ -707,14 +703,10 @@ CodeBlau reports the following checks:
 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.
-
-.. Who is "we" -- the auditor?  Better to say "included in the
-   database duplicated from the exchange"?  --ttn
+This tool verifies that the deposit confirmations reported by merchants
+directly to the auditor are also included in the database duplicated from the
+exchange at the auditor.  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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.