diff options
Diffstat (limited to 'man/taler-exchange-offline.1')
| -rw-r--r-- | man/taler-exchange-offline.1 | 442 |
1 files changed, 442 insertions, 0 deletions
diff --git a/man/taler-exchange-offline.1 b/man/taler-exchange-offline.1 new file mode 100644 index 00000000..858183c5 --- /dev/null +++ b/man/taler-exchange-offline.1 @@ -0,0 +1,442 @@ +.\" Man page generated from reStructuredText. +. +.TH "TALER-EXCHANGE-OFFLINE" "1" "Jan 21, 2021" "0.8pre0" "GNU Taler" +.SH NAME +taler-exchange-offline \- operations using the offline key of a Taler exchange +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-offline\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB––help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] +[\fB\-v\fP\ |\ \fB––version\fP] +[subcommand …] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-offline\fP 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. +.sp +The tool includes two subcommands to interact \fIonline\fP with the exchange’s +REST APIs. The \fBdownload\fP subcommand downloads the future public keys from the +running exchange. The resulting data serves as input to the \fBsign\fP and \fBshow\fP +subcommands. The \fBupload\fP subcommand uploads the signatures created with the +private master key to the exchange. It handles the output of all subcommands +(except \fBdownload\fP). The \fBdownload\fP and \fBupload\fP subcommands must naturally be +run “online” and do not require access to the offline key. +.sp +All other subcommands are intended to be run “offline”. However, especially +when testing, it is of course possible to run the subcommands online as well. +Generally, subcommands read inputs (beyond command\-line arguments) +from \fBstdin\fP\&. 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 \fBstdout\fP\&. +.sp +The general options for \fBtaler\-exchange\-offline\fP are: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB––help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-v\fP | \fB––version\fP +Print version information. +.UNINDENT +.SH CONFIGURATION +.sp +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: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ MASTER_PRIV_FILE=\(gataler\-config \-f \-c $CONF \-s EXCHANGE \-o MASTER_PRIV_FILE\(ga +$ gnunet\-ecc \-p $MASTER_PRIV_FILE +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note that if the private key file does not yet exist, the above will fail. +In this case, create the private key using: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ MASTER_PRIV_FILE=\(gataler\-config \-f \-c $CONF \-s EXCHANGE \-o MASTER_PRIV_FILE\(ga +$ MASTER_PRIV_DIR=\(gadirname $MASTER_PRIV_FILE\(ga +$ mkdir \-p $MASTER_PRIV_DIR +$ gnunet\-ecc \-g1 $MASTER_PRIV_FILE +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Relevant configuration options for \fBtaler\-exchange\-offline\fP are: +.INDENT 0.0 +.IP \(bu 2 +\fB[exchange/BASE_URL]\fP — how to reach the exchange (for download/upload) +.IP \(bu 2 +\fB[exchange\-offline/MASTER_PRIV_FILE]\fP — where to store the private keys +.IP \(bu 2 +\fB[exchange\-offline/SECM_TOFU_FILE]\fP — where to store TOFU data +.UNINDENT +.SH SUBCOMMANDS +.SS download +.sp +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 subcommands, or to \fBstdout\fP). +.SS show +.sp +This subcommand outputs information about future signing and denomination keys for +manual checking against the business\-approved fee structure, lifetimes and +other parameters. +.sp +It consumes the output of the \fBdownload\fP subcommand, either from \fBstdin\fP or +directly. +However, if given arg \fB\-\fP (hyphen), this input is not consumed, +but instead is passed to the next command. This functions like the +tee(1) command. +.sp +Its output always goes to \fBstdout\fP for human consumption (not in JSON). It +is usually a bad idea (but possible) to combine \fBshow\fP with other subcommands, +except maybe for testing. +.SS sign +.sp +This subcommand signs information about future signing and denomination keys. +.sp +It consumes the output of the \fBdownload\fP subcommand, either from \fBstdin\fP or +directly. +.sp +It outputs the signatures over \fIall\fP denomination and signing keys +present in the input, in a format suitable for the \fBupload\fP subcommand. +.SS revoke\-denomination +.sp +This subcommand signs a revocation message for a denomination key. +.sp +The hash of the denomination public key must be given in the usual +base32\-encoding as the first and only argument to the subcommand. +.sp +It outputs the signature affirming the revocation of the denomination key, +in a format suitable for the \fBupload\fP subcommand. +.SS revoke\-signkey +.sp +This subcommand signs a revocation message for an exchange online signing key. +.sp +The online signing public key must be given in the usual +base32\-encoding as the first and only argument to the subcommand. +.sp +It outputs the signature affirming the revocation of the online signing key, +in a format suitable for the \fBupload\fP subcommand. +.SS enable\-auditor +.sp +This subcommand +informs an exchange that an auditor is to be activated. Afterwards, the +exchange will accept inputs from that auditor’s \fBtaler\-auditor\-offline\fP +tool. Note that the auditor also must add the exchange to the list of +exchanges that it audits via \fBtaler\-auditor\-exchange\fP\&. 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. +.sp +The auditor’s public key must be given in the usual base32\-encoding as the +first argument. +.sp +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! +.sp +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. +.sp +The subcommand takes no inputs from \fBstdin\fP or other subcommands. +.sp +It outputs the signature affirming the addition of the auditor, +in a format suitable for the \fBupload\fP subcommand. +.SS disable\-auditor +.sp +This subcommand +informs an exchange that an auditor is to be deactivated. Afterwards, the +exchange will refuse inputs from that auditor’s \fBtaler\-auditor\-offline\fP +tool. +.sp +The auditor’s public key must be given in the usual base32\-encoding as the +first argument. +.sp +The subcommand takes no inputs from \fBstdin\fP or other subcommands. +.sp +It outputs the signature affirming the removal of the auditor, +in a format suitable for the \fBupload\fP subcommand. +.SS enable\-account +.sp +This subcommand +informs an exchange that it should advertise a bank account as belonging to +the exchange on its \fB/wire\fP endpoint. Note that this does \fInot\fP ensure that +the exchange will use this bank account for incoming or outgoing wire +transfers! For this, the \fBtaler\-exchange\-transfer\fP and +\fBtaler\-exchange\-wirewatch\fP 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. +.sp +The \fBpayto://\fP URI (RFC 8905) of the exchange’s bank account must be given +as the first argument to the subcommand. +.sp +The subcommand takes no inputs from \fBstdin\fP or other subcommands. +.sp +It outputs the signature affirming the addition of the wire account, +in a format suitable for the \fBupload\fP subcommand. +.SS disable\-account +.sp +This subcommand +informs an exchange that it should stop advertising a bank account as +belonging to the exchange on its \fB/wire\fP endpoint. +.sp +The \fBpayto://\fP URI (RFC 8905) of the exchange’s (former) bank account must be +given as the first argument to the subcommand. +.sp +The subcommand takes no inputs from \fBstdin\fP or other subcommands. +.sp +It outputs the signature affirming the deletion of the wire account, in a +format suitable for the \fBupload\fP subcommand. +.SS wire\-fee +.sp +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. +.sp +The subcommand takes the year, wire\-method (see RFC 8905, examples include +\fBx\-taler\-bank\fP or \fBiban\fP), wire fee and closing fee as arguments. +Instead of a year, the string \fBnow\fP 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 \fBCURRENCY:NUMBER.FRACTION\fP\&. +.sp +The subcommand takes no inputs from \fBstdin\fP or other subcommands. +.sp +It outputs the signature affirming the wire fees, in a format suitable for the +\fBupload\fP subcommand. +.SS upload +.sp +This subcommand uploads outputs from other subcommands (except \fBdownload\fP and \fBshow\fP) +to the exchange. Note that it is possible that some uploads succeed, while others +fail, as the operation is not atomic. +.sp +The subcommand takes no arguments and has no output. +.SS help +.sp +This subcommand shows a summary of all available subcommands with the +required arguments. +.SH EXAMPLES +.SS Download future public keys from an exchange (online) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline download > keys.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Show information about future public keys (offline or online) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline show < keys.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Sign future public keys (offline) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline sign < keys.json > sigs.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Upload signatures about future public keys (online) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline upload < sigs.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Download, sign and upload, all in one (online) +.sp +Note that doing this is only recommended in non\-production deployments. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline download sign upload +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Here is a variant that shows the output of \fBdownload\fP, but does not consume it, +so that \fBsign\fP can see it as input, as in the variant without \fBshow\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline download show \- sign upload +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Create signature to enable bank account (offline) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline enable\-account payto://iban/DE24242 > account.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Upload bank account signature (online) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline upload < account.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Combine signing keys and enabling bank account (offline) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline sign enable\-account payto://iban/DE24242 < keys.json > combo.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Upload various signatures (online) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline upload < combo.json +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Create multiple revocation messages in one pass (offline) +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ 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 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The outputs (“revoke.json”, “mix.json”) must be uploaded using the \fBupload\fP +subcommand to the exchange to actually revoke the keys. +.SH SECURITY CONSIDERATIONS +.sp +The \fBtaler\-exchange\-offline\fP tool assumes that it is run on a high\-security +system with \fImonotonic time\fP\&. 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. +.sp +The \fBtaler\-exchange\-offline\fP 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 \fBtaler\-exchange\-httpd\fP +but \fInot\fP the security modules from providing attacker\-controlled keys to the +offline signing process. +.sp +For this, the \fBtaler\-exchange\-offline\fP signing subcommand always +automatically learns the security module’s public signing key and \fItrusts it +on first use\fP (TOFU), but stores it to disk (see the \fBSECM_TOFU_FILE\fP option +in the \fB[exchange\-offline]\fP section of the configuration). If the keys +change subsequently, the tool will refuse to sign. +.SH SEE ALSO +.sp +taler\-exchange\-httpd(1), taler\-auditor\-offline(1), taler\-auditor\-exchange(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. |