taler-exchange-offline.1.rst (22392B)
1 taler-exchange-offline(1) 2 ######################### 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **taler-exchange-offline** - perform operations with exchange offline master private key 10 11 Synopsis 12 ======== 13 14 **taler-exchange-offline** 15 [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] 16 [**-h** | **--help**] 17 [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] 18 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] 19 [**-v** | **--version**] 20 [subcommand ...] 21 22 23 Description 24 =========== 25 26 **taler-exchange-offline** is a command-line tool to interact with the Taler 27 exchange's master private key. Most operations of this tool require access to 28 the exchange’s long-term offline signing key and should be run in a secure 29 (offline) environment under strict controls. The tool takes a list of 30 subcommands as arguments which are then processed sequentially. 31 32 The tool includes two subcommands to interact *online* with the exchange's 33 REST APIs. To determine how to talk to the exchange, these two subcommands 34 rely on the ``BASE_URL`` configuration option from the ``[exchange]`` section 35 of the configuration file. The ``download`` subcommand downloads the future 36 public keys from the running exchange. The resulting data serves as input to 37 the ``sign`` and ``show`` subcommands. The ``upload`` subcommand uploads the 38 signatures created with the private master key to the exchange. It handles 39 the output of all subcommands (except ``download``). The ``download`` and 40 ``upload`` subcommands must naturally be run "online" and do not require 41 access to the offline key. 42 43 All other subcommands are intended to be run "offline". However, especially 44 when testing, it is of course possible to run the subcommands online as well. 45 Generally, subcommands read inputs (beyond command-line arguments) 46 from ``stdin``. However, they may also consume outputs of previous 47 subcommands. The outputs of multiple subcommands are automatically combined, 48 and if not consumed the final output is printed to ``stdout``. 49 50 51 The general options for **taler-exchange-offline** are: 52 53 **-c** *FILENAME* \| **--config=**\ \ *FILENAME* 54 Use the configuration and other resources for the merchant to operate 55 from *FILENAME*. 56 57 **-h** \| **--help** 58 Print short help on options. 59 60 **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* 61 Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, 62 ``WARNING``, ``ERROR``. 63 64 **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* 65 Send logging output to *FILENAME*. 66 67 **-v** \| **--version** 68 Print version information. 69 70 71 Configuration 72 ============= 73 74 The exchange validates all operations by checking the signatures against the 75 master public key that must be provided in the exchange configuration. To 76 obtain the master public key, use: 77 78 .. code-block:: console 79 80 $ taler-exchange-offline setup 81 82 Note that if the private key file already exists, the above will simply output 83 the existing key. Passing additional arguments after setup (including "-") 84 will cause the output to be encapsulated in JSON. 85 86 87 Relevant configuration options for **taler-exchange-offline** are: 88 89 * ``[exchange/BASE_URL]`` --- how to reach the exchange (for download/upload) 90 * ``[exchange-offline/MASTER_PRIV_FILE]`` --- where to store the private keys 91 * ``[exchange-offline/SECM_TOFU_FILE]`` --- where to store TOFU data 92 93 94 95 Subcommands 96 =========== 97 98 setup 99 ----- 100 101 When run the first time, this subcommand sets up the offline private key and 102 outputs the resulting public key. Subsequent invocations will simply again 103 output the (same) public key (in the format usable for the exchange 104 configuration). 105 106 107 download 108 -------- 109 110 This subcommand must be run online. It downloads future signing and denomination 111 keys with the associated meta data from the exchange and outputs the resulting 112 JSON (for consumption by subsequent subcommands, or to ``stdout``). 113 114 115 show 116 ---- 117 118 This subcommand outputs information about future signing and denomination keys for 119 manual checking against the business-approved fee structure, lifetimes and 120 other parameters. 121 122 It consumes the output of the ``download`` subcommand, either from ``stdin`` or 123 directly. 124 However, if given arg ``-`` (hyphen), this input is not consumed, 125 but instead is passed to the next command. This functions like the 126 tee(1) command. 127 128 Its output always goes to ``stdout`` for human consumption (not in JSON). It 129 is usually a bad idea (but possible) to combine ``show`` with other subcommands, 130 except maybe for testing. 131 132 133 sign 134 ---- 135 136 This subcommand signs information about future signing and denomination keys. 137 138 It consumes the output of the ``download`` subcommand, either from ``stdin`` or 139 directly. 140 141 It outputs the signatures over *all* denomination and signing keys 142 present in the input, in a format suitable for the ``upload`` subcommand. 143 144 145 extensions 146 ---------- 147 148 This subcommand is responsible for the management of available extensions in 149 the exchange. 150 151 It consumes the output of the ``download`` subcommand, either from ``stdin`` or 152 directly. 153 154 It provides the sub-subcommand ``extensions show`` to show the configuration 155 for extensions and the ``extensions sign`` command to sign the current 156 configuration of extensions, in a format suitable for the ``upload`` 157 subcommand. 158 159 Note that an extension on the exchange will only become activated at runtime 160 *after* the extension's configurations has been signed by the offline tool with 161 the signing key and the signed configuration been uploaded to the exchange. 162 163 drain 164 ----- 165 166 This subcommand allows an exchange operator to transfer the 167 profits made from transaction fees to a regular (non-escrowed) bank 168 account. Using this command, draining profits from the 169 escrow account can be done in such a way that the auditor 170 is aware of the special transaction and does not flag the 171 resulting balance as fundamentally problematic. Note that 172 the drained amounts must still total up to less than the fees 173 earned by the exchange. 174 175 Arguments to the ``drain`` command are the amount to be drained (in the usual 176 Taler amount format), the section of the exchange configuration specifying the 177 account to be debited (this argument is currently ignored, and the account is 178 purely derived from the wire method and the account being set for debiting), 179 and finally the payto://-URI to wire the funds to. 180 181 Note that to actually wire the funds, the exchange administrator must run 182 **taler-exchange-drain** manually and confirm the operation after the 183 ``upload`` was completed. 184 185 186 revoke-denomination 187 ------------------- 188 189 This subcommand signs a revocation message for a denomination key. 190 191 The hash of the denomination public key must be given in the usual 192 base32-encoding as the first and only argument to the subcommand. 193 194 It outputs the signature affirming the revocation of the denomination key, 195 in a format suitable for the ``upload`` subcommand. 196 197 198 revoke-signkey 199 -------------- 200 201 This subcommand signs a revocation message for an exchange online signing key. 202 203 The online signing public key must be given in the usual 204 base32-encoding as the first and only argument to the subcommand. 205 206 It outputs the signature affirming the revocation of the online signing key, 207 in a format suitable for the ``upload`` subcommand. 208 209 210 211 enable-auditor 212 -------------- 213 214 This subcommand 215 informs an exchange that an auditor is to be activated. Afterwards, the 216 exchange will accept inputs from that auditor's **taler-auditor-offline** 217 tool. The exchange's database will need to be provided to the auditor. This 218 subcommand only informs the exchange about the auditor, but does not perform 219 those additional mandatory steps for a working auditor. 220 221 The auditor's public key must be given in the usual base32-encoding as the 222 first argument. 223 224 The auditor's REST API base URL must be given as the second argument. The tool 225 performs a minimal sanity check, namely that the URL begins with "http" 226 (this also allows "https"), but as it runs offline does not perform any further 227 validation! 228 229 The third argument must be a human-readable name for the auditor. This may 230 be shown to users and should identify the auditor's business entity. If 231 the name includes spaces, the argument should be quoted. 232 233 The subcommand takes no inputs from ``stdin`` or other subcommands. 234 235 It outputs the signature affirming the addition of the auditor, 236 in a format suitable for the ``upload`` subcommand. 237 238 239 disable-auditor 240 --------------- 241 242 This subcommand 243 informs an exchange that an auditor is to be deactivated. Afterwards, the 244 exchange will refuse inputs from that auditor's **taler-auditor-offline** 245 tool. 246 247 The auditor's public key must be given in the usual base32-encoding as the 248 first argument. 249 250 The subcommand takes no inputs from ``stdin`` or other subcommands. 251 252 It outputs the signature affirming the removal of the auditor, 253 in a format suitable for the ``upload`` subcommand. 254 255 256 enable-account 257 -------------- 258 259 This subcommand informs an exchange that it should advertise a bank account as 260 belonging to the exchange on its ``/keys`` endpoint. Note that this does 261 *not* ensure that the exchange will use this bank account for incoming or 262 outgoing wire transfers! For this, the **taler-exchange-transfer** and 263 **taler-exchange-wirewatch** tools must be configured. Furthermore, the bank 264 account information advertised could theoretically differ from that which 265 these tool actually use, for example if the public bank account is only a 266 front for the actual internal business accounts. 267 268 The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given 269 as the first argument to the subcommand. 270 271 Afterwards, optional arguments can be given: 272 273 * ``conversion-url`` $URL: specifies that using this bank account is subject 274 to currency conversion. $URL must be the address of a currency conversion 275 REST API that allows merchants and wallets to determine the current 276 conversion rate. 277 278 * ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should 279 be shown to the user with the given numeric $PRIORITY (higher is earlier, zero is hidden for manual withdrawal) 280 and with the given $LABEL. This is useful to ensure that if an exchange 281 has multiple bank accounts, we can show the user those that are most likely 282 useful first, and give them appropriately labeled hints for selecting other 283 accounts as well. A display hint is optional, if missing the priority is 1 284 and the wallet must pick some appropriate label itself somehow. 285 286 * ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are 287 restrictions in place when crediting this bank account. Details depend on 288 the restriction $TYPE. This argument may be given multiple times, in which 289 case debitor accounts must satisfy all restrictions. Restriction types are 290 discussed below. 291 292 * ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions 293 in place when receiving money from the exchange. Wallets and merchants 294 must check that their target bank account satisfies these restrictions 295 before sending deposit requests to the exchange. Details depend on the 296 restriction $TYPE. This argument may be given multiple times, in which 297 case debitor accounts must satisfy all restrictions. Restriction types are 298 discussed below. 299 300 The following types of credit- and debit-restrictions are supported: 301 302 * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used 303 for the given operation. ``deny`` takes no further arguments. 304 305 * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's 306 bank account ``payto``-URI representation must follow a certain regular 307 expression given in $EXPR where the syntax follows posix-egrep, but 308 without support for character classes, GNU extensions, back-references or 309 intervals. See 310 `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ 311 for a description of the posix-egrep syntax. The $HINT must be a 312 human-readable description of the $EXPR. $JSON should be a JSON array 313 mapping IETF BCP 47 language tags to localized versions of $HINT. 314 315 The subcommand takes no inputs from ``stdin`` or other subcommands. 316 317 It outputs the signature affirming the addition of the wire account, 318 in a format suitable for the ``upload`` subcommand. 319 320 disable-account 321 --------------- 322 323 This subcommand 324 informs an exchange that it should stop advertising a bank account as 325 belonging to the exchange on its ``/keys`` endpoint. 326 327 The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be 328 given as the first argument to the subcommand. 329 330 The subcommand takes no inputs from ``stdin`` or other subcommands. 331 332 It outputs the signature affirming the deletion of the wire account, in a 333 format suitable for the ``upload`` subcommand. 334 335 336 wire-fee 337 -------- 338 339 This subcommand informs an exchange about the desired wire fee structure (that is, wire, and closing fees) 340 for particular wire method and a calendar year (!). The tool does not 341 permit changing wire fees during a calendar year. Also, once the wire fee has been 342 set for a calendar year, it cannot be changed. 343 344 The subcommand takes the year, wire-method (see RFC 8905, examples include 345 ``x-taler-bank`` or ``iban``), wire fee, and closing fee as arguments. 346 Instead of a year, the string ``now`` can be given for the current year 347 (this is mostly useful for test cases). The wire-method should follow the 348 GANA registry as given in RFC 8905. The fees must be given in the usual 349 Taler format of ``CURRENCY:NUMBER.FRACTION``. 350 351 The subcommand takes no inputs from ``stdin`` or other subcommands. 352 353 It outputs the signature affirming the wire fees, in a format suitable for the 354 ``upload`` subcommand. 355 356 357 global-fee 358 ---------- 359 360 This subcommand informs an exchange about the desired global fee structure and 361 related global configuration options for a calendar year (!). The tool does 362 not permit changing global fees during a calendar year. Also, once the global 363 fee structure has been set for a calendar year, it cannot be changed. 364 365 The subcommand takes the year, history fee, account fee, purse fee, 366 purse timeout, history expiration and the (free) purse (per) 367 account limit as arguments. Instead of a year, the string ``now`` can be 368 given for the current year (this is mostly useful for test cases). The fees 369 must be given in the usual Taler format of ``CURRENCY:NUMBER.FRACTION``. 370 371 The arguments provided must include: 372 373 (1) Calendar year for which the fee applies, 'now' for the current year. 374 (2) History fee charged when inquiring about non-recent account history (not implemented, use zero!) 375 (3) Account fee charged for opening an account (not supported by wallet, use zero!) 376 (4) Purse fee. How much will the exchange charge for an abandoned purse. Also the minimum amount that can be in a purse that is not associated with an account. (Not well supported by wallets, use zero!) 377 (5) Purse timeout. How long does the exchange keep information about a purse around after it expired or was successfully merged? 378 (6) How long will the exchange preserve an account history. 379 (7) Number of free purses per account. (Irrelevant if purse fee is zero). 380 381 The subcommand takes no inputs from ``stdin`` or other subcommands. 382 383 It outputs the signature affirming the global fees, in a format suitable for 384 the ``upload`` subcommand. 385 386 387 enable-partner 388 -------------- 389 390 This subcommand informs an exchange about the wad fee and frequency to apply 391 to a partner exchange. The arguments provided must include: 392 393 (1) Partner exchange base URL. 394 (2) Partner exchange master public key. 395 (3) Calendar year for which the fee applies, 'now' for the current year. 396 (4) Wad frequency, in minutes (for example, '30'). 397 (5) Wad fee (for example, 'KUDOS:0.1'). 398 399 400 aml-enable 401 ---------- 402 403 Enable AML officer's account, granting them access to AML data and, 404 if 'rw' is given, the power to make AML decisions. 405 406 The arguments provided must include: 407 408 (1) AML staff member public key (in base32 encoding) 409 (2) AML staff member legal name 410 (3) 'ro' or 'rw' to set access to read-only or read-write 411 412 413 aml-disable 414 ----------- 415 416 Disable AML officer's account. Also updates the legal name. 417 418 The arguments provided must include: 419 420 (1) AML staff member public key (in base32 encoding) 421 (2) AML staff member legal name 422 423 424 add-partner 425 ----------- 426 427 Add partner exchange for wad transfers. Enables P2P payments 428 between users of these exchanges. 429 430 The arguments provided must include: 431 432 (1) Master public key of the partner exchange. 433 (2) Base URL of the partner exchange API. 434 (3) Wad fee to charge. 435 (4) Wad transfer frequency. 436 (5) Year for which the above options are to be configured, 'now' for the current year. 437 438 439 upload 440 ------ 441 442 This subcommand uploads outputs from other subcommands (except ``download`` and ``show``) 443 to the exchange. Note that it is possible that some uploads succeed, while others 444 fail, as the operation is not atomic. 445 446 The subcommand takes no arguments and has no output. 447 448 449 help 450 ---- 451 452 This subcommand shows a summary of all available subcommands with the 453 required arguments. 454 455 456 457 Examples 458 ======== 459 460 Download future public keys from an exchange (online) 461 ----------------------------------------------------- 462 463 .. code-block:: console 464 465 $ taler-exchange-offline download > keys.json 466 467 Show information about future public keys (offline or online) 468 ------------------------------------------------------------- 469 470 .. code-block:: console 471 472 $ taler-exchange-offline show < keys.json 473 474 Sign future public keys (offline) 475 --------------------------------- 476 477 .. code-block:: console 478 479 $ taler-exchange-offline sign < keys.json > sigs.json 480 481 Upload signatures about future public keys (online) 482 --------------------------------------------------- 483 484 .. code-block:: console 485 486 $ taler-exchange-offline upload < sigs.json 487 488 Download, sign and upload, all in one (online) 489 ---------------------------------------------- 490 491 Note that doing this is only recommended in non-production deployments, 492 as this requires putting the "offline" key onto a system that is actually 493 online! 494 495 .. code-block:: console 496 497 $ taler-exchange-offline \ 498 download \ 499 sign \ 500 upload 501 502 Here is a variant that shows the output of ``download``, but does not consume it, 503 so that ``sign`` can see it as input, as in the variant without ``show``. 504 505 .. code-block:: console 506 507 $ taler-exchange-offline \ 508 download \ 509 show - \ 510 sign \ 511 upload 512 513 514 Create signature to enable bank account (offline) 515 ------------------------------------------------- 516 517 The following command sets up an unrestricted simple exchange bank account 518 without conversion: 519 520 .. code-block:: console 521 522 $ taler-exchange-offline \ 523 enable-account payto://iban/DE24242?receiver-name=operator > account.json 524 525 The following command would set up an exchange bank account with conversion 526 and restrict it to only receive money from Switzerland and deny its use for 527 debit operations: 528 529 .. code-block:: shell-session 530 531 $ taler-exchange-offline \ 532 enable-account payto://x-taler-bank/example.com/?receiver-name=name \ 533 conversion-url http://conversion.exchange.com/ \ 534 debit-restriction \ 535 deny \ 536 credit-restriction \ 537 regex \ 538 'payto://iban/.*/CH.*?receiver-name=.*' \ 539 'Swiss only' \ 540 '{ "de" : "nur Schweiz", \ 541 "fr" : "Suisse uniquement" }' 542 543 544 Upload bank account signature (online) 545 -------------------------------------- 546 547 .. code-block:: console 548 549 $ taler-exchange-offline upload < account.json 550 551 552 Combine signing keys and enabling bank account (offline) 553 -------------------------------------------------------- 554 555 You can chain multiple commands into one invocation: 556 557 .. code-block:: console 558 559 $ taler-exchange-offline \ 560 sign \ 561 enable-account \ 562 payto://iban/DE24242 < keys.json > combo.json 563 564 Note that ``sign`` must be first as it consumes the ``keys.json`` 565 input. The resulting output combines the outputs of the ``sign`` 566 and ``enable-account`` subcommands. 567 568 569 Upload various signatures (online) 570 ---------------------------------- 571 572 .. code-block:: console 573 574 $ taler-exchange-offline upload < combo.json 575 576 Create multiple revocation messages in one pass (offline) 577 --------------------------------------------------------- 578 579 You can freely combine almost all commands, including those for 580 key revocation: 581 582 .. code-block:: console 583 584 $ taler-exchange-offline \ 585 revoke-denomination $DKH1 \ 586 revoke-denomination $DKH2 > revoke.json 587 $ taler-exchange-offline \ 588 revoke-signkey $SK1 \ 589 revoke-signkey $SK2 > revoke.json 590 $ taler-exchange-offline \ 591 revoke-signkey $SK \ 592 revoke-denomkey $DKH > mix.json 593 594 The outputs ("revoke.json", "mix.json") must be uploaded using the ``upload`` 595 subcommand to the exchange to actually revoke the keys. 596 597 598 599 Security considerations 600 ======================= 601 602 The **taler-exchange-offline** tool assumes that it is run on a high-security 603 system with *monotonic time*. The time does not have to precisely match that 604 of the exchange, but it must be monotonic across tool invocations. The clock 605 of the offline system is used in the enable/disable signatures to communicate 606 an order of the events to the exchange. This prevents someone from replaying 607 an older "enable" (or "disable") message after a more recent "disable" (or 608 "enable") message has been provided to the exchange. Thus, there is no need 609 to keep the actual files exchanged with the offline tool secret. 610 611 The **taler-exchange-offline** tool tries to make sure that the online signing 612 keys of the exchange are always created by the same two security modules. 613 The goal here is to prevent an attacker who compromised **taler-exchange-httpd** 614 but *not* the security modules from providing attacker-controlled keys to the 615 offline signing process. 616 617 For this, the **taler-exchange-offline** signing subcommand always 618 automatically learns the security module's public signing key and *trusts it 619 on first use* (TOFU), but stores it to disk (see the ``SECM_TOFU_FILE`` option 620 in the ``[exchange-offline]`` section of the configuration). If the keys 621 change subsequently, the tool will refuse to sign. 622 623 624 625 See Also 626 ======== 627 628 taler-exchange-httpd(1), taler-auditor-offline(1), taler-exchange.conf(5). 629 630 Bugs 631 ==== 632 633 Report bugs by using https://bugs.taler.net/ or by sending electronic 634 mail to <taler@gnu.org>.