diff options
Diffstat (limited to 'man/taler-exchange-offline.1')
| -rw-r--r-- | man/taler-exchange-offline.1 | 94 |
1 files changed, 55 insertions, 39 deletions
diff --git a/man/taler-exchange-offline.1 b/man/taler-exchange-offline.1 index 104e54ee..da91e9d8 100644 --- a/man/taler-exchange-offline.1 +++ b/man/taler-exchange-offline.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-OFFLINE" "1" "Jun 20, 2022" "0.9" "GNU Taler" +.TH "TALER-EXCHANGE-OFFLINE" "1" "Jul 06, 2022" "0.9" "GNU Taler" .SH NAME taler-exchange-offline \- operations using the offline key of a Taler exchange . @@ -33,21 +33,21 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .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 ...] +[\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\(aqs master private key. Most operations of this tool require access to +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\(aqs +The tool includes two subcommands to interact \fIonline\fP with the exchange’s REST APIs. To determine how to talk to the exchange, these two subcommands rely on the \fBBASE_URL\fP configuration option from the \fB[exchange]\fP section of the configuration file. The \fBdownload\fP subcommand downloads the future @@ -55,10 +55,10 @@ 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 +\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 +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 @@ -68,21 +68,21 @@ and if not consumed the final output is printed to \fBstdout\fP\&. The general options for \fBtaler\-exchange\-offline\fP are: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB\-\-config=\fP\fIFILENAME\fP +\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 +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB\-\-loglevel=\fP\fILOGLEVEL\fP +\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 +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-v\fP | \fB\-\-version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH CONFIGURATION @@ -102,17 +102,17 @@ $ taler\-exchange\-offline setup .UNINDENT .sp Note that if the private key file already exists, the above will simply output -the existing key. Passing additional arguments after setup (including "\-") +the existing key. Passing additional arguments after setup (including “\-“) will cause the output to be encapsulated in JSON. .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) +\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 +\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 +\fB[exchange\-offline/SECM_TOFU_FILE]\fP — where to store TOFU data .UNINDENT .SH SUBCOMMANDS .SS setup @@ -150,6 +150,22 @@ 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 extensions +.sp +This subcommand is responsible for the management of available extensions in +the exchange. +.sp +It consumes the output of the \fBdownload\fP subcommand, either from \fBstdin\fP or +directly. +.sp +It provides the sub\-subcommand \fBextensions show\fP to show the configuration +for extensions and the \fBextensions sign\fP command to sign the current +configuration of extensions, in a format suitable for the \fBupload\fP +subcommand. +.sp +Note that an extension on the exchange will only become activated at runtime +\fIafter\fP the extension’s configurations has been signed by the offline tool with +the signing key and the signed configuration been uploaded to the exchange. .SS revoke\-denomination .sp This subcommand signs a revocation message for a denomination key. @@ -172,23 +188,23 @@ in a format suitable for the \fBupload\fP subcommand. .sp This subcommand informs an exchange that an auditor is to be activated. Afterwards, the -exchange will accept inputs from that auditor\(aqs \fBtaler\-auditor\-offline\fP +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\(aqs database will need to be provided to the auditor. This subcommand +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\(aqs public key must be given in the usual base32\-encoding as the +The auditor’s public key must be given in the usual base32\-encoding as the first argument. .sp -The auditor\(aqs 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 +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\(aqs business entity. If +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. @@ -199,10 +215,10 @@ in a format suitable for the \fBupload\fP subcommand. .sp This subcommand informs an exchange that an auditor is to be deactivated. Afterwards, the -exchange will refuse inputs from that auditor\(aqs \fBtaler\-auditor\-offline\fP +exchange will refuse inputs from that auditor’s \fBtaler\-auditor\-offline\fP tool. .sp -The auditor\(aqs public key must be given in the usual base32\-encoding as the +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. @@ -221,7 +237,7 @@ account information advertized 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 accounts. .sp -The \fBpayto://\fP URI (RFC 8905) of the exchange\(aqs bank account must be given +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. @@ -234,7 +250,7 @@ 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\(aqs (former) bank account must be +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. @@ -288,11 +304,11 @@ Partner exchange base URL. .IP 2. 3 Partner exchange master public key. .IP 3. 3 -Calendar year for which the fee applies, \(aqnow\(aq for the current year. +Calendar year for which the fee applies, ‘now’ for the current year. .IP 4. 3 -Wad frequency, in minutes (for example, \(aq30\(aq). +Wad frequency, in minutes (for example, ‘30’). .IP 5. 3 -Wad fee (for example, \(aqKUDOS:0.1\(aq). +Wad fee (for example, ‘KUDOS:0.1’). .UNINDENT .UNINDENT .UNINDENT @@ -305,7 +321,7 @@ The arguments provided must include: .INDENT 3.5 .INDENT 0.0 .IP 1. 3 -Calendar year for which the fee applies, \(aqnow\(aq for the current year. +Calendar year for which the fee applies, ‘now’ for the current year. .IP 2. 3 KYC timeout. How long does the exchange keep a reserve open that is waiting for the KYC. .IP 3. 3 @@ -465,7 +481,7 @@ $ taler\-exchange\-offline revoke\-signkey $SK revoke\-denomkey $DKH > mix.json .UNINDENT .UNINDENT .sp -The outputs ("revoke.json", "mix.json") must be uploaded using the \fBupload\fP +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 @@ -474,8 +490,8 @@ system with \fImonotonic time\fP\&. The time does not have to precisely match th 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 +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 @@ -485,7 +501,7 @@ but \fInot\fP the security modules from providing attacker\-controlled keys to t offline signing process. .sp For this, the \fBtaler\-exchange\-offline\fP signing subcommand always -automatically learns the security module\(aqs public signing key and \fItrusts it +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. |