taler-exchange-offline.1.rst (22945B)
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 * ``open-banking-gateway`` $URL: specifies an 279 URL where wallets can find an open banking gateway to 280 initiate wire transfers when withdrawing digital cash 281 from this exchange. Optional (as obviously not every 282 exchange will have an open banking gateway attached). 283 284 * ``wire-transfer-gateway`` $URL: specifies a 285 wire transfer gateway base URL where wallets and merchants can 286 request (short) wire transfer subjects to wire funds to this 287 exchange without having to encode the full public key. 288 See also design document 80. 289 290 * ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should 291 be shown to the user with the given numeric $PRIORITY (higher is earlier, zero is hidden for manual withdrawal) 292 and with the given $LABEL. This is useful to ensure that if an exchange 293 has multiple bank accounts, we can show the user those that are most likely 294 useful first, and give them appropriately labeled hints for selecting other 295 accounts as well. A display hint is optional, if missing the priority is 1 296 and the wallet must pick some appropriate label itself somehow. 297 298 * ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are 299 restrictions in place when crediting this bank account. Details depend on 300 the restriction $TYPE. This argument may be given multiple times, in which 301 case debitor accounts must satisfy all restrictions. Restriction types are 302 discussed below. 303 304 * ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions 305 in place when receiving money from the exchange. Wallets and merchants 306 must check that their target bank account satisfies these restrictions 307 before sending deposit requests to the exchange. Details depend on the 308 restriction $TYPE. This argument may be given multiple times, in which 309 case debitor accounts must satisfy all restrictions. Restriction types are 310 discussed below. 311 312 The following types of credit- and debit-restrictions are supported: 313 314 * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used 315 for the given operation. ``deny`` takes no further arguments. 316 317 * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's 318 bank account ``payto``-URI representation must follow a certain regular 319 expression given in $EXPR where the syntax follows posix-egrep, but 320 without support for character classes, GNU extensions, back-references or 321 intervals. See 322 `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ 323 for a description of the posix-egrep syntax. The $HINT must be a 324 human-readable description of the $EXPR. $JSON should be a JSON array 325 mapping IETF BCP 47 language tags to localized versions of $HINT. 326 327 The subcommand takes no inputs from ``stdin`` or other subcommands. 328 329 It outputs the signature affirming the addition of the wire account, 330 in a format suitable for the ``upload`` subcommand. 331 332 disable-account 333 --------------- 334 335 This subcommand 336 informs an exchange that it should stop advertising a bank account as 337 belonging to the exchange on its ``/keys`` endpoint. 338 339 The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be 340 given as the first argument to the subcommand. 341 342 The subcommand takes no inputs from ``stdin`` or other subcommands. 343 344 It outputs the signature affirming the deletion of the wire account, in a 345 format suitable for the ``upload`` subcommand. 346 347 348 wire-fee 349 -------- 350 351 This subcommand informs an exchange about the desired wire fee structure (that is, wire, and closing fees) 352 for particular wire method and a calendar year (!). The tool does not 353 permit changing wire fees during a calendar year. Also, once the wire fee has been 354 set for a calendar year, it cannot be changed. 355 356 The subcommand takes the year, wire-method (see RFC 8905, examples include 357 ``x-taler-bank`` or ``iban``), wire fee, and closing fee as arguments. 358 Instead of a year, the string ``now`` can be given for the current year 359 (this is mostly useful for test cases). The wire-method should follow the 360 GANA registry as given in RFC 8905. The fees must be given in the usual 361 Taler format of ``CURRENCY:NUMBER.FRACTION``. 362 363 The subcommand takes no inputs from ``stdin`` or other subcommands. 364 365 It outputs the signature affirming the wire fees, in a format suitable for the 366 ``upload`` subcommand. 367 368 369 global-fee 370 ---------- 371 372 This subcommand informs an exchange about the desired global fee structure and 373 related global configuration options for a calendar year (!). The tool does 374 not permit changing global fees during a calendar year. Also, once the global 375 fee structure has been set for a calendar year, it cannot be changed. 376 377 The subcommand takes the year, history fee, account fee, purse fee, 378 purse timeout, history expiration and the (free) purse (per) 379 account limit as arguments. Instead of a year, the string ``now`` can be 380 given for the current year (this is mostly useful for test cases). The fees 381 must be given in the usual Taler format of ``CURRENCY:NUMBER.FRACTION``. 382 383 The arguments provided must include: 384 385 (1) Calendar year for which the fee applies, 'now' for the current year. 386 (2) History fee charged when inquiring about non-recent account history (not implemented, use zero!) 387 (3) Account fee charged for opening an account (not supported by wallet, use zero!) 388 (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!) 389 (5) Purse timeout. How long does the exchange keep information about a purse around after it expired or was successfully merged? 390 (6) How long will the exchange preserve an account history. 391 (7) Number of free purses per account. (Irrelevant if purse fee is zero). 392 393 The subcommand takes no inputs from ``stdin`` or other subcommands. 394 395 It outputs the signature affirming the global fees, in a format suitable for 396 the ``upload`` subcommand. 397 398 399 enable-partner 400 -------------- 401 402 This subcommand informs an exchange about the wad fee and frequency to apply 403 to a partner exchange. The arguments provided must include: 404 405 (1) Partner exchange base URL. 406 (2) Partner exchange master public key. 407 (3) Calendar year for which the fee applies, 'now' for the current year. 408 (4) Wad frequency, in minutes (for example, '30'). 409 (5) Wad fee (for example, 'KUDOS:0.1'). 410 411 412 aml-enable 413 ---------- 414 415 Enable AML officer's account, granting them access to AML data and, 416 if 'rw' is given, the power to make AML decisions. 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 (3) 'ro' or 'rw' to set access to read-only or read-write 423 424 425 aml-disable 426 ----------- 427 428 Disable AML officer's account. Also updates the legal name. 429 430 The arguments provided must include: 431 432 (1) AML staff member public key (in base32 encoding) 433 (2) AML staff member legal name 434 435 436 add-partner 437 ----------- 438 439 Add partner exchange for wad transfers. Enables P2P payments 440 between users of these exchanges. 441 442 The arguments provided must include: 443 444 (1) Master public key of the partner exchange. 445 (2) Base URL of the partner exchange API. 446 (3) Wad fee to charge. 447 (4) Wad transfer frequency. 448 (5) Year for which the above options are to be configured, 'now' for the current year. 449 450 451 upload 452 ------ 453 454 This subcommand uploads outputs from other subcommands (except ``download`` and ``show``) 455 to the exchange. Note that it is possible that some uploads succeed, while others 456 fail, as the operation is not atomic. 457 458 The subcommand takes no arguments and has no output. 459 460 461 help 462 ---- 463 464 This subcommand shows a summary of all available subcommands with the 465 required arguments. 466 467 468 469 Examples 470 ======== 471 472 Download future public keys from an exchange (online) 473 ----------------------------------------------------- 474 475 .. code-block:: console 476 477 $ taler-exchange-offline download > keys.json 478 479 Show information about future public keys (offline or online) 480 ------------------------------------------------------------- 481 482 .. code-block:: console 483 484 $ taler-exchange-offline show < keys.json 485 486 Sign future public keys (offline) 487 --------------------------------- 488 489 .. code-block:: console 490 491 $ taler-exchange-offline sign < keys.json > sigs.json 492 493 Upload signatures about future public keys (online) 494 --------------------------------------------------- 495 496 .. code-block:: console 497 498 $ taler-exchange-offline upload < sigs.json 499 500 Download, sign and upload, all in one (online) 501 ---------------------------------------------- 502 503 Note that doing this is only recommended in non-production deployments, 504 as this requires putting the "offline" key onto a system that is actually 505 online! 506 507 .. code-block:: console 508 509 $ taler-exchange-offline \ 510 download \ 511 sign \ 512 upload 513 514 Here is a variant that shows the output of ``download``, but does not consume it, 515 so that ``sign`` can see it as input, as in the variant without ``show``. 516 517 .. code-block:: console 518 519 $ taler-exchange-offline \ 520 download \ 521 show - \ 522 sign \ 523 upload 524 525 526 Create signature to enable bank account (offline) 527 ------------------------------------------------- 528 529 The following command sets up an unrestricted simple exchange bank account 530 without conversion: 531 532 .. code-block:: console 533 534 $ taler-exchange-offline \ 535 enable-account payto://iban/DE24242?receiver-name=operator > account.json 536 537 The following command would set up an exchange bank account with conversion 538 and restrict it to only receive money from Switzerland and deny its use for 539 debit operations: 540 541 .. code-block:: shell-session 542 543 $ taler-exchange-offline \ 544 enable-account payto://x-taler-bank/example.com/?receiver-name=name \ 545 conversion-url http://conversion.exchange.com/ \ 546 debit-restriction \ 547 deny \ 548 credit-restriction \ 549 regex \ 550 'payto://iban/.*/CH.*?receiver-name=.*' \ 551 'Swiss only' \ 552 '{ "de" : "nur Schweiz", \ 553 "fr" : "Suisse uniquement" }' 554 555 556 Upload bank account signature (online) 557 -------------------------------------- 558 559 .. code-block:: console 560 561 $ taler-exchange-offline upload < account.json 562 563 564 Combine signing keys and enabling bank account (offline) 565 -------------------------------------------------------- 566 567 You can chain multiple commands into one invocation: 568 569 .. code-block:: console 570 571 $ taler-exchange-offline \ 572 sign \ 573 enable-account \ 574 payto://iban/DE24242 < keys.json > combo.json 575 576 Note that ``sign`` must be first as it consumes the ``keys.json`` 577 input. The resulting output combines the outputs of the ``sign`` 578 and ``enable-account`` subcommands. 579 580 581 Upload various signatures (online) 582 ---------------------------------- 583 584 .. code-block:: console 585 586 $ taler-exchange-offline upload < combo.json 587 588 Create multiple revocation messages in one pass (offline) 589 --------------------------------------------------------- 590 591 You can freely combine almost all commands, including those for 592 key revocation: 593 594 .. code-block:: console 595 596 $ taler-exchange-offline \ 597 revoke-denomination $DKH1 \ 598 revoke-denomination $DKH2 > revoke.json 599 $ taler-exchange-offline \ 600 revoke-signkey $SK1 \ 601 revoke-signkey $SK2 > revoke.json 602 $ taler-exchange-offline \ 603 revoke-signkey $SK \ 604 revoke-denomkey $DKH > mix.json 605 606 The outputs ("revoke.json", "mix.json") must be uploaded using the ``upload`` 607 subcommand to the exchange to actually revoke the keys. 608 609 610 611 Security considerations 612 ======================= 613 614 The **taler-exchange-offline** tool assumes that it is run on a high-security 615 system with *monotonic time*. The time does not have to precisely match that 616 of the exchange, but it must be monotonic across tool invocations. The clock 617 of the offline system is used in the enable/disable signatures to communicate 618 an order of the events to the exchange. This prevents someone from replaying 619 an older "enable" (or "disable") message after a more recent "disable" (or 620 "enable") message has been provided to the exchange. Thus, there is no need 621 to keep the actual files exchanged with the offline tool secret. 622 623 The **taler-exchange-offline** tool tries to make sure that the online signing 624 keys of the exchange are always created by the same two security modules. 625 The goal here is to prevent an attacker who compromised **taler-exchange-httpd** 626 but *not* the security modules from providing attacker-controlled keys to the 627 offline signing process. 628 629 For this, the **taler-exchange-offline** signing subcommand always 630 automatically learns the security module's public signing key and *trusts it 631 on first use* (TOFU), but stores it to disk (see the ``SECM_TOFU_FILE`` option 632 in the ``[exchange-offline]`` section of the configuration). If the keys 633 change subsequently, the tool will refuse to sign. 634 635 636 637 See Also 638 ======== 639 640 taler-exchange-httpd(1), taler-auditor-offline(1), taler-exchange.conf(5). 641 642 Bugs 643 ==== 644 645 Report bugs by using https://bugs.taler.net/ or by sending electronic 646 mail to <taler@gnu.org>.