taler-exchange.conf.5.rst (27346B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2014-2024 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Florian Dold 17 @author Benedikt Muller 18 @author Sree Harsha Totakura 19 @author Marcello Stanisci 20 @author Christian Grothoff 21 @author Javier Sepulveda 22 23 24 taler-exchange.conf(5) 25 ###################### 26 27 .. only:: html 28 29 Name 30 ==== 31 32 **taler-exchange.conf** - Taler exchange configuration file 33 34 35 Description 36 =========== 37 38 .. include:: ../frags/common-conf-syntax.rst 39 40 Files containing default values for many of the options described below 41 are installed under ``$TALER_EXCHANGE_PREFIX/share/taler-exchange/config.d/``. 42 The configuration file given with **-c** to Taler binaries 43 overrides these defaults. 44 45 A configuration file may include another, by using the ``@INLINE@`` directive, 46 for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to 47 include the entirety of ``sub.conf`` at that point in ``main.conf``. 48 49 Be extra careful when using ``taler-exchange-config -V VALUE`` to change configuration 50 values: it will destroy all uses of ``@INLINE@`` and furthermore remove all 51 comments from the configuration file! 52 53 54 GLOBAL OPTIONS 55 -------------- 56 57 The “[PATHS]” section is special in that it contains paths that can be 58 referenced using “$” in other configuration values that specify 59 filenames. For Taler exchange, it commonly contains the following paths: 60 61 TALER_HOME 62 Home directory of the user, usually “${HOME}”. Can be overwritten by 63 testcases by setting ${TALER_TEST_HOME}. 64 65 TALER_DATA_HOME 66 Where should Taler store its long-term data. 67 Usually “${TALER_HOME}/.local/share/taler-exchange/”. 68 69 TALER_CONFIG_HOME 70 Where is the Taler configuration kept. 71 Usually “${TALER_HOME}/.config/taler-exchange/”. 72 73 TALER_CACHE_HOME 74 Where should Taler store cached data. 75 Usually “${TALER_HOME}/.cache/taler-exchange/”. 76 77 TALER_RUNTIME_DIR 78 Where should Taler store system runtime data (like UNIX domain 79 sockets). Usually “${TMP}/taler-exchange-runtime”. 80 81 82 .. include:: frags/currency-spec.rst 83 84 EXCHANGE OPTIONS 85 ---------------- 86 87 The following options are from the “[exchange]” section and used by most 88 exchange tools. 89 90 CURRENCY 91 Name of the currency, e.g. “EUR” for Euro. 92 93 CURRENCY_ROUND_UNIT 94 Smallest amount in this currency that can be transferred using the 95 underlying RTGS. For example: "EUR:0.01" or "JPY:1". 96 97 DB 98 Plugin to use for the database, e.g. “postgres”. 99 100 ATTRIBUTE_ENCRYPTION_KEY 101 Attribute encryption key for storing attributes encrypted 102 in the database. Should be a high-entropy nonce. 103 104 SERVE 105 Should the HTTP server listen on a UNIX domain socket (set option to "unix"), or on a TCP socket (set option to "tcp"), or be activated via systemd (set option to "systemd"). 106 107 UNIXPATH 108 Path to listen on if we "SERVE" is set to "unix". 109 110 UNIXPATH_MODE 111 Access permission mask to use for the "UNIXPATH". 112 113 PORT 114 Port on which the HTTP server listens, e.g. 8080. 115 116 BIND_TO 117 Hostname to which the exchange HTTP server should be bound to, e.g. "localhost". 118 119 MASTER_PUBLIC_KEY 120 Crockford Base32-encoded master public key, public version of the 121 exchange's long-time offline signing key. This configuration option 122 is also used by the **auditor** to determine the public key of the 123 exchange which it is auditing. 124 125 TINY_AMOUNT 126 Smallest amount that can likely be transferred to the exchange. 127 This value is published in the exchange's ``/keys`` response (as 128 ``tiny_amount``) and is used in several places, for example as the 129 default amount for KYC authentication wire transfers and by the 130 auditor when reconciling incoming wire transfers. Because it is not 131 specific to KYC, this option must be configured even when KYC is 132 disabled (``ENABLE_KYC`` not set). 133 134 SHOPPING_URL 135 Web URL where users can discover shops that accept digital cash 136 offered by this exchange. Optional, but highly recommended. 137 138 AML_SPA_DIALECT 139 Determines the variant of the AML SPA that should be shown. This 140 will determine the set of forms shown to AML staff, statistics to 141 be displayed on the main page, and influence the default set of 142 properties/events the AML forms show when AML staff makes decisions. 143 Possible values for now include "tops" and "magnet". 144 Optional. The AML SPA will only show certain default forms and 145 generic decisions if this option is not set. 146 147 GLOBAL_PDF_FORM_DATA 148 Set to a JSON object that should be provided as additional input 149 to the PDF form generation logic when generating AML records in 150 PDF format. Useful to specify global attributes for the Typst forms. 151 Optional, global PDF form data injection will simply be off if 152 this option is not specified. 153 154 BANK_COMPLIANCE_LANGUAGE 155 Determines the legal language (and possibly other UI/UX aspects) 156 wallets should use when providing the user interface for this bank. 157 Allows banks to communicate the desired compliance language they 158 want to see used to the wallet. Wallets SHOULD follow the guidance 159 provided by the bank, but some wallets MAY not understand all compliance 160 languages. Optional, if not set wallets will use their default UI/UX. 161 162 STEFAN_ABS 163 Absolute amount to add as an offset in the STEFAN fee approximation 164 curve (see DD47). Defaults to CURRENCY:0 if not specified. 165 166 STEFAN_LOG 167 Amount to multiply by the base-2 logarithm of the total amount 168 divided by the amount of the smallest denomination 169 in the STEFAN fee approximation curve (see DD47). 170 Defaults to CURRENCY:0 if not specified. 171 172 STEFAN_LIN 173 Linear floating point factor to be multiplied by the total amount 174 to use in the STEFAN fee approximation curve (see DD47). 175 Defaults to 0.0 if not specified. 176 177 BASE_URL 178 The base URL under which the exchange can be reached. 179 Added to wire transfers to enable tracking by merchants. 180 Used by the KYC logic when interacting with OAuth 2.0. 181 182 TOPLEVEL_REDIRECT_URL 183 Where to redirect visitors that access the top-level 184 "/" endpoint of the exchange. Should point users to 185 information about the exchange operator. 186 Optional setting, defaults to "/terms". 187 188 AGGREGATOR_IDLE_SLEEP_INTERVAL 189 For how long should the taler-exchange-aggregator sleep when it is idle 190 before trying to look for more work? Default is 60 seconds. 191 192 CLOSER_IDLE_SLEEP_INTERVAL 193 For how long should the taler-exchange-closer sleep when it is idle 194 before trying to look for more work? Default is 60 seconds. 195 196 TRANSFER_IDLE_SLEEP_INTERVAL 197 For how long should the taler-exchange-transfer sleep when it is idle 198 before trying to look for more work? Default is 60 seconds. 199 200 WIREWATCH_IDLE_SLEEP_INTERVAL 201 For how long should the taler-exchange-wirewatch sleep when it is idle 202 before trying to look for more work? Default is 60 seconds. 203 204 AGGREGATOR_SHARD_SIZE 205 Which share of the range from [0,..2147483648] should be processed by one of the shards of the aggregator. Useful only for Taler exchanges with ultra high-performance needs. When changing this value, you must stop all aggregators and run "taler-exchange-dbinit -s" before resuming. Default is 2147483648 (no sharding). 206 207 SIGNKEY_LEGAL_DURATION 208 For how long are signatures with signing keys legally valid? 209 210 MAX_KEYS_CACHING 211 For how long should clients cache ``/keys`` responses at most? 212 213 MAX_REQUESTS 214 How many requests should the HTTP server process at most before committing suicide? 215 216 TERMS_DIR 217 Directory where the terms of service of the exchange operator can be fund. 218 The directory must contain sub-directories for every supported language, 219 using the two-character language code in lower case, e.g. "en/" or "fr/". 220 Each subdirectory must then contain files with the terms of service in 221 various formats. The basename of the file of the current policy must be 222 specified under ``TERMS_ETAG``. The extension defines the mime type. 223 Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", 224 "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure 225 could be the following: 226 227 - $TERMS_DIR/en/0.pdf 228 - $TERMS_DIR/en/0.html 229 - $TERMS_DIR/en/0.txt 230 - $TERMS_DIR/fr/0.pdf 231 - $TERMS_DIR/fr/0.html 232 - $TERMS_DIR/de/0.txt 233 234 TERMS_ETAG 235 Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service. 236 The value is also used for the "Etag" in the HTTP request to control 237 caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also 238 change, and old values MUST NOT be repeated. For example, the date or 239 version number of the terms of service SHOULD be used for the Etag. If 240 there are minor (e.g. spelling) fixes to the terms of service, the 241 ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must 242 approve the new terms, the ``TERMS_ETAG`` MUST change. 243 244 PRIVACY_DIR 245 Works the same as ``TERMS_DIR``, just for the privacy policy. 246 247 PRIVACY_ETAG 248 Works the same as ``TERMS_ETAG``, just for the privacy policy. 249 250 ENABLE_KYC 251 Must be set to ``YES`` to enable AML/KYC rule enforcement. Note that the administrative endpoints will always work, even if the flag is set to ``NO``. 252 253 KYC_SWAP_TOS_ACCEPTANCE 254 Set to ``YES`` to signal to the merchant backend that it should 255 swap the terms-of-service and KYC auth authentication steps in 256 the user experience. Optional, defaults to ``NO``. 257 258 DISABLE_DIRECT_DEPOSIT 259 Set to ``YES`` to indicate to wallets that deposits by non-merchants 260 are not supported. Defaults to ``NO``. 261 262 263 EXCHANGE KYC PROVIDER OPTIONS 264 ----------------------------- 265 266 The following options must be in the section "[kyc-provider-$PROVIDER_NAME]" sections. 267 268 LOGIC 269 API type of the KYC provider. 270 271 KYC_PROCESS_TIMEOUT 272 Maximum time for which the exchange reuses an unfinished KYC process if 273 the provider does not report the process's own expiration time. Once this 274 timeout passes, starting KYC creates a fresh provider process instead of 275 returning the old redirect URL. Must be finite and non-zero. Optional, 276 defaults to 1 day. A provider-reported expiration takes precedence. 277 278 Additional logic-specific options may be given in the 279 section. 280 281 282 EXCHANGE KYC OAUTH2 OPTIONS 283 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 284 285 The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = oauth2". 286 287 288 KYC_OAUTH2_VALIDITY 289 Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". 290 291 KYC_OAUTH2_AUTHORIZE_URL 292 URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is where the exchange will redirect the client to begin the authorization process. Example: "http://localhost:8888/oauth/v2/authorize". To use the plugin in combination with the Challenger service's ``/setup`` step, append "#setup", thus "https://challenger.example.com/authorize#setup". Here, "#setup" is not a fragment but merely a hint to the logic to determine the full authorization URL via the ``/setup/$CLIENT_ID`` handler. 293 294 KYC_OAUTH2_TOKEN_URL 295 URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a "bearer" token). Example: "http://localhost:8888/oauth/v2/token" (or just "/token") 296 297 KYC_OAUTH2_INFO_URL 298 URL of the OAuth2-protected resource endpoint, where the OAuth 2.0 token can be used to download information about the user that has undergone the KYC process. The exchange will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: "http://localhost:8888/api/user/me" or "http://localhost:8888/oauth/v2/info" 299 300 KYC_OAUTH2_CLIENT_ID 301 Client ID of the exchange when it talks to the KYC OAuth2 endpoint. 302 303 KYC_OAUTH2_CLIENT_SECRET 304 Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. 305 306 KYC_OAUTH2_SCOPE 307 Scope argument to pass in the Oauth2 /authorize request. 308 Optional, if not given no scope will be provided. 309 310 KYC_OAUTH2_POST_URL 311 URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. Example: "http://example.com/thank-you" 312 313 KYC_OAUTH2_CONVERTER_HELPER 314 Helper to convert JSON with KYC data returned by the OAuth2.0 info endpoint into GNU Taler internal format. Specific to the OAuth 2.0 provider. 315 316 KYC_OAUTH2_DEBUG_MODE 317 Set to YES to allow error responses to include potentially 318 sensitive private information (such as full responses 319 from the OAuth 2.0 server) that might aid in debugging 320 problems. Should be set to "NO" in production. 321 322 323 EXCHANGE KYC KYCAID OPTIONS 324 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 325 326 The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = kycaid". 327 328 329 KYC_KYCAID_VALIDITY 330 Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". 331 332 KYC_KYCAID_AUTH_TOKEN 333 Authentication token to access the KYC service. 334 335 KYC_KYCAID_CONVERTER_HELPER 336 Helper to convert JSON with KYC data returned by KYCAID into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-kycaid-converter.sh". 337 338 KYC_KYCAID_FORM_ID 339 ID that specifies the form to use for the KYC process. 340 341 KYC_KYCAID_POST_URL 342 URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. 343 344 345 EXCHANGE KYC PERSONA OPTIONS 346 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 347 348 The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = persona". 349 350 351 KYC_PERSONA_VALIDITY 352 Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". 353 354 KYC_PERSONA_AUTH_TOKEN 355 Authentication token to access the KYC service. 356 357 KYC_PERSONA_SALT 358 Salt value to use for request idempotency. Optional, generated at random per process if not given. 359 360 KYC_PERSONA_SUBDOMAIN 361 Subdomain to use under Persona. 362 363 KYC_PERSONA_CONVERTER_HELPER 364 Helper to convert JSON with KYC data returned by Persona into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-persona-converter.sh". 365 366 KYC_PERSONA_POST_URL 367 URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. 368 369 KYC_PERSONA_TEMPLATE_ID 370 ID of the Persona template to use. 371 372 EXCHANGE KYC PERSONA GLOBAL OPTIONS 373 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 374 375 The following option must be in the section "[kyclogic-persona]". 376 377 378 WEBHOOK_AUTH_TOKEN 379 Authentication token Persona must supply to our webhook. This is an optional setting. 380 381 382 EXCHANGE KYC CHECK OPTIONS 383 -------------------------- 384 385 The following options must be in "[kyc-check-$CHECK_NAME]" sections. 386 387 TYPE 388 Which type of check is this? Also determines 389 the SPA form to show to the user for this check. 390 391 * INFO: wait for staff or contact staff out-of band 392 (only information shown, no SPA action) 393 * FORM: SPA should show an inline (HTML) form 394 * LINK: SPA may start external KYC process or upload 395 396 PROVIDER_ID 397 Provider id, present only if type is LINK. 398 Refers to a ``kyc-provider-$PROVIDER_ID`` section. 399 400 FORM_NAME 401 Name of the SPA form, if type is FORM 402 "INFO" and "LINK" are reserved and must not be used. 403 The exchange server and the SPA must agree on a list 404 of supported forms and the resulting attributes. 405 The SPA should include a JSON resource file 406 "forms.json" mapping form names to arrays of 407 attribute names each form provides. 408 The list of possible FORM names is fixed in the SPA 409 for a particular exchange release. 410 411 DESCRIPTION 412 Descriptions to use in the SPA to display the check. 413 414 DESCRIPTION_I18N 415 JSON with internationalized descriptions to use 416 in the SPA to display the check. 417 418 REQUIRES 419 ';'-separated list of fields that the CONTEXT must 420 provide as inputs to this check. For example, 421 for a FORM of type CHOICE, this might state 422 ``choices: string[];``. The type after the ":" 423 is for now purely for documentation and is 424 not checked. However, it may be shown to AML staff 425 when they configure measures. 426 427 OUTPUTS = "business_name street city country registration" 428 Description of the outputs provided by the check. 429 Basically, the check's output is expected to 430 provide the following fields as attribute inputs into 431 a subsequent AML program. INFO never has any outputs. 432 433 FALLBACK 434 Name of an **original** measure to take if the check fails 435 (for any reason, e.g. provider or form fail to 436 satisfy constraints or provider signals user error) 437 Usually should point to a measure that requests 438 AML staff to investigate. The fallback measure 439 context always includes the reasons for the 440 failure. 441 442 EXCHANGE KYC RULES 443 ------------------ 444 445 The following options must be in "[kyc-rule-$RULE_NAME]" sections. 446 447 OPERATION_TYPE = WITHDRAW 448 Operation that triggers this rule. 449 Must be one of AGGREGATE, BALANCE, CLOSE, DEPOSIT, MERGE, 450 REFUND, TRANSACTION or WITHDRAW 451 See the Exchange KYC/AML Operator Manual for the 452 operations these refer to. 453 454 NEXT_MEASURES 455 Space-separated list of next measures to be performed. 456 The SPA should display *all* of these measures to the user. 457 (They have a choice of either which ones, or in 458 which order they are to be performed.) 459 A special measure name "verboten" is used if the 460 specified threshold may never be crossed 461 (under this set of rules). This option is equivalent 462 to the "new_measure" string in an AmlDecisionRequest 463 (with IS_AND_COMBINATOR replacing the "+"-prefix). 464 465 IS_AND_COMBINATOR 466 "YES" if all NEXT_MEASURES will eventually need 467 to be satisfied, "NO" the user has a choice between 468 them. Not actually enforced by the exchange, but 469 primarily used to inform the user whether this is 470 an "and" or "or". YES for "and". 471 472 EXPOSED 473 YES if the rule (specifically, operation type, 474 threshold, timeframe) and the general nature of 475 the next measure (verboten or approval required) 476 should be exposed to the client. 477 Defaults to NO if not set. 478 479 THRESHOLD 480 Threshold amount above which the rule is 481 triggered. The total must be exceeded in the given 482 timeframe. 483 484 TIMEFRAME 485 Timeframe over which the amount to be compared to 486 the THRESHOLD is calculated (for example, "30 days"). 487 Ignored for BALANCE. Can be 'forever'. 488 489 ENABLED = NO 490 Set to YES to enable the rule (default is NO). 491 492 493 EXCHANGE AML PROGRAMS 494 --------------------- 495 496 The following options must be in "[aml-program-$PROG_NAME]" sections. 497 498 COMMAND 499 Name of the program to run. Must match a binary 500 on the local machine where the exchange is running. 501 502 DESCRIPTION 503 Human-readable description of what this 504 AML helper program will do. Used to show 505 to the AML staff. 506 507 ENABLED 508 True if this AML program is enabled (and thus can be 509 used in measures and exposed to AML staff). 510 Optional, default is NO. 511 512 FALLBACK 513 Name of an **original** measure to take if COMMAND fails 514 Usually points to a measure that asks AML staff 515 to contact the systems administrator. The fallback measure 516 context always includes the reasons for the 517 failure. 518 519 EXCHANGE KYC MEASURES 520 --------------------- 521 522 The following options must be in "[kyc-measure-$MEASURE_NAME]" sections. 523 These sections define the **original** measures. 524 525 CHECK_NAME 526 Name of a possible check for this measure. Optional. 527 If not given or set to ``SKIP``, PROGRAM should be run immediately 528 (on an empty set of attributes). 529 530 CONTEXT = {"choices":["individual","business"]} 531 Context for the check. The context can be 532 just an empty JSON object if there is none. 533 534 PROGRAM 535 Program to run on the context and check data to 536 determine the outcome and next measure. 537 Refers to a ``[aml-program-$PROG_NAME]`` section name. 538 539 VOLUNTARY 540 Optional. Set to YES to allow this measure to be 541 done voluntarily by a client. Used to offer the 542 SPA to display measures even if they are 543 not required. Default is NO. 544 545 546 547 AGE_RESTRICTION_ENABLED 548 Set to ``YES`` to enable age restriction on coins. When age restriction is 549 active, certain denominations can be marked with ``AGE_RESTRICTED = YES`` 550 (see `EXCHANGE COIN OPTIONS`_) and wallets must include an age commitment 551 when withdrawing or spending such coins. Default is ``NO``. 552 553 AGE_GROUPS 554 Only meaningful when ``AGE_RESTRICTION_ENABLED = YES``. 555 A colon-separated string of increasing non-negative integers defining the 556 age-group boundaries. Each integer marks the start of the next group; the 557 zero'th group begins implicitly at 0. For example ``"10:18"`` defines three 558 groups: 559 560 1. Group 0: ages 0 through 9 (inclusive) 561 2. Group 1: ages 10 through 17 (inclusive) 562 3. Group 2: ages 18 and above 563 564 If not given the default value ``"8:10:12:14:16:18:21"`` is used. 565 566 567 EXCHANGE OFFLINE SIGNING OPTIONS 568 -------------------------------- 569 570 The following options must be in the section "[exchange-offline]". 571 572 MASTER_PRIV_FILE 573 Location of the master private key on disk. Only used by tools that 574 can be run offline (as the master key is for offline signing). 575 Mandatory. 576 577 SECM_TOFU_FILE 578 Where to store the public keys of both crypto helper modules. 579 Used to persist the keys after the first invocation of the tool, 580 so that if they ever change in the future, this is detected and 581 the tool can abort. 582 Mandatory. 583 584 SECM_DENOM_PUBKEY 585 Public key of the (RSA) crypto helper module. Optional. If not given, 586 we will rely on TOFU. Note that once TOFU has been established, 587 this option will also be ignored. 588 589 SECM_ESIGN_PUBKEY 590 Public key of the (EdDSA) crypto helper module. Optional. If not given, 591 we will rely on TOFU. Note that once TOFU has been established, 592 this option will also be ignored. 593 594 595 EXCHANGE RSA CRYPTO HELPER OPTIONS 596 ---------------------------------- 597 598 The following options must be in the section "[taler-exchange-secmod-rsa]". 599 600 LOOKAHEAD_SIGN 601 How long do we generate denomination and signing keys ahead of time? 602 603 OVERLAP_DURATION 604 How much should validity periods for coins overlap? 605 Should be long enough to avoid problems with 606 wallets picking one key and then due to network latency 607 another key being valid. The ``DURATION_WITHDRAW`` period 608 must be longer than this value. 609 610 SM_PRIV_KEY 611 Where should the security module store its long-term private key? 612 613 KEY_DIR 614 Where should the security module store the private keys it manages? 615 616 UNIXPATH 617 On which path should the security module listen for signing requests? 618 619 Note that the **taler-exchange-secmod-rsa** also evaluates the ``[coin_*]`` 620 configuration sections described below. 621 622 623 EXCHANGE CS CRYPTO HELPER OPTIONS 624 --------------------------------- 625 626 The following options must be in the section "[taler-exchange-secmod-cs]". 627 628 LOOKAHEAD_SIGN 629 How long do we generate denomination and signing keys ahead of time? 630 631 OVERLAP_DURATION 632 How much should validity periods for coins overlap? 633 Should be long enough to avoid problems with 634 wallets picking one key and then due to network latency 635 another key being valid. The ``DURATION_WITHDRAW`` period 636 must be longer than this value. 637 638 SM_PRIV_KEY 639 Where should the security module store its long-term private key? 640 641 KEY_DIR 642 Where should the security module store the private keys it manages? 643 644 UNIXPATH 645 On which path should the security module listen for signing requests? 646 647 Note that the **taler-exchange-secmod-cs** also evaluates the ``[coin_*]`` 648 configuration sections described below. 649 650 651 652 EXCHANGE EDDSA CRYPTO HELPER OPTIONS 653 ------------------------------------ 654 655 The following options must be in the section "[taler-exchange-secmod-eddsa]". 656 657 LOOKAHEAD_SIGN 658 How long do we generate denomination and signing keys ahead of time? 659 660 OVERLAP_DURATION 661 How much should validity periods for coins overlap? 662 Should be long enough to avoid problems with 663 wallets picking one key and then due to network latency 664 another key being valid. The ``DURATION_WITHDRAW`` period 665 must be longer than this value. 666 667 DURATION 668 For how long should EdDSA keys be valid for signing? 669 670 SM_PRIV_KEY 671 Where should the security module store its long-term private key? 672 673 KEY_DIR 674 Where should the security module store the private keys it manages? 675 676 UNIXPATH 677 On which path should the security module listen for signing requests? 678 679 .. include:: frags/exchange-database.rst 680 .. include:: frags/exchange-account.rst 681 .. include:: frags/exchange-coin.rst 682 683 EXCHANGE SANCTIONSCHECK OPTIONS 684 ------------------------------- 685 686 This section configures the taler-exchange-sanctionlist tool to enforce 687 sanctions. The tool scores KYC records in two dimensions, the quality 688 of the match (rating) and the number of attributes that were found in 689 both sets (confidence). 690 691 The following options must be in the section "[exchange-sanctionscheck]". 692 693 RATER_COMMAND 694 Program (and command-line arguments) for the helper program to 695 execute to compare sanction list records. Usually set to 696 something like "robocop $SANCTIONLIST.json", but can be any 697 program that reads KYC attributes in JSON line-by-line and 698 outputs a rating (0-1), confidence (0-1) and free-form sanction list 699 identifier for each JSON input received. 700 701 MIN_ROW_FILENAME 702 Name of the file where taler-exchange-sanctionscheck will store the 703 last row process during sanction list evaluation. Not in thed atabase 704 as we frequently need to reset it when we get a new list, so no 705 transactionality is needed or even desirable. There should be no 706 need to change the default. 707 708 FREEZE_RATING_LIMIT 709 Match quality rating (on a scale of [0,1]) that must be exceeded 710 for the exchange to automatically freeze an account. The account 711 must satisfy both the rating limit and the confidence limit to be 712 frozen. 713 714 FREEZE_CONFIDENCE_LIMIT 715 Match confidence rating (on a scale of [0,1]) that must be exceeded 716 for the exchange to automatically freeze an account. A rating of 0 717 means no attributes were available, while a rating of 1 indicates that 718 we could compare the acconts across all dimensions. 719 720 INVESTIGATION_LIMIT 721 Limit (on a scale of [0,1]) that must be exceeded for an account to 722 be flagged for manual investigation. Only applies of the account 723 is not automatically frozen. The limit given is compared against 724 the quality rating divided by the confidence score. 725 If set at 0.95, a modest 0.8 match with low 0.5 confidence will 726 trigger (1.6 > 0.95), but a good 0.9 match with a super-high 1.0 727 confidence would not (0.9 < 0.95). On the other hand, a bad 0.2 match 728 with super-low 0.1 confidence would again trigger (2.0 > 0.95). 729 730 INVESTIGATION_CONFIDENCE_LIMIT 731 Match confidence limit (on a scale of [0,1]) that must be exceeded for the 732 exchange to flag an account for investigation according to the 733 rules for INVESTIGATION_LIMIT. 734 735 736 SEE ALSO 737 ======== 738 739 taler-exchange-dbinit(1), taler-exchange-httpd(1), taler-exchange-offline(1), taler-exchange-sanctionscheck(1) 740 741 BUGS 742 ==== 743 744 Report bugs by using https://bugs.taler.net/ or by sending electronic 745 mail to <taler@gnu.org>.