taler-exchange.conf.5.rst (26753B)
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 2.1, 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 "gls", "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 Additional logic-specific options may be given in the 272 section. 273 274 275 EXCHANGE KYC OAUTH2 OPTIONS 276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 277 278 The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = oauth2". 279 280 281 KYC_OAUTH2_VALIDITY 282 Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". 283 284 KYC_OAUTH2_AUTHORIZE_URL 285 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. 286 287 KYC_OAUTH2_TOKEN_URL 288 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") 289 290 KYC_OAUTH2_INFO_URL 291 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" 292 293 KYC_OAUTH2_CLIENT_ID 294 Client ID of the exchange when it talks to the KYC OAuth2 endpoint. 295 296 KYC_OAUTH2_CLIENT_SECRET 297 Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. 298 299 KYC_OAUTH2_SCOPE 300 Scope argument to pass in the Oauth2 /authorize request. 301 Optional, if not given no scope will be provided. 302 303 KYC_OAUTH2_POST_URL 304 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" 305 306 KYC_OAUTH2_CONVERTER_HELPER 307 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. 308 309 KYC_OAUTH2_DEBUG_MODE 310 Set to YES to allow error responses to include potentially 311 sensitive private information (such as full responses 312 from the OAuth 2.0 server) that might aid in debugging 313 problems. Should be set to "NO" in production. 314 315 316 EXCHANGE KYC KYCAID OPTIONS 317 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 318 319 The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = kycaid". 320 321 322 KYC_KYCAID_VALIDITY 323 Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". 324 325 KYC_KYCAID_AUTH_TOKEN 326 Authentication token to access the KYC service. 327 328 KYC_KYCAID_CONVERTER_HELPER 329 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". 330 331 KYC_KYCAID_FORM_ID 332 ID that specifies the form to use for the KYC process. 333 334 KYC_KYCAID_POST_URL 335 URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. 336 337 338 EXCHANGE KYC PERSONA OPTIONS 339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 340 341 The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = persona". 342 343 344 KYC_PERSONA_VALIDITY 345 Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". 346 347 KYC_PERSONA_AUTH_TOKEN 348 Authentication token to access the KYC service. 349 350 KYC_PERSONA_SALT 351 Salt value to use for request idempotency. Optional, generated at random per process if not given. 352 353 KYC_PERSONA_SUBDOMAIN 354 Subdomain to use under Persona. 355 356 KYC_PERSONA_CONVERTER_HELPER 357 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". 358 359 KYC_PERSONA_POST_URL 360 URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. 361 362 KYC_PERSONA_TEMPLATE_ID 363 ID of the Persona template to use. 364 365 EXCHANGE KYC PERSONA GLOBAL OPTIONS 366 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 367 368 The following option must be in the section "[kyclogic-persona]". 369 370 371 WEBHOOK_AUTH_TOKEN 372 Authentication token Persona must supply to our webhook. This is an optional setting. 373 374 375 EXCHANGE KYC CHECK OPTIONS 376 -------------------------- 377 378 The following options must be in "[kyc-check-$CHECK_NAME]" sections. 379 380 TYPE 381 Which type of check is this? Also determines 382 the SPA form to show to the user for this check. 383 384 * INFO: wait for staff or contact staff out-of band 385 (only information shown, no SPA action) 386 * FORM: SPA should show an inline (HTML) form 387 * LINK: SPA may start external KYC process or upload 388 389 PROVIDER_ID 390 Provider id, present only if type is LINK. 391 Refers to a ``kyc-provider-$PROVIDER_ID`` section. 392 393 FORM_NAME 394 Name of the SPA form, if type is FORM 395 "INFO" and "LINK" are reserved and must not be used. 396 The exchange server and the SPA must agree on a list 397 of supported forms and the resulting attributes. 398 The SPA should include a JSON resource file 399 "forms.json" mapping form names to arrays of 400 attribute names each form provides. 401 The list of possible FORM names is fixed in the SPA 402 for a particular exchange release. 403 404 DESCRIPTION 405 Descriptions to use in the SPA to display the check. 406 407 DESCRIPTION_I18N 408 JSON with internationalized descriptions to use 409 in the SPA to display the check. 410 411 REQUIRES 412 ';'-separated list of fields that the CONTEXT must 413 provide as inputs to this check. For example, 414 for a FORM of type CHOICE, this might state 415 ``choices: string[];``. The type after the ":" 416 is for now purely for documentation and is 417 not checked. However, it may be shown to AML staff 418 when they configure measures. 419 420 OUTPUTS = "business_name street city country registration" 421 Description of the outputs provided by the check. 422 Basically, the check's output is expected to 423 provide the following fields as attribute inputs into 424 a subsequent AML program. INFO never has any outputs. 425 426 FALLBACK 427 Name of an **original** measure to take if the check fails 428 (for any reason, e.g. provider or form fail to 429 satisfy constraints or provider signals user error) 430 Usually should point to a measure that requests 431 AML staff to investigate. The fallback measure 432 context always includes the reasons for the 433 failure. 434 435 EXCHANGE KYC RULES 436 ------------------ 437 438 The following options must be in "[kyc-rule-$RULE_NAME]" sections. 439 440 OPERATION_TYPE = WITHDRAW 441 Operation that triggers this rule. 442 Must be one of AGGREGATE, BALANCE, CLOSE, DEPOSIT, MERGE, 443 REFUND, TRANSACTION or WITHDRAW 444 See the Exchange KYC/AML Operator Manual for the 445 operations these refer to. 446 447 NEXT_MEASURES 448 Space-separated list of next measures to be performed. 449 The SPA should display *all* of these measures to the user. 450 (They have a choice of either which ones, or in 451 which order they are to be performed.) 452 A special measure name "verboten" is used if the 453 specified threshold may never be crossed 454 (under this set of rules). This option is equivalent 455 to the "new_measure" string in an AmlDecisionRequest 456 (with IS_AND_COMBINATOR replacing the "+"-prefix). 457 458 IS_AND_COMBINATOR 459 "YES" if all NEXT_MEASURES will eventually need 460 to be satisfied, "NO" the user has a choice between 461 them. Not actually enforced by the exchange, but 462 primarily used to inform the user whether this is 463 an "and" or "or". YES for "and". 464 465 EXPOSED 466 YES if the rule (specifically, operation type, 467 threshold, timeframe) and the general nature of 468 the next measure (verboten or approval required) 469 should be exposed to the client. 470 Defaults to NO if not set. 471 472 THRESHOLD 473 Threshold amount above which the rule is 474 triggered. The total must be exceeded in the given 475 timeframe. 476 477 TIMEFRAME 478 Timeframe over which the amount to be compared to 479 the THRESHOLD is calculated (for example, "30 days"). 480 Ignored for BALANCE. Can be 'forever'. 481 482 ENABLED = NO 483 Set to YES to enable the rule (default is NO). 484 485 486 EXCHANGE AML PROGRAMS 487 --------------------- 488 489 The following options must be in "[aml-program-$PROG_NAME]" sections. 490 491 COMMAND 492 Name of the program to run. Must match a binary 493 on the local machine where the exchange is running. 494 495 DESCRIPTION 496 Human-readable description of what this 497 AML helper program will do. Used to show 498 to the AML staff. 499 500 ENABLED 501 True if this AML program is enabled (and thus can be 502 used in measures and exposed to AML staff). 503 Optional, default is NO. 504 505 FALLBACK 506 Name of an **original** measure to take if COMMAND fails 507 Usually points to a measure that asks AML staff 508 to contact the systems administrator. The fallback measure 509 context always includes the reasons for the 510 failure. 511 512 EXCHANGE KYC MEASURES 513 --------------------- 514 515 The following options must be in "[kyc-measure-$MEASURE_NAME]" sections. 516 These sections define the **original** measures. 517 518 CHECK_NAME 519 Name of a possible check for this measure. Optional. 520 If not given or set to ``SKIP``, PROGRAM should be run immediately 521 (on an empty set of attributes). 522 523 CONTEXT = {"choices":["individual","business"]} 524 Context for the check. The context can be 525 just an empty JSON object if there is none. 526 527 PROGRAM 528 Program to run on the context and check data to 529 determine the outcome and next measure. 530 Refers to a ``[aml-program-$PROG_NAME]`` section name. 531 532 VOLUNTARY 533 Optional. Set to YES to allow this measure to be 534 done voluntarily by a client. Used to offer the 535 SPA to display measures even if they are 536 not required. Default is NO. 537 538 539 540 AGE_RESTRICTION_ENABLED 541 Set to ``YES`` to enable age restriction on coins. When age restriction is 542 active, certain denominations can be marked with ``AGE_RESTRICTED = YES`` 543 (see `EXCHANGE COIN OPTIONS`_) and wallets must include an age commitment 544 when withdrawing or spending such coins. Default is ``NO``. 545 546 AGE_GROUPS 547 Only meaningful when ``AGE_RESTRICTION_ENABLED = YES``. 548 A colon-separated string of increasing non-negative integers defining the 549 age-group boundaries. Each integer marks the start of the next group; the 550 zero'th group begins implicitly at 0. For example ``"10:18"`` defines three 551 groups: 552 553 1. Group 0: ages 0 through 9 (inclusive) 554 2. Group 1: ages 10 through 17 (inclusive) 555 3. Group 2: ages 18 and above 556 557 If not given the default value ``"8:10:12:14:16:18:21"`` is used. 558 559 560 EXCHANGE OFFLINE SIGNING OPTIONS 561 -------------------------------- 562 563 The following options must be in the section "[exchange-offline]". 564 565 MASTER_PRIV_FILE 566 Location of the master private key on disk. Only used by tools that 567 can be run offline (as the master key is for offline signing). 568 Mandatory. 569 570 SECM_TOFU_FILE 571 Where to store the public keys of both crypto helper modules. 572 Used to persist the keys after the first invocation of the tool, 573 so that if they ever change in the future, this is detected and 574 the tool can abort. 575 Mandatory. 576 577 SECM_DENOM_PUBKEY 578 Public key of the (RSA) crypto helper module. Optional. If not given, 579 we will rely on TOFU. Note that once TOFU has been established, 580 this option will also be ignored. 581 582 SECM_ESIGN_PUBKEY 583 Public key of the (EdDSA) crypto helper module. Optional. If not given, 584 we will rely on TOFU. Note that once TOFU has been established, 585 this option will also be ignored. 586 587 588 EXCHANGE RSA CRYPTO HELPER OPTIONS 589 ---------------------------------- 590 591 The following options must be in the section "[taler-exchange-secmod-rsa]". 592 593 LOOKAHEAD_SIGN 594 How long do we generate denomination and signing keys ahead of time? 595 596 OVERLAP_DURATION 597 How much should validity periods for coins overlap? 598 Should be long enough to avoid problems with 599 wallets picking one key and then due to network latency 600 another key being valid. The ``DURATION_WITHDRAW`` period 601 must be longer than this value. 602 603 SM_PRIV_KEY 604 Where should the security module store its long-term private key? 605 606 KEY_DIR 607 Where should the security module store the private keys it manages? 608 609 UNIXPATH 610 On which path should the security module listen for signing requests? 611 612 Note that the **taler-exchange-secmod-rsa** also evaluates the ``[coin_*]`` 613 configuration sections described below. 614 615 616 EXCHANGE CS CRYPTO HELPER OPTIONS 617 --------------------------------- 618 619 The following options must be in the section "[taler-exchange-secmod-cs]". 620 621 LOOKAHEAD_SIGN 622 How long do we generate denomination and signing keys ahead of time? 623 624 OVERLAP_DURATION 625 How much should validity periods for coins overlap? 626 Should be long enough to avoid problems with 627 wallets picking one key and then due to network latency 628 another key being valid. The ``DURATION_WITHDRAW`` period 629 must be longer than this value. 630 631 SM_PRIV_KEY 632 Where should the security module store its long-term private key? 633 634 KEY_DIR 635 Where should the security module store the private keys it manages? 636 637 UNIXPATH 638 On which path should the security module listen for signing requests? 639 640 Note that the **taler-exchange-secmod-cs** also evaluates the ``[coin_*]`` 641 configuration sections described below. 642 643 644 645 EXCHANGE EDDSA CRYPTO HELPER OPTIONS 646 ------------------------------------ 647 648 The following options must be in the section "[taler-exchange-secmod-eddsa]". 649 650 LOOKAHEAD_SIGN 651 How long do we generate denomination and signing keys ahead of time? 652 653 OVERLAP_DURATION 654 How much should validity periods for coins overlap? 655 Should be long enough to avoid problems with 656 wallets picking one key and then due to network latency 657 another key being valid. The ``DURATION_WITHDRAW`` period 658 must be longer than this value. 659 660 DURATION 661 For how long should EdDSA keys be valid for signing? 662 663 SM_PRIV_KEY 664 Where should the security module store its long-term private key? 665 666 KEY_DIR 667 Where should the security module store the private keys it manages? 668 669 UNIXPATH 670 On which path should the security module listen for signing requests? 671 672 .. include:: frags/exchange-database.rst 673 .. include:: frags/exchange-account.rst 674 .. include:: frags/exchange-coin.rst 675 676 EXCHANGE SANCTIONSCHECK OPTIONS 677 ------------------------------- 678 679 This section configures the taler-exchange-sanctionlist tool to enforce 680 sanctions. The tool scores KYC records in two dimensions, the quality 681 of the match (rating) and the number of attributes that were found in 682 both sets (confidence). 683 684 The following options must be in the section "[exchange-sanctionscheck]". 685 686 RATER_COMMAND 687 Program (and command-line arguments) for the helper program to 688 execute to compare sanction list records. Usually set to 689 something like "robocop $SANCTIONLIST.json", but can be any 690 program that reads KYC attributes in JSON line-by-line and 691 outputs a rating (0-1), confidence (0-1) and free-form sanction list 692 identifier for each JSON input received. 693 694 MIN_ROW_FILENAME 695 Name of the file where taler-exchange-sanctionscheck will store the 696 last row process during sanction list evaluation. Not in thed atabase 697 as we frequently need to reset it when we get a new list, so no 698 transactionality is needed or even desirable. There should be no 699 need to change the default. 700 701 FREEZE_RATING_LIMIT 702 Match quality rating (on a scale of [0,1]) that must be exceeded 703 for the exchange to automatically freeze an account. The account 704 must satisfy both the rating limit and the confidence limit to be 705 frozen. 706 707 FREEZE_CONFIDENCE_LIMIT 708 Match confidence rating (on a scale of [0,1]) that must be exceeded 709 for the exchange to automatically freeze an account. A rating of 0 710 means no attributes were available, while a rating of 1 indicates that 711 we could compare the acconts across all dimensions. 712 713 INVESTIGATION_LIMIT 714 Limit (on a scale of [0,1]) that must be exceeded for an account to 715 be flagged for manual investigation. Only applies of the account 716 is not automatically frozen. The limit given is compared against 717 the quality rating divided by the confidence score. 718 If set at 0.95, a modest 0.8 match with low 0.5 confidence will 719 trigger (1.6 > 0.95), but a good 0.9 match with a super-high 1.0 720 confidence would not (0.9 < 0.95). On the other hand, a bad 0.2 match 721 with super-low 0.1 confidence would again trigger (2.0 > 0.95). 722 723 724 SEE ALSO 725 ======== 726 727 taler-exchange-dbinit(1), taler-exchange-httpd(1), taler-exchange-offline(1), taler-exchange-sanctionscheck(1) 728 729 BUGS 730 ==== 731 732 Report bugs by using https://bugs.taler.net/ or by sending electronic 733 mail to <taler@gnu.org>.