taler-exchange-offline.1.rst (22275B)
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 drain 146 ----- 147 148 This subcommand allows an exchange operator to transfer the 149 profits made from transaction fees to a regular (non-escrowed) bank 150 account. Using this command, draining profits from the 151 escrow account can be done in such a way that the auditor 152 is aware of the special transaction and does not flag the 153 resulting balance as fundamentally problematic. Note that 154 the drained amounts must still total up to less than the fees 155 earned by the exchange. 156 157 Arguments to the ``drain`` command are the amount to be drained (in the usual 158 Taler amount format), the section of the exchange configuration specifying the 159 account to be debited (this argument is currently ignored, and the account is 160 purely derived from the wire method and the account being set for debiting), 161 and finally the payto://-URI to wire the funds to. 162 163 Note that to actually wire the funds, the exchange administrator must run 164 **taler-exchange-drain** manually and confirm the operation after the 165 ``upload`` was completed. 166 167 168 revoke-denomination 169 ------------------- 170 171 This subcommand signs a revocation message for a denomination key. 172 173 The hash of the denomination public key must be given in the usual 174 base32-encoding as the first and only argument to the subcommand. 175 176 It outputs the signature affirming the revocation of the denomination key, 177 in a format suitable for the ``upload`` subcommand. 178 179 180 revoke-signkey 181 -------------- 182 183 This subcommand signs a revocation message for an exchange online signing key. 184 185 The online signing public key must be given in the usual 186 base32-encoding as the first and only argument to the subcommand. 187 188 It outputs the signature affirming the revocation of the online signing key, 189 in a format suitable for the ``upload`` subcommand. 190 191 192 193 enable-auditor 194 -------------- 195 196 This subcommand 197 informs an exchange that an auditor is to be activated. Afterwards, the 198 exchange will accept inputs from that auditor's **taler-auditor-offline** 199 tool. The exchange's database will need to be provided to the auditor. This 200 subcommand only informs the exchange about the auditor, but does not perform 201 those additional mandatory steps for a working auditor. 202 203 The auditor's public key must be given in the usual base32-encoding as the 204 first argument. 205 206 The auditor's REST API base URL must be given as the second argument. The tool 207 performs a minimal sanity check, namely that the URL begins with "http" 208 (this also allows "https"), but as it runs offline does not perform any further 209 validation! 210 211 The third argument must be a human-readable name for the auditor. This may 212 be shown to users and should identify the auditor's business entity. If 213 the name includes spaces, the argument should be quoted. 214 215 The subcommand takes no inputs from ``stdin`` or other subcommands. 216 217 It outputs the signature affirming the addition of the auditor, 218 in a format suitable for the ``upload`` subcommand. 219 220 221 disable-auditor 222 --------------- 223 224 This subcommand 225 informs an exchange that an auditor is to be deactivated. Afterwards, the 226 exchange will refuse inputs from that auditor's **taler-auditor-offline** 227 tool. 228 229 The auditor's public key must be given in the usual base32-encoding as the 230 first argument. 231 232 The subcommand takes no inputs from ``stdin`` or other subcommands. 233 234 It outputs the signature affirming the removal of the auditor, 235 in a format suitable for the ``upload`` subcommand. 236 237 238 enable-account 239 -------------- 240 241 This subcommand informs an exchange that it should advertise a bank account as 242 belonging to the exchange on its ``/keys`` endpoint. Note that this does 243 *not* ensure that the exchange will use this bank account for incoming or 244 outgoing wire transfers! For this, the **taler-exchange-transfer** and 245 **taler-exchange-wirewatch** tools must be configured. Furthermore, the bank 246 account information advertised could theoretically differ from that which 247 these tool actually use, for example if the public bank account is only a 248 front for the actual internal business accounts. 249 250 The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given 251 as the first argument to the subcommand. 252 253 Afterwards, optional arguments can be given: 254 255 * ``conversion-url`` $URL: specifies that using this bank account is subject 256 to currency conversion. $URL must be the address of a currency conversion 257 REST API that allows merchants and wallets to determine the current 258 conversion rate. 259 260 * ``open-banking-gateway`` $URL: specifies an 261 URL where wallets can find an open banking gateway to 262 initiate wire transfers when withdrawing digital cash 263 from this exchange. Optional (as obviously not every 264 exchange will have an open banking gateway attached). 265 266 * ``prepared-transfer-url`` $URL: specifies a 267 Prepared transfer API base URL where wallets and merchants can 268 request (short) wire transfer subjects to wire funds to this 269 exchange without having to encode the full public key. 270 See also design document 80. 271 272 * ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should 273 be shown to the user with the given numeric $PRIORITY (higher is earlier, zero is hidden for manual withdrawal) 274 and with the given $LABEL. This is useful to ensure that if an exchange 275 has multiple bank accounts, we can show the user those that are most likely 276 useful first, and give them appropriately labeled hints for selecting other 277 accounts as well. A display hint is optional, if missing the priority is 1 278 and the wallet must pick some appropriate label itself somehow. 279 280 * ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are 281 restrictions in place when crediting this bank account. Details depend on 282 the restriction $TYPE. This argument may be given multiple times, in which 283 case debitor accounts must satisfy all restrictions. Restriction types are 284 discussed below. 285 286 * ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions 287 in place when receiving money from the exchange. Wallets and merchants 288 must check that their target bank account satisfies these restrictions 289 before sending deposit requests to the exchange. Details depend on the 290 restriction $TYPE. This argument may be given multiple times, in which 291 case debitor accounts must satisfy all restrictions. Restriction types are 292 discussed below. 293 294 The following types of credit- and debit-restrictions are supported: 295 296 * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used 297 for the given operation. ``deny`` takes no further arguments. 298 299 * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's 300 bank account ``payto``-URI representation must follow a certain regular 301 expression given in $EXPR where the syntax follows posix-egrep, but 302 without support for character classes, GNU extensions, back-references or 303 intervals. See 304 `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ 305 for a description of the posix-egrep syntax. The $HINT must be a 306 human-readable description of the $EXPR. $JSON should be a JSON array 307 mapping IETF BCP 47 language tags to localized versions of $HINT. 308 309 The subcommand takes no inputs from ``stdin`` or other subcommands. 310 311 It outputs the signature affirming the addition of the wire account, 312 in a format suitable for the ``upload`` subcommand. 313 314 disable-account 315 --------------- 316 317 This subcommand 318 informs an exchange that it should stop advertising a bank account as 319 belonging to the exchange on its ``/keys`` endpoint. 320 321 The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be 322 given as the first argument to the subcommand. 323 324 The subcommand takes no inputs from ``stdin`` or other subcommands. 325 326 It outputs the signature affirming the deletion of the wire account, in a 327 format suitable for the ``upload`` subcommand. 328 329 330 wire-fee 331 -------- 332 333 This subcommand informs an exchange about the desired wire fee structure (that is, wire, and closing fees) 334 for particular wire method and a calendar year (!). The tool does not 335 permit changing wire fees during a calendar year. Also, once the wire fee has been 336 set for a calendar year, it cannot be changed. 337 338 The subcommand takes the year, wire-method (see RFC 8905, examples include 339 ``x-taler-bank`` or ``iban``), wire fee, and closing fee as arguments. 340 Instead of a year, the string ``now`` can be given for the current year 341 (this is mostly useful for test cases). The wire-method should follow the 342 GANA registry as given in RFC 8905. The fees must be given in the usual 343 Taler format of ``CURRENCY:NUMBER.FRACTION``. 344 345 The subcommand takes no inputs from ``stdin`` or other subcommands. 346 347 It outputs the signature affirming the wire fees, in a format suitable for the 348 ``upload`` subcommand. 349 350 351 global-fee 352 ---------- 353 354 This subcommand informs an exchange about the desired global fee structure and 355 related global configuration options for a calendar year (!). The tool does 356 not permit changing global fees during a calendar year. Also, once the global 357 fee structure has been set for a calendar year, it cannot be changed. 358 359 The subcommand takes the year, history fee, account fee, purse fee, 360 purse timeout, history expiration and the (free) purse (per) 361 account limit as arguments. Instead of a year, the string ``now`` can be 362 given for the current year (this is mostly useful for test cases). The fees 363 must be given in the usual Taler format of ``CURRENCY:NUMBER.FRACTION``. 364 365 The arguments provided must include: 366 367 (1) Calendar year for which the fee applies, 'now' for the current year. 368 (2) History fee charged when inquiring about non-recent account history (not implemented, use zero!) 369 (3) Account fee charged for opening an account (not supported by wallet, use zero!) 370 (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!) 371 (5) Purse timeout. How long does the exchange keep information about a purse around after it expired or was successfully merged? 372 (6) How long will the exchange preserve an account history. 373 (7) Number of free purses per account. (Irrelevant if purse fee is zero). 374 375 The subcommand takes no inputs from ``stdin`` or other subcommands. 376 377 It outputs the signature affirming the global fees, in a format suitable for 378 the ``upload`` subcommand. 379 380 381 enable-partner 382 -------------- 383 384 This subcommand informs an exchange about the wad fee and frequency to apply 385 to a partner exchange. The arguments provided must include: 386 387 (1) Partner exchange base URL. 388 (2) Partner exchange master public key. 389 (3) Calendar year for which the fee applies, 'now' for the current year. 390 (4) Wad frequency, in minutes (for example, '30'). 391 (5) Wad fee (for example, 'KUDOS:0.1'). 392 393 394 aml-enable 395 ---------- 396 397 Enable AML officer's account, granting them access to AML data and, 398 if 'rw' is given, the power to make AML decisions. 399 400 The arguments provided must include: 401 402 (1) AML staff member public key (in base32 encoding) 403 (2) AML staff member legal name 404 (3) 'ro' or 'rw' to set access to read-only or read-write 405 406 407 aml-disable 408 ----------- 409 410 Disable AML officer's account. Also updates the legal name. 411 412 The arguments provided must include: 413 414 (1) AML staff member public key (in base32 encoding) 415 (2) AML staff member legal name 416 417 418 add-partner 419 ----------- 420 421 Add partner exchange for wad transfers. Enables P2P payments 422 between users of these exchanges. 423 424 The arguments provided must include: 425 426 (1) Master public key of the partner exchange. 427 (2) Base URL of the partner exchange API. 428 (3) Wad fee to charge. 429 (4) Wad transfer frequency. 430 (5) Year for which the above options are to be configured, 'now' for the current year. 431 432 433 upload 434 ------ 435 436 This subcommand uploads outputs from other subcommands (except ``download`` and ``show``) 437 to the exchange. Note that it is possible that some uploads succeed, while others 438 fail, as the operation is not atomic. 439 440 The subcommand takes no arguments and has no output. 441 442 443 help 444 ---- 445 446 This subcommand shows a summary of all available subcommands with the 447 required arguments. 448 449 450 451 Examples 452 ======== 453 454 Download future public keys from an exchange (online) 455 ----------------------------------------------------- 456 457 .. code-block:: console 458 459 $ taler-exchange-offline download > keys.json 460 461 Show information about future public keys (offline or online) 462 ------------------------------------------------------------- 463 464 .. code-block:: console 465 466 $ taler-exchange-offline show < keys.json 467 468 Sign future public keys (offline) 469 --------------------------------- 470 471 .. code-block:: console 472 473 $ taler-exchange-offline sign < keys.json > sigs.json 474 475 Upload signatures about future public keys (online) 476 --------------------------------------------------- 477 478 .. code-block:: console 479 480 $ taler-exchange-offline upload < sigs.json 481 482 Download, sign and upload, all in one (online) 483 ---------------------------------------------- 484 485 Note that doing this is only recommended in non-production deployments, 486 as this requires putting the "offline" key onto a system that is actually 487 online! 488 489 .. code-block:: console 490 491 $ taler-exchange-offline \ 492 download \ 493 sign \ 494 upload 495 496 Here is a variant that shows the output of ``download``, but does not consume it, 497 so that ``sign`` can see it as input, as in the variant without ``show``. 498 499 .. code-block:: console 500 501 $ taler-exchange-offline \ 502 download \ 503 show - \ 504 sign \ 505 upload 506 507 508 Create signature to enable bank account (offline) 509 ------------------------------------------------- 510 511 The following command sets up an unrestricted simple exchange bank account 512 without conversion: 513 514 .. code-block:: console 515 516 $ taler-exchange-offline \ 517 enable-account payto://iban/DE24242?receiver-name=operator > account.json 518 519 The following command would set up an exchange bank account with conversion 520 and restrict it to only receive money from Switzerland and deny its use for 521 debit operations: 522 523 .. code-block:: shell-session 524 525 $ taler-exchange-offline \ 526 enable-account payto://x-taler-bank/example.com/?receiver-name=name \ 527 conversion-url http://conversion.exchange.com/ \ 528 debit-restriction \ 529 deny \ 530 credit-restriction \ 531 regex \ 532 'payto://iban/.*/CH.*?receiver-name=.*' \ 533 'Swiss only' \ 534 '{ "de" : "nur Schweiz", \ 535 "fr" : "Suisse uniquement" }' 536 537 538 Upload bank account signature (online) 539 -------------------------------------- 540 541 .. code-block:: console 542 543 $ taler-exchange-offline upload < account.json 544 545 546 Combine signing keys and enabling bank account (offline) 547 -------------------------------------------------------- 548 549 You can chain multiple commands into one invocation: 550 551 .. code-block:: console 552 553 $ taler-exchange-offline \ 554 sign \ 555 enable-account \ 556 payto://iban/DE24242 < keys.json > combo.json 557 558 Note that ``sign`` must be first as it consumes the ``keys.json`` 559 input. The resulting output combines the outputs of the ``sign`` 560 and ``enable-account`` subcommands. 561 562 563 Upload various signatures (online) 564 ---------------------------------- 565 566 .. code-block:: console 567 568 $ taler-exchange-offline upload < combo.json 569 570 Create multiple revocation messages in one pass (offline) 571 --------------------------------------------------------- 572 573 You can freely combine almost all commands, including those for 574 key revocation: 575 576 .. code-block:: console 577 578 $ taler-exchange-offline \ 579 revoke-denomination $DKH1 \ 580 revoke-denomination $DKH2 > revoke.json 581 $ taler-exchange-offline \ 582 revoke-signkey $SK1 \ 583 revoke-signkey $SK2 > revoke.json 584 $ taler-exchange-offline \ 585 revoke-signkey $SK \ 586 revoke-denomkey $DKH > mix.json 587 588 The outputs ("revoke.json", "mix.json") must be uploaded using the ``upload`` 589 subcommand to the exchange to actually revoke the keys. 590 591 592 593 Security considerations 594 ======================= 595 596 The **taler-exchange-offline** tool assumes that it is run on a high-security 597 system with *monotonic time*. The time does not have to precisely match that 598 of the exchange, but it must be monotonic across tool invocations. The clock 599 of the offline system is used in the enable/disable signatures to communicate 600 an order of the events to the exchange. This prevents someone from replaying 601 an older "enable" (or "disable") message after a more recent "disable" (or 602 "enable") message has been provided to the exchange. Thus, there is no need 603 to keep the actual files exchanged with the offline tool secret. 604 605 The **taler-exchange-offline** tool tries to make sure that the online signing 606 keys of the exchange are always created by the same two security modules. 607 The goal here is to prevent an attacker who compromised **taler-exchange-httpd** 608 but *not* the security modules from providing attacker-controlled keys to the 609 offline signing process. 610 611 For this, the **taler-exchange-offline** signing subcommand always 612 automatically learns the security module's public signing key and *trusts it 613 on first use* (TOFU), but stores it to disk (see the ``SECM_TOFU_FILE`` option 614 in the ``[exchange-offline]`` section of the configuration). If the keys 615 change subsequently, the tool will refuse to sign. 616 617 618 619 See Also 620 ======== 621 622 taler-exchange-httpd(1), taler-auditor-offline(1), taler-exchange.conf(5). 623 624 Bugs 625 ==== 626 627 Report bugs by using https://bugs.taler.net/ or by sending electronic 628 mail to <taler@gnu.org>.