diff options
Diffstat (limited to 'manpages/taler-auditor-offline.1.rst')
| -rw-r--r-- | manpages/taler-auditor-offline.1.rst | 139 |
1 files changed, 80 insertions, 59 deletions
diff --git a/manpages/taler-auditor-offline.1.rst b/manpages/taler-auditor-offline.1.rst index 3ee3b7db..75f4f731 100644 --- a/manpages/taler-auditor-offline.1.rst +++ b/manpages/taler-auditor-offline.1.rst @@ -12,51 +12,54 @@ Synopsis ======== **taler-auditor-offline** +[**-c** *FILENAME* | **––config=**\ \ *FILENAME*] [**-h** | **––help**] +[**-L** *LOGLEVEL* | **––loglevel=**\ \ *LOGLEVEL*] +[**-o** *FILE* | **––output=**\ \ *FILE*] [**-v** | **––version**] -[SUBCOMMANDS]* +[subcommand ...] Description =========== -**taler-auditor-offline** is a command line tool to be used by an auditor to +**taler-auditor-offline** is a command-line tool to be used by an auditor to sign that he is aware of certain keys being used by a exchange. Using this signature, the auditor affirms that he will verify that the exchange is properly accounting for coins of those denominations. The tool takes a list of subcommands as arguments which are then processed sequentially. The tool includes two subcommands to interact *online* with the exchange's -REST APIs. The "download" subcommand downloads current public keys from the +REST APIs. The ``download`` subcommand downloads current public keys from the running exchange. Note that this only includes keys that the exchange operator has previously validated using the **taler-exchange-offline** tool. -The resulting data serves as input to the "sign" and "show" subcommands. +The resulting data serves as input to the ``sign`` and ``show`` subcommands. -The "upload" subcommand uploads the signatures created with the private key to -the exchange. It handles the output of all subcommands (except "download"). -The "download" and "upload" commands must naturally be run "online" and do not +The ``upload`` subcommand uploads the signatures created with the private key to +the exchange. It handles the output of all subcommands (except ``download``). +The ``download`` and ``upload`` subcommands must naturally be run "online" and do not require access to the auditor's private key, which should be kept offline. All other subcommands are intended to be run "offline". However, especially -when testing, it is of course possible to run the commands online as well. +when testing, it is of course possible to run the subcommands online as well. Generally, subcommands read inputs (beyond command-line arguments) -from {\tt stdin}. However, they may also consume outputs of previous -subcommands. The outputs of multiple commands is automatically combined, -and if not consumed the final output is printed to {\tt stdout}. +from ``stdin``. However, they may also consume outputs of previous +subcommands. The outputs of multiple subcommands are automatically combined, +and if not consumed the final output is printed to ``stdout``. -The general options to for **taler-auditor-offline** are: +The general options for **taler-auditor-offline** are: **-c** *FILENAME* \| **––config=**\ \ *FILENAME* Use the configuration and other resources for the merchant to operate - from FILENAME. + from *FILENAME*. **-h** \| **––help** Print short help on options. **-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* - Specifies the log level to use. Accepted values are: DEBUG, INFO, - WARNING, ERROR. + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. **-o** *FILE* \| **––output=**\ \ *FILE* Where to write a denomination key signing request file to be given to @@ -75,21 +78,25 @@ The exchange and the **taler-auditor-httpd** must both be provided with the auditor's public key, such that they can validate messages signed by the auditor. To obtain the auditor's public key, use: -$ AUDITOR_PRIV_FILE=`taler-config -f -c $CONF -s AUDITOR -o AUDITOR_PRIV_FILE` -$ gnunet-ecc -p $AUDITOR_PRIV_FILE +.. code-block:: console + + $ AUDITOR_PRIV_FILE=`taler-config -f -c $CONF -s AUDITOR -o AUDITOR_PRIV_FILE` + $ gnunet-ecc -p $AUDITOR_PRIV_FILE Note that if the private key file does not yet exist, the above will fail. In this case, create the private key using: -$ AUDITOR_PRIV_FILE=`taler-config -f -c $CONF -s AUDITOR -o AUDITOR_PRIV_FILE` -$ AUDITOR_PRIV_DIR=`dirname $AUDITOR_PRIV_FILE` -$ mkdir -p $AUDITOR_PRIV_DIR -$ gnunet-ecc -g1 $AUDITOR_PRIV_FILE +.. code-block:: console + + $ AUDITOR_PRIV_FILE=`taler-config -f -c $CONF -s AUDITOR -o AUDITOR_PRIV_FILE` + $ AUDITOR_PRIV_DIR=`dirname $AUDITOR_PRIV_FILE` + $ mkdir -p $AUDITOR_PRIV_DIR + $ gnunet-ecc -g1 $AUDITOR_PRIV_FILE Relevant configuration options for **taler-auditor-offline** are: -* [auditor/AUDITOR_PRIV_FILE] --- where to store the private key +* ``[auditor/AUDITOR_PRIV_FILE]`` --- where to store the private key @@ -99,67 +106,68 @@ Subcommands download -------- -This command must be run online. It downloads future signing and denomination +This subcommand must be run online. It downloads future signing and denomination keys with the associated meta data from the exchange and outputs the resulting -JSON (for consumption by subsequent commands, or to stdout). +JSON (for consumption by subsequent subcommands, or to ``stdout``). show ---- -This command outputs information about future signing and denomination keys for +This subcommand outputs information about future signing and denomination keys for manual checking against the business-approved fee structure, lifetimes and other parameters. -It consumes the output of the "download" subcommand, either from "stdin" or +It consumes the output of the ``download`` subcommand, either from ``stdin`` or directly. -Its output always goes to "stdout" for human consumption (not in JSON). It -is usually a bad idea (but possible) to combine "show" with other commands, +Its output always goes to ``stdout`` for human consumption (not in JSON). It +is usually a bad idea (but possible) to combine ``show`` with other subcommands, except maybe for testing. sign ---- -This command signs information about future signing and denomination keys. +This subcommand signs information about future signing and denomination keys. -It consumes the output of the "download" subcommand, either from "stdin" or +It consumes the output of the ``download`` subcommand, either from ``stdin`` or directly. It outputs the signatures over *all* denomination and signing keys -present in the input, in a format suitable for the "upload" subcommand. +present in the input, in a format suitable for the ``upload`` subcommand. revoke-denomination ------------------- -This command signs a revocation message for a denomination key. +This subcommand signs a revocation message for a denomination key. The hash of the denomination public key must be given in the usual base32-encoding as the first and only argument to the subcommand. It outputs the signature affirming the revocation of the denomination key, -in a format suitable for the "upload" subcommand. +in a format suitable for the ``upload`` subcommand. revoke-signkey -------------- -This command signs a revocation message for an exchange online signing key. +This subcommand signs a revocation message for an exchange online signing key. The online signing public key must be given in the usual base32-encoding as the first and only argument to the subcommand. It outputs the signature affirming the revocation of the online signing key, -in a format suitable for the "upload" subcommand. +in a format suitable for the ``upload`` subcommand. enable-auditor -------------- -Informs an exchange that an auditor is to be activated. Afterwards, the +This subcommand +informs an exchange that an auditor is to be activated. Afterwards, the exchange will accept inputs from that auditor's **taler-auditor-offline** tool. Note that the auditor also must add the exchange to the list of exchanges that it audits via **taler-auditor-exchange**. Furthermore, the @@ -179,32 +187,34 @@ The third argument must be a human-readable name for the auditor. This may be shown to users and should identify the auditor's business entity. If the name includes spaces, the argument should be quoted. -The subcommand takes no inputs from stdin or other subcommands. +The subcommand takes no inputs from ``stdin`` or other subcommands. It outputs the signature affirming the addition of the auditor, -in a format suitable for the "upload" subcommand. +in a format suitable for the ``upload`` subcommand. disable-auditor --------------- -Informs an exchange that an auditor is to be deactivated. Afterwards, the +This subcommand +informs an exchange that an auditor is to be deactivated. Afterwards, the exchange will refuse inputs from that auditor's **taler-auditor-offline** tool. The auditor's public key must be given in the usual base32-encoding as the first argument. -The subcommand takes no inputs from stdin or other subcommands. +The subcommand takes no inputs from ``stdin`` or other subcommands. It outputs the signature affirming the removal of the auditor, -in a format suitable for the "upload" subcommand. +in a format suitable for the ``upload`` subcommand. enable-account -------------- -Informs an exchange that it should advertise a bank account as belonging to +This subcommand +informs an exchange that it should advertise a bank account as belonging to the exchange on its ``/wire`` endpoint. Note that this does *not* ensure that the exchange will use this bank account for incoming or outgoing wire transfers! For this, the **taler-exchange-transfer** and @@ -213,28 +223,29 @@ account information advertised could theoretically differ from that which these tool actually use, for example if the public bank account is only a front for the actual internal business acounts. -The payto:// URI (RFC 8905) of the exchange's bank account must be given +The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given as the first argument to the subcommand. -The subcommand takes no inputs from stdin or other subcommands. +The subcommand takes no inputs from ``stdin`` or other subcommands. It outputs the signature affirming the addition of the wire account, -in a format suitable for the "upload" subcommand. +in a format suitable for the ``upload`` subcommand. disable-account --------------- -Informs an exchange that it should stop advertising a bank account as +This subcommand +informs an exchange that it should stop advertising a bank account as belonging to the exchange on its ``/wire`` endpoint. -The payto:// URI (RFC 8905) of the exchange's (former) bank account must be +The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be given as the first argument to the subcommand. -The subcommand takes no inputs from stdin or other subcommands. +The subcommand takes no inputs from ``stdin`` or other subcommands. It outputs the signature affirming the deletion of the wire account, in a -format suitable for the "upload" subcommand. +format suitable for the ``upload`` subcommand. wire-fee @@ -252,16 +263,16 @@ Instead of a year, the string ``now`` can be given for the current year GANA registry as given in RFC 8905. The fees must be given in the usual Taler format of ``CURRENCY:NUMBER.FRACTION``. -The subcommand takes no inputs from stdin or other subcommands. +The subcommand takes no inputs from ``stdin`` or other subcommands. It outputs the signature affirming the wire fees, in a format suitable for the -"upload" subcommand. +``upload`` subcommand. upload ------ -This subcommand uploads outputs from other commands (except "download" and "show") +This subcommand uploads outputs from other subcommands (except ``download`` and ``show``) to the exchange. Note that it is possible that some uploads succeed, while others fail, as the operation is not atomic. @@ -282,29 +293,39 @@ Examples Download public keys from an exchange (online) ---------------------------------------------- -$ taler-auditor-offline download > keys.json +.. code-block:: console + + $ taler-auditor-offline download > keys.json Show information about public keys (offline or online) ------------------------------------------------------ -$ taler-auditor-offline show < keys.json +.. code-block:: console + + $ taler-auditor-offline show < keys.json Sign public keys (offline) -------------------------- -$ taler-auditor-offline sign < keys.json > sigs.json +.. code-block:: console + + $ taler-auditor-offline sign < keys.json > sigs.json Upload auditor signatures (online) ---------------------------------- -$ taler-auditor-offline upload < sigs.json +.. code-block:: console + + $ taler-auditor-offline upload < sigs.json Download, sign and upload, all in one (online) ---------------------------------------------- Note that doing this is only recommended in non-production deployments. -$ taler-auditor-offline download sign upload +.. code-block:: console + + $ taler-auditor-offline download sign upload @@ -313,9 +334,9 @@ Security considerations ======================= The **taler-auditor-offline** tool assumes that it is run on a high-security -system, especially for the "sign" command. +system, especially for the ``sign`` subcommand. -The auditor should first use the "show" command on the offline system to +The auditor should first use the ``show`` subcommand on the offline system to check that the keys being signed are acceptable. This process requires manual work: the auditor should check with the exchange operator that the keys (and meta data) matches that previously seen by the |