commit 0cc41c007f771f5bf8897e39565e426b44cfd7c1
parent a02fda277f0c7704d71a2f8b38fc2506b68d3df0
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 17 Dec 2020 16:30:16 +0100
address ttn comments
Diffstat:
2 files changed, 19 insertions(+), 27 deletions(-)
diff --git 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
@@ -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
