diff options
| -rw-r--r-- | conf.py | 13 | ||||
| -rw-r--r-- | manpages/taler-auditor-offline.1.rst | 335 | ||||
| -rw-r--r-- | manpages/taler-auditor-sign.1.rst | 65 | ||||
| -rw-r--r-- | manpages/taler-exchange-keycheck.1.rst | 56 | ||||
| -rw-r--r-- | manpages/taler-exchange-keyup.1.rst | 85 | ||||
| -rw-r--r-- | manpages/taler-exchange-offline.1.rst | 375 | ||||
| -rw-r--r-- | manpages/taler-exchange-wire.1.rst | 47 |
7 files changed, 714 insertions, 262 deletions
@@ -275,8 +275,6 @@ man_pages = [ ("manpages/taler-auditor-exchange.1", "taler-auditor-exchange", "add or remove exchange from auditor’s list", "GNU Taler contributors", 1), - ("manpages/taler-auditor-sign.1", "taler-auditor-sign", - "sign exchange denomination as auditor", "GNU Taler contributors", 1), ("manpages/taler-auditor-dbinit.1", "taler-auditor-dbinit", "setup auditor database", "GNU Taler contributors", 1), ("manpages/taler-auditor.1", "taler-auditor", "audit exchange", @@ -301,14 +299,11 @@ man_pages = [ "initialize Taler exchange database", "GNU Taler contributors", 1), ("manpages/taler-exchange-httpd.1", "taler-exchange-httpd", "run Taler exchange (with RESTful API)", "GNU Taler contributors", 1), - ("manpages/taler-exchange-keycheck.1", "taler-exchange-keycheck", - "check validity of Taler signing and denomination keys", + ("manpages/taler-auditor-offline.1", "taler-auditor-offline", + "Taler auditor certifies that it audits a Taler exchange", "GNU Taler contributors", 1), - ("manpages/taler-exchange-keyup.1", "taler-exchange-keyup", - "set up Taler exchange denomination and signing", - "GNU Taler contributors", 1), - ("manpages/taler-exchange-wire.1", "taler-exchange-wire", - "create the master-key signed responses to /wire", + ("manpages/taler-exchange-offline.1", "taler-exchange-offline", + "operations using the offline key of a Taler exchange", "GNU Taler contributors", 1), ("manpages/taler-exchange-wirewatch.1", "taler-exchange-wirewatch", "watch for incoming wire transfers", "GNU Taler contributors", 1), diff --git a/manpages/taler-auditor-offline.1.rst b/manpages/taler-auditor-offline.1.rst new file mode 100644 index 00000000..3ee3b7db --- /dev/null +++ b/manpages/taler-auditor-offline.1.rst @@ -0,0 +1,335 @@ +taler-auditor-offline(1) +######################## + +.. only:: html + + Name + ==== + + **taler-auditor-offline** - operations using the auditor's private key + +Synopsis +======== + +**taler-auditor-offline** +[**-h** | **––help**] +[**-v** | **––version**] +[SUBCOMMANDS]* + + +Description +=========== + +**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 +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 "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 +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. +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}. + + +The general options to for **taler-auditor-offline** are: + +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + 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. + +**-o** *FILE* \| **––output=**\ \ *FILE* + Where to write a denomination key signing request file to be given to + the auditor. + +**-v** \| **––version** + Print version information. + + + + +Configuration +============= + +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 + +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 + + +Relevant configuration options for **taler-auditor-offline** are: + +* [auditor/AUDITOR_PRIV_FILE] --- where to store the private key + + + +Subcommands +=========== + +download +-------- + +This command 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). + + +show +---- + +This command 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 +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, +except maybe for testing. + + +sign +---- + +This command signs information about future signing and denomination keys. + +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. + + +revoke-denomination +------------------- + +This command 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. + + +revoke-signkey +-------------- + +This command 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. + + + +enable-auditor +-------------- + +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 +exchange's database will need to be provided to the auditor. This subcommand +only informs the exchange about the auditor, but does not perform those +additional mandatory steps for a working auditor. + +The auditor's public key must be given in the usual base32-encoding as the +first argument. + +The auditor's REST API base URL must be given as the second argument. The tool +performs a minimal sanity check, namely that the URL begins with "http" +(this also allows "https"), but as it runs offline does not perform any further +validation! + +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. + +It outputs the signature affirming the addition of the auditor, +in a format suitable for the "upload" subcommand. + + +disable-auditor +--------------- + +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. + +It outputs the signature affirming the removal of the auditor, +in a format suitable for the "upload" subcommand. + + +enable-account +-------------- + +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 +**taler-exchange-wirewatch** tools must be configured. Furthermore, the bank +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 +as the first argument to the subcommand. + +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. + + +disable-account +--------------- + +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 +given as the first argument to the subcommand. + +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. + + +wire-fee +-------- + +This subcommand informs an exchange about the desired wire fee (and closing fee) +structure for particular wire method and a calendar year (!). The tool does not +permit changing wire fees during a calendar year. Also, once the wire fee has been +set for a calendar year, it cannot be changed. + +The subcommand takes the year, wire-method (see RFC 8905, examples include +``x-taler-bank`` or ``iban``), wire fee and closing fee as arguments. +Instead of a year, the string ``now`` can be given for the current year +(this is mostly useful for test cases). The wire-method should follow the +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. + +It outputs the signature affirming the wire fees, in a format suitable for the +"upload" subcommand. + + +upload +------ + +This subcommand uploads outputs from other commands (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. + +The subcommand takes no arguments and has no output. + + +help +---- + +This subcommand shows a summary of all available subcommands with the +required arguments. + + + +Examples +======== + +Download public keys from an exchange (online) +---------------------------------------------- + +$ taler-auditor-offline download > keys.json + +Show information about public keys (offline or online) +------------------------------------------------------ + +$ taler-auditor-offline show < keys.json + +Sign public keys (offline) +-------------------------- + +$ taler-auditor-offline sign < keys.json > sigs.json + +Upload auditor signatures (online) +---------------------------------- + +$ 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 + + + + +Security considerations +======================= + +The **taler-auditor-offline** tool assumes that it is run on a high-security +system, especially for the "sign" command. + +The auditor should first use the "show" command 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 +exchange operator when they used the **taler-exchange-offline** tool. + + +See Also +======== + +gnunet-ecc(1), taler-auditor-exchange(1), taler-exchange-offline(1), +taler.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-auditor-sign.1.rst b/manpages/taler-auditor-sign.1.rst deleted file mode 100644 index 5d0bb1c1..00000000 --- a/manpages/taler-auditor-sign.1.rst +++ /dev/null @@ -1,65 +0,0 @@ -taler-auditor-sign(1) -##################### - -.. only:: html - - Name - ==== - - **taler-auditor-sign** - sign exchange denomination as auditor - -Synopsis -======== - -**taler-auditor-sign** -[**-a** *FILE* | **––auditor-key=**\ \ *FILE*] -[**-h** | **––help**] -[**-m** *KEY* | **––exchange-key=**\ \ *KEY*] -[**-u** *URL* | **––auditor-url=**\ \ *URL*] -[**-r** *FILE* | **––exchange-request=**\ \ *FILE*] -[**-o** *FILE* | **––output=**\ \ *FILE*] - -Description -=========== - -**taler-auditor-sign** 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 those coins. - -The exchange for which keys were signed must have been added to the -auditor using taler-auditor-exchange first! - -**-a** *FILE* \| **––auditor-key=**\ \ *FILE* - Location of the private EdDSA auditor key. If it does not exist, it - will be created. - -**-h** \| **––help** - Print short help on options. - -**-m** *KEY* \| **––exchange-key=**\ \ *KEY* - Public key of the exchange in Crockford base32 encoding, for example - as generated by gnunet-ecc -p. - -**-u** *URL* \| **––auditor-url=**\ \ *URL* - URL of the auditor. Provides informative link for the user to learn - more about the auditor. - -**-r** *FILE* \| **––exchange-request=**\ \ *FILE* - File with the exchange’s denomination key signing request as - generated by taler-exchange-keyup -o. - -**-o** *FILE* \| **––output=**\ \ *FILE* - File where the auditor should write the EdDSA signature. - -See Also -======== - -gnunet-ecc(1), taler-auditor-exchange(1), taler-exchange-keyup(1), -taler.conf(5) - -Bugs -==== - -Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-keycheck.1.rst b/manpages/taler-exchange-keycheck.1.rst deleted file mode 100644 index 48bf0d1c..00000000 --- a/manpages/taler-exchange-keycheck.1.rst +++ /dev/null @@ -1,56 +0,0 @@ -taler-exchange-keycheck(1) -########################## - -.. only:: html - - Name - ==== - - **taler-exchange-keycheck** - check validity of Taler signing and - denomination keys - -Synopsis -======== - -**taler-exchange-keycheck** -[**-h** | **––help**] -[**-v** | **––version**] - -Description -=========== - -**taler-exchange-keycheck** can be used to check if the signing and -denomination keys in the operation directory are well-formed. This can -be useful after importing fresh keys from the offline system to ensure -that the files are correct. - -Its options are as follows: - -**-c** *FILENAME* \| **––config=**\ \ *FILENAME* - Use the configuration and other resources for the exchange to operate - from *FILENAME*. - -**-h** \| **––help** - Print short help on options. - -**-i** *AMOUNT* \| **––denomination-info-hash=**\ \ *AMOUNT* - Output the full denomination key hashes and the validity starting times of all denomination keys for the given *AMOUNT*. Useful to identify hashes when revoking keys. - -**-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* - Specifies the log level to use. Accepted values are: DEBUG, INFO, - WARNING, ERROR. - -**-v** \| **––version** - Print version information. - -See Also -======== - -taler-exchange-httpd(1), taler-exchange-keyup(1), -taler-exchange-dbinit(1), taler.conf(5). - -Bugs -==== - -Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-keyup.1.rst b/manpages/taler-exchange-keyup.1.rst deleted file mode 100644 index e101b4cd..00000000 --- a/manpages/taler-exchange-keyup.1.rst +++ /dev/null @@ -1,85 +0,0 @@ -taler-exchange-keyup(1) -####################### - -.. only:: html - - Name - ==== - - **taler-exchange-keyup** - set up Taler exchange denomination and signing - keys - -Synopsis -======== - -**taler-exchange-keyup** -[**-h** | **––help**] -[**-m** *FILE* | **––master-key=**\ \ *FILE*] -[**-o** *FILE* | **––output=**\ \ *FILE*] -[**-r** *DKH* | **––revoke=**\ \ *DKH*] -[**-t** *TIMESTAMP* | **––time=**\ \ *TIMESTAMP*] -[**-v** | **––version**] - -Description -=========== - -**taler-exchange-keyup** is a command line tool to setup Taler -denomination and signing keys. This tool requires access to the -exchange’s long-term offline signing key and should be run in a secure -(offline) environment under strict controls. The resulting keys can then -be copied to the main online directory where the Taler HTTP server -operates. - -Its options are as follows: - -**-c** *FILENAME* \| **––config=**\ \ *FILENAME* - Use the configuration and other resources for the merchant to operate - from FILENAME. - -**-f** *DIRNAME* \| **––feedir=**\ \ *DIRNAME* - Directory where to write the wire transfer fee structure. If not given, - the one from the main configuration will be used. - -**-h** \| **––help** - Print short help on options. - -**-L** *LOGLEVEL* \| **––loglevel=**\ \ *LOGLEVEL* - Specifies the log level to use. Accepted values are: DEBUG, INFO, - WARNING, ERROR. - -**-k** *BITS* \| **––replacement-keysize=**\ \ *BITS* - When revoke an active denomination key (see **--r** option), use - *BITS* bit for the replacement denomination key. Default is 2048 (bits). - -**-m** *FILE* \| **––master-key=**\ \ *FILE* - Location of the private EdDSA offline master key of the exchange. If not - given, the location given in the configuration file will be used. - -**-o** *FILE* \| **––output=**\ \ *FILE* - Where to write a denomination key signing request file to be given to - the auditor. - -**-r** *DKH* \| **––revoke=**\ \ *DKH* - Revoke the denomination key where the denomination public key’s hash - is DKH. - -**-T** *[+/-]MICROSECONDS* \| **––timetravel=**\ \ *[+/-]MICROSECONDS* - Modify system time (as seen by this process) by the given offset (for debugging/testing). - -**-t** *TIMESTAMP* \| **––time=**\ \ *TIMESTAMP* - Operate as if the current time was *TIMESTAMP*. - -**-v** \| **––version** - Print version information. - -See Also -======== - -taler-exchange-httpd(1), taler-exchange-keyup(1), -taler-exchange-keycheck(1), taler.conf(5). - -Bugs -==== - -Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-offline.1.rst b/manpages/taler-exchange-offline.1.rst new file mode 100644 index 00000000..a441f498 --- /dev/null +++ b/manpages/taler-exchange-offline.1.rst @@ -0,0 +1,375 @@ +taler-exchange-offline(1) +######################### + +.. only:: html + + Name + ==== + + **taler-exchange-offline** - perform operations with exchange offline master private key + +Synopsis +======== + +**taler-exchange-offline** +[**-h** | **––help**] +[**-v** | **––version**] +[SUBCOMMANDS]* + + +Description +=========== + +**taler-exchange-offline** is a command line tool to interact with the Taler +exchange's master private key. Most operations of this tool require access to +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 +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 +private master 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 require access to the offline key. + +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. +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}. + + +The general options to for **taler-exchange-offline** are: + +**-c** *FILENAME* \| **––config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + 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. + +**-o** *FILE* \| **––output=**\ \ *FILE* + Where to write a denomination key signing request file to be given to + the auditor. + +**-v** \| **––version** + Print version information. + + +Configuration +============= + +The exchange validates all operations by checking the signatures against the +master public key that must be provided in the exchange configuration. To +obtain the master public key, use: + +$ MASTER_PRIV_FILE=`taler-config -f -c $CONF -s EXCHANGE -o MASTER_PRIV_FILE` +$ gnunet-ecc -p $MASTER_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: + +$ MASTER_PRIV_FILE=`taler-config -f -c $CONF -s EXCHANGE -o MASTER_PRIV_FILE` +$ MASTER_PRIV_DIR=`dirname $MASTER_PRIV_FILE` +$ mkdir -p $MASTER_PRIV_DIR +$ gnunet-ecc -g1 $MASTER_PRIV_FILE + + +Relevant configuration options for **taler-exchange-offline** are: + +* [exchange/BASE_URL] --- how to reach the exchange (for download/upload) +* [exchange-offline/MASTER_PRIV_FILE] --- where to store the private keys +* [exchange-offline/SECM_TOFU_FILE] --- where to store TOFU data + + + +Subcommands +=========== + +download +-------- + +This command 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). + + +show +---- + +This command 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 +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, +except maybe for testing. + + +sign +---- + +This command signs information about future signing and denomination keys. + +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. + + +revoke-denomination +------------------- + +This command 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. + + +revoke-signkey +-------------- + +This command 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. + + + +enable-auditor +-------------- + +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 +exchange's database will need to be provided to the auditor. This subcommand +only informs the exchange about the auditor, but does not perform those +additional mandatory steps for a working auditor. + +The auditor's public key must be given in the usual base32-encoding as the +first argument. + +The auditor's REST API base URL must be given as the second argument. The tool +performs a minimal sanity check, namely that the URL begins with "http" +(this also allows "https"), but as it runs offline does not perform any further +validation! + +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. + +It outputs the signature affirming the addition of the auditor, +in a format suitable for the "upload" subcommand. + + +disable-auditor +--------------- + +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. + +It outputs the signature affirming the removal of the auditor, +in a format suitable for the "upload" subcommand. + + +enable-account +-------------- + +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 +**taler-exchange-wirewatch** tools must be configured. Furthermore, the bank +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 +as the first argument to the subcommand. + +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. + + +disable-account +--------------- + +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 +given as the first argument to the subcommand. + +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. + + +wire-fee +-------- + +This subcommand informs an exchange about the desired wire fee (and closing fee) +structure for particular wire method and a calendar year (!). The tool does not +permit changing wire fees during a calendar year. Also, once the wire fee has been +set for a calendar year, it cannot be changed. + +The subcommand takes the year, wire-method (see RFC 8905, examples include +``x-taler-bank`` or ``iban``), wire fee and closing fee as arguments. +Instead of a year, the string ``now`` can be given for the current year +(this is mostly useful for test cases). The wire-method should follow the +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. + +It outputs the signature affirming the wire fees, in a format suitable for the +"upload" subcommand. + + +upload +------ + +This subcommand uploads outputs from other commands (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. + +The subcommand takes no arguments and has no output. + + +help +---- + +This subcommand shows a summary of all available subcommands with the +required arguments. + + + +Examples +======== + +Download future public keys from an exchange (online) +----------------------------------------------------- + +$ taler-exchange-offline download > keys.json + +Show information about future public keys (offline or online) +------------------------------------------------------------- + +$ taler-exchange-offline show < keys.json + +Sign future public keys (offline) +--------------------------------- + +$ taler-exchange-offline sign < keys.json > sigs.json + +Upload signatures about future public keys (online) +--------------------------------------------------- + +$ taler-exchange-offline upload < sigs.json + +Download, sign and upload, all in one (online) +---------------------------------------------- + +Note that doing this is only recommended in non-production deployments. + +$ taler-exchange-offline download sign upload + + +Create signature to enable bank account (offline) +------------------------------------------------- + +$ taler-exchange-offline enable-account payto://iban/DE24242 > account.json + +Upload bank account signature (online) +-------------------------------------- + +$ taler-exchange-offline upload < account.json + + +Combine signing keys and enabling bank account (offline) +-------------------------------------------------------- + +$ taler-exchange-offline sign enable-account payto://iban/DE24242 < keys.json > combo.json + +Upload various signatures (online) +---------------------------------- + +$ taler-exchange-offline upload < combo.json + +Create multiple revocation messages in one pass (offline) +--------------------------------------------------------- + +$ taler-exchange-offline revoke-denomination $DKH1 revoke-denomination $DKH2 > revoke.json +$ taler-exchange-offline revoke-signkey $SK1 revoke-signkey $SK2 > revoke.json +$ taler-exchange-offline revoke-signkey $SK revoke-denomkey $DKH > mix.json + +The outputs ("revoke.json", "mix.json") must be uploaded using the "upload" +command to the exchange to actually revoke the keys. + + + +Security considerations +======================= + +The **taler-exchange-offline** tool assumes that it is run on a high-security +system with *monotonic time*. The time does not have to precisely match that +of the exchange, but it must be monotonic across tool invocations. The clock +of the offline system is used in the enable/disable signatures to communicate +an order of the events to the exchange. This prevents someone from replaying +an older "enable" (or "disable") message after a more recent "disable" (or +"enable") message has been provided to the exchange. Thus, there is no need +to keep the actual files exchanged with the offline tool secret. + +The **taler-exchange-offline** tool tries to make sure that the online signing +keys of the the exchange are always created by the same two security modules. +The goal here is to prevent an attacker who compromised **taler-exchange-httpd** +but *not* the security modules from providing attacker-controlled keys to the +offline signing process. + +For this, the **taler-exchange-offline** signing subcommand always +automatically learns the security module's public signing key and *trusts it +on first use* (TOFU), but stores it to disk (see the ``SECM_TOFU_FILE`` option +in the ``[exchange-offline]`` section of the configuration). If the keys +change subsequently, the tool will refuse to sign. + + + +See Also +======== + +taler-exchange-httpd(1), taler-auditor-offline(1), taler-auditor-exchange(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-wire.1.rst b/manpages/taler-exchange-wire.1.rst deleted file mode 100644 index 7f042a4b..00000000 --- a/manpages/taler-exchange-wire.1.rst +++ /dev/null @@ -1,47 +0,0 @@ -taler-exchange-wire(1) -###################### - -.. only:: html - - Name - ==== - - **taler-exchange-wire** - create the master-key signed responses to - /wire - -Synopsis -======== - -**taler-exchange-wire** -[**-h** | **––help**] -[**-m** *MASTERKEYFILE* | **––master=**\ \ *MASTERKEYFILE*] -[**-v** | **––version**] - -Description -=========== - -**taler-exchange-wire** is used to create the exchange’s reply to a -/wire request. It converts the bank details into the appropriate signed -response. This needs to be done using the long-term offline master key. - -Its options are as follows: - -**-h** \| **––help** - Print short help on options. - -**-m** *MASTERKEYFILE* \| **––master=**\ \ *MASTERKEYFILE* - Specifies the name of the file containing the exchange’s master key. - -**-v** \| **––version** - Print version information. - -See Also -======== - -taler-exchange-httpd(1), taler.conf(5). - -Bugs -==== - -Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to <taler@gnu.org>. |