023-taler-kyc.rst (74111B)
1 DD 23: Taler KYC 2 ################ 3 4 :Design status: Accepted 5 :Implementation status: Implemented 6 :DD shepherd: TBD 7 :Historical contributors: Florian Dold, Christian Grothoff, Özgür Kesim 8 :First published: 2021-09-12 9 :Last substantive change: 2026-05-03 10 :Implementation evidence: exchange (2024-04-22) 11 :Normative references: :doc:`../core/api-exchange`, :doc:`../taler-kyc-manual` 12 13 .. note:: 14 15 This is a living design rationale. The core exchange API and KYC manual 16 are authoritative for implemented endpoints and operations. 17 18 Summary 19 ======= 20 21 This document discusses the Know-your-customer (KYC) and Anti-Money Laundering 22 (AML) processes supported by Taler. 23 24 For the current wallet-core transaction states, KYC continuation data, and 25 available actions, see :ref:`dd37-kyc` in 26 :doc:`037-wallet-transactions-lifecycle`. 27 28 29 Motivation 30 ========== 31 32 To legally operate, Taler has to comply with KYC/AML regulation that requires 33 banks to identify parties involved in transactions at certain points. 34 35 36 Requirements 37 ============ 38 39 Taler needs to take *measures* based on the following primary *triggers*: 40 41 * Customer withdraws money over a monthly threshold 42 43 * exchange triggers KYC 44 * key: IBAN (encoded as payto:// URI) 45 46 * Wallet receives (via refunds) money resulting in a balance over a threshold 47 48 * this is a client-side restriction 49 * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI) 50 51 * Wallet receives money via P2P payments 52 53 * there are two sub-cases: PUSH and PULL payments 54 * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI) 55 56 * Merchant receives money (Q: any money, or above a monthly threshold?) 57 58 * key: IBAN (encoded as payto:// URI) 59 60 * Reserve is "opened" for invoicing. 61 62 * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI) 63 64 * Import of new sanctions lists and triggering of measures against matches of existing 65 customer records against the list 66 67 For the different operation types, there can be both soft and hard 68 limits. Soft limits are those that the customer may raise by providing data 69 and passing KYC checks. Hard limits cannot be lifted, for example because an 70 exchange forbids crossing those limits in its terms of service for all 71 customers. 72 73 74 Process requirements 75 ^^^^^^^^^^^^^^^^^^^^ 76 77 The key consideration here is *plausibilization*: staff needs to 78 check that the client-provided information is plausible. As this 79 is highly case-dependent, this cannot be automated. 80 81 For the different *measures*, there are various different possible KYC/AML 82 *checks* that could happen: 83 84 * In-person validation by AML staff 85 * Various forms to be filled by AML staff 86 * Validation involving local authorities and post-office 87 * Online validation, sometimes with multiple options (like KYC for multiple people): 88 89 * Forms to be supplied by user (different types of ID) 90 * Interactive video 91 * Documents to be supplied (business register) 92 * Address validation (e-mail or phone or postal) 93 94 Additionally, the process is dynamic and conditional upon various decisions: 95 96 * Individual vs. business 97 * PEP or non-PEP 98 * Hit on sanctions list 99 * Type of business (trust, foundation, listed on stock market, etc.) 100 * Need for plausibilization (via documents by user or staff research) 101 * Periodic updates (of customer data, of sanction lists) and re-assessment 102 103 There are also various *outcomes*: 104 105 * normal operation (with expiration date) 106 * normal operation but with AML staff investigating (new measure) 107 * held, requesting customer documentation (new measure) 108 * held, AML staff reviewing evidence for plausibilization (new measure) 109 * automatically frozen until certain day (due to sanctions) 110 * institutionally frozen until certain day (due to order by state authority) 111 * operation is categorically not allowed (at least above certain limits) 112 113 Outcomes may also be (partially) public, that is exposed to the client. For 114 example, we may want to tell a wallet that it has hit a hard withdraw limit, 115 but might succeed at withdrawing a smaller amount. 116 117 The outcome of a *check* can set new rules or trigger another *measure* (the 118 latter is conditional on reaching the expiration time of the outcome). 119 120 As a result, we largely end up in a large state machine where the AML staff has 121 serious flexibility while the user needs guidance as to the possible next moves 122 and/or to the current state of their account (where some information must not be 123 disclosed). 124 125 126 Documentation requirements 127 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 128 129 For each account we must: 130 131 * define risk-profile (902.4, 905.1) 132 * document the specific setup, likely not just the INI file 133 * should have some key Anti-Money-Laundering Act (AMLA) 134 file attributes, such as: 135 136 * File opened, file closed (keep data for X years afterwards!) 137 * low-risk or high-risk business relationship 138 * PEP status 139 * business domain 140 * authority notification dates (possibly multiple) with 141 voluntary or mandatory notification classification 142 143 Finally, we need to produce statistics: 144 145 * There must be a page with an overview of AMLA files with opening 146 and closing dates and an easy way to determine for any day the 147 number of open AMLA files 148 * Technically, we also need a list of at-risk transactions and of 149 frozen transactions, but given that we can really only freeze 150 on an account-basis, I think there is nothing to do here 151 * number of incidents reported (voluntarily, required) 152 * number of business relationships at any point in time 153 * number of risky business relationships (PEP, etc.) 154 * number of frozen transactions (authority vs. sanction) with start-date and end-date 155 * start-data and end-date of relationships (data retained for X years after end of relationship) 156 157 For this high-level monitoring, we need certain designated critical events to 158 be tracked in the system statistics: 159 160 * account opened 161 * set to high risk 162 * set to low risk 163 * suspicious activity report filed with authority 164 * account frozen 165 * account unfrozen 166 * account closed 167 * sanction list import / update 168 169 170 Sanction lists 171 ^^^^^^^^^^^^^^ 172 173 .. note:: 174 175 The implementation described in the current KYC manual supersedes this 176 historical design sketch. 177 178 We need to be able to import new sanction lists (whenever they are published) 179 and then check existing AMLA files against those lists. Additionally, newly 180 created AMLA files must be checked against the current list and some "measure" 181 applied in case of a match. 182 183 This will primarily require us to define an endpoint to upload a sanction list 184 and to define a new table to track the list of sanctioned entities. As it is 185 expected that sanction lists will not permit fully automated determinations in 186 all cases, an external "sanction check" program should be configured which 187 compares records against the current list and determines the correct measure, 188 such as no change, further manual review by AML staff, or even automatic 189 freeze (and report) depending on how well the records match. 190 191 Basically, the "sanction check" program takes the sanction list and an 192 attribute set to compute the same kind of `AmlOutcome` that an AML program 193 outputs given a context and an attribute set. 194 195 196 Security requirements 197 ^^^^^^^^^^^^^^^^^^^^^ 198 199 IBANs are predictable. We (probably) do not want random people to be able to 200 initate KYC processes for other parties. Similarly, the attestation API 201 requires us to somehow *authenticate* the user to ensure we only give out 202 attestation data to the data subject themselves. For P2P payments and 203 withdrawals, we have the reserve public key that is only known to the data 204 subject and thus can be used to authenticate the client via a signature. Only 205 pure deposits (by merchants or directly from a wallet) are a problem as the 206 only thing we know about the receiver is the IBAN at that time, and literally 207 any user could just deposit money into some bank account, so knowledge of the 208 IBAN is insufficient to determine that we actually are communicating with the 209 owner of the bank account. 210 211 212 Further considerations 213 ^^^^^^^^^^^^^^^^^^^^^^ 214 215 On top of all of this, we need to plan some *diagnostics* to determine when 216 components fail (such as scripts or external services providing malformed 217 results). 218 219 Optionally, in the future, the solution should support fees to be paid by the 220 user for *voluntary* KYC processes related to attestation (#7365). 221 222 223 Proposed Solution 224 ================= 225 226 The main state of an account is represented by a set of `KYC rules <KycRule>` (the 227 `LegitimizationRuleSet`) which specify the current *rules* to apply to 228 transactions involving the account. Rules can *exposed* to the account owner, 229 or can be secret. Each *rule* specifies certain *conditions* which, if met, 230 *trigger* a set of *measures*. After a *rule* was *triggered* and 231 before the *outcome* of a respective *measure* has been produced (say 232 because the user did not yet enter their data or the AML officer is still 233 reviewing the case), the existing rules remain in force. Rules have a display 234 priority, and if a second rule with a higher display priority is also 235 triggered, the *measures* of the higher-priority rule become the active 236 *measures*. Except for the default rule set, every legitimization rule set 237 also has an *expiration* time after which a successor *measure* (or the 238 default rule set) is automatically triggered. 239 240 For any possible *measures*, we define: 241 242 * Contextual input data to be provided (with dynamic inputs, 243 e.g. amount set dynamically based on the *trigger* could be 244 in the context) 245 * A *check* to be performed (checks can be user-interactive (LINK, FORM) 246 or staff-interactive (INFO)) 247 * A fallback *measure* to take on failure of a user-interactive check 248 (if the check fails, we cannot run the AML *program* as required inputs 249 might be missing!) 250 * An (AML) *program* that uses *attribtes* from the *check* as well as 251 *context* data to determine an *outcome* represented as the 252 `AmlOutcome`. 253 254 "verboten" is the name of a special *measure*, which means that crossing the 255 respective transaction threshold is categorically not allowed (for this 256 account). "verboten" with a threshold of zero can be used to freeze funds. 257 258 Possible *outcomes* of a measure include: 259 260 * The next operational state (normal, AML investigation) of the account 261 (basically, whether to add it to the work list of AML staff). 262 * A new set of *rules* in the form of a `LegitimizationRuleSet` that 263 determines custom rules to apply to transactions involving the account; 264 such rules may be used to block certain transactions by using the 265 "verboten" measure. The `LegitimizationRuleSet` also must specify 266 an *expiration* time by which we fall back to a successor measure 267 *or* to the default rules. 268 * A (largely) free-form set of `AccountProperties` that AML staff can 269 use to tag accounts with. Some default properties are defined, but 270 the exchange does not do anything with these and AML SPAs are free to 271 use any properties they like. Account properties are only exposed 272 to AML staff and never to the customer. 273 * A set of *events* that are to be added to the timeline of the 274 operator for statistical purposes. 275 276 For the user-interactive *checks* we need a KYC SPA that is given: 277 278 * instructions to render (with either a form to fill or links to external checks); 279 here the context could provide an array of choices! 280 * possibly an external check that was set up (if any); for cost-reasons, we 281 should only do one at a time, and probably should then always redirect the 282 browser to that check. 283 284 For the staff-interactive *checks* we need an AML SPA: 285 286 * to file forms and upload documentation (without state transition) 287 * to decide on next measure (providing context); here, the exchange needs 288 to expose the list of available *measures* and required *context* for each 289 290 We need some customer-driven interactivity in KYB/KYC process, for example the 291 user may need to be given choices (address vs. phone, individual vs. business, 292 order in which to provide KYC data of beneficiaries). As a result, the 293 exchange needs to serve some SPA for *measures* where the user is shown the 294 next step(s) or choices (which person to collect KYC data on, whether to run 295 challenger on phone number of physical address, etc.). The SPA should also 296 potentially contain a form to allow the customer to directly upload documents 297 to us (like business registration) instead of to some KYC provider. This is 298 because KYC providers may not be flexible enough. The SPA should also allow 299 the customer to perform KYC checks voluntarily. 300 301 Similarly, the AML staff will need to be able to trigger rather complex 302 KYB/KYC processes, like "need KYC on X and Y and Z" or "phone number or 303 mailing address" or "please upload form A/T/S". Here in particular it 304 should be possible to request not only filled forms, but arbitrary 305 documents. 306 307 308 Terminology 309 ^^^^^^^^^^^ 310 311 * **Attributes**: Attributes are used to represent KYC data obtained about 312 an account holder. Attributes include passport images, address data, 313 business registration documents, and indeed arbitrary forms filed by 314 AML staff or the customer themselves. Attribute data is considered 315 sensitive private information and is thus stored encrypted within the 316 exchange database. 317 318 * **Check**: A check establishes a particular attribute of a user, such as 319 their name based on an ID document and lifeness, mailing address, phone 320 number, taxpayer identity, etc. Checks may be given *context* (such as 321 whether a customer is an individual or a business) to run correctly. Checks 322 can also be AML staff inserting information for plausibilization. Checks 323 result in *attributes* about the account's owner which are given to an 324 external AML *program* together with the *context* to determine an *outcome*. 325 KYC checks are always specified with a fallback *measure* to be taken if 326 the check fails. 327 328 * **Condition**: A condition specifies when KYC is required. Conditions 329 include the *type of operation*, a threshold amount (e.g. above EUR:1000) 330 and possibly a time period (e.g. over the last month). 331 332 * **Configuration**: The configuration determines the *legitimization rules*, 333 and specifies which providers offer which *checks*. 334 335 * **Context**: Context is information provided as input into a *check* and 336 *program* to customize their execution. The context is initially set by the 337 *measure* (possibly including data from the *trigger*). Naturally, the 338 *program* may use its `AmlProgramInput` which includes *context* and 339 *attribute* data to compute an update *context* for the next set of 340 *measures* that it specifies in the `LegitimizationRuleSet` as part 341 of the `AmlOutcome`. Thus, *context* is something that typically 342 evolves as the *account* undergoes *measures*. Context is lost if 343 an account transitions to default *legitimization rules* due to 344 *expiration*. 345 346 * **Display priority**: Every rule has a *display priority*. If a second 347 *rule* is *triggered* before the *outcome* of a *rule* could be determined, 348 the *rule* with the larger *display priority* becomes the requirement that 349 the account owner has to satisfy (and that thus will be displayed by the 350 KYC SPA). 351 352 * **Expiration**: Except for the default rules, any set of KYC rules is 353 subject to *expiration*. This can be because *attributes* become outdated or 354 because sanctions have a time limit. The expiration time thus determines 355 when a new *measure* is triggered in the absence of a transaction crossing 356 thresholds in the current set of *legtimization rules*. 357 358 * **Legitimization rules**: The *legitimization rules* determine under which 359 *conditions* which *measures* will be taken. A `LegitimizationRuleSet` 360 always also includes an *expiration* time period for (custom, non-default) 361 *legitimization rules* after which a fallback measure* will automatically 362 apply. Legitimization rules may be *exposed* to the client (for example, 363 to allow a wallet to stay below hard withdraw thresholds) or could be secret. 364 365 * **Logic**: Logic refers to a specific bit of code (realized as an exchange 366 plugin) that enables the interaction with a specific *provider*. Logic 367 typically requires *configuration* for access control (such as an 368 authorization token) and possibly the endpoint of the specific *provider* 369 implementing the respective API. 370 371 * **Measure**: Describes the possible outgoing edges from one state in the 372 state machine (including how to show the current state). Each edge is given 373 some *context* and a *check* to be performed as well as an AML *program* 374 which determines the *outcome*. We generally distinguish between 375 "original" measures (defined globally in the exchange configuration) and 376 "custom" measures (defined specifically for an account by AML staff). 377 378 * **Outcome**: An `AmlOutcome` describes the account state that an account 379 ends up in due to either an AML staff action or an AML *program* doing some 380 computation over the attributes resulting from a *check*. Outcomes can be 381 that certain types of transactions are "verboten", that the account is (or 382 remains) under investigation by AML staff, that the account is given certain 383 properties, and/or that certain events are to be logged. Outcomes also 384 include a new set of *legitimization rules* to apply (and an *expiration* 385 time at which point a successor *measure* will be automatically taken). 386 387 * **Provider**: A provider performs a specific set of *checks* at a certain 388 *cost*. Interaction with a provider is performed by provider-specific 389 *logic*. 390 391 * **Program**: An AML helper *program* is given *context* about the current 392 state of an account and the attribute data from a *check* to compute the 393 *outcome*. For example, a *program* may look at the "PEP" field of a KYC 394 check and decide if the outcome is to put the account into ``normal`` or 395 ``held-for-manual-review`` state. AML programs are always specified 396 with a fallback *measure* to be taken if the program fails. 397 398 * **Trigger**: A specific transaction that satisfies a **Condition**. 399 400 * **Type of operation**: The operation type determines which Taler-specific 401 operation has triggered the KYC requirement. We support four types of 402 operation: withdraw (by customer), deposit (by merchant), P2P receive (by 403 wallet) and (high) wallet balance. 404 405 406 Account owner authentication 407 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 408 409 Access to the KYC SPA (or rather, its account-specific state) is controlled by 410 a *target token* (which is effectively like a bearer token, except passed 411 inside the URL). The *target token* ensures that only the account owner has 412 access to the KYC processes. It can be obtained by authenticating using 413 either the merchant private key or reserve private key, depending on the type 414 of the account (IBAN or wallet-reserve respectively). 415 416 When we need to authenticate a bank account owner, we will simply require them 417 to make an outgoing wire transfer into the exchange bank account with a public 418 key in the wire transfer subject (just like when withdrawing), but augmented 419 with the string "KYC" so we can distinguish the wire transfer from a regular 420 withdrawal. Typically, we would put the merchant public key into the wire 421 transfer subject; wallets MAY put their long-term reserve public key instead. 422 The amount to be transferred is the *KYC fee*. 423 424 This has several advantages: 425 426 * Only the account owner can provide us with the public key, so we already 427 have also one super-hard piece of KYC evidence. 428 * If the account owner looses their public key, it's not a problem: they 429 would just have to do the transfer again with a new key. No need for 430 us to do any kind of intervention for key management. 431 * We could theoretically get paid to do the KYC process, or just "charge" a 432 nominal amount. 433 * This also somewhat addresses the payment for voluntary KYC processes where 434 a merchant wants to do KYC to get us to attest their identity for their 435 customers even if we do not yet have a legal need. The only issue here 436 is that this does not work if voluntary KYC is invoiced while mandatory 437 KYC is gratis. But, that kind of configuration is a business decision 438 and there is no hard need to support it immediately. 439 * This definitively addresses the need for authentication to access the 440 attestation API, which so far was only available for P2P payments as 441 we could not authenticate merchants. 442 * The "KYC" string allows us to distinguish the authentication transfers from 443 withdrawal transfers; by keeping the KYC fee at or below the closing fee, 444 we can even deploy this without fully updating the logic everywhere to 445 distinguish KYC transfers 446 447 448 451 Response 449 ^^^^^^^^^^^^ 450 451 When KYC operations are required, various endpoints may respond with a 452 ``451 Unavailable for Legal Reasons`` status code and a `LegitimizationNeededResponse` 453 body. 454 455 New endpoints 456 ^^^^^^^^^^^^^ 457 458 .. http:get:: /kyc-check/$H_PAYTO 459 460 Checks the KYC status of a particular payment target and possibly begins a 461 KYC process by allowing the customer to choose the next KYC measure to 462 satisfy. This endpoint is typically used by wallets or merchants that 463 have been told that a transaction is not happening because it triggered 464 some KYC/AML measure and now want to check how the KYC/AML 465 requirement could be fulfilled (or whether it already has been 466 satisfied and the operation can now proceed). Long-polling may be used 467 to instantly observe a change in the KYC requirement status. 468 469 The payto hash of the ``/kyc-check/`` endpoint encodes the 470 account (or wallet) for which legitimization measures are determined. 471 It is returned in `LegitimizationNeededResponse` responses as in 472 the case of withdraw, the wallet may not know the debited bank account. 473 474 Given a valid pair of payto hash and account owner signature, the 475 ``/kyc-check/`` endpoint returns either just the KYC status or redirects the 476 client (202) to the next required stage of the KYC process. The redirection 477 must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET. It 478 must always be the same endpoint for the same client, as the wallet/merchant 479 backend are not required to check for changes to this endpoint. Clients 480 that received a 202 status code may repeat the request and use long-polling 481 to detect a change of the HTTP status. 482 483 **Request:** 484 485 *Account-Owner-Signature*: 486 The client must provide Base-32 encoded EdDSA signature with 487 ``$ACCOUNT_PRIV``, affirming the desire to obtain KYC data. Note that 488 this is merely a simple authentication mechanism, the details of the 489 request are not protected by the signature. The ``$ACCOUNT_PRIV`` is 490 either the (wallet long-term) reserve private key or the merchant instance 491 private key. 492 493 :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will 494 wait up to ``timeout_ms`` milliseconds if the requirement continues 495 to be mandatory provisioning of KYC data by the client. 496 Ignored if the HTTP status code is already ``200 Ok``. Note that 497 clients cannot long-poll for AML staff actions, so status information 498 about an account being under AML review needs to be requested 499 periodically. 500 501 **Response:** 502 503 :http:statuscode:`200 Ok`: 504 No mandatory KYC actions are required by the client at this time. 505 The client *may* still visit the KYC URL to initiate voluntary checks. 506 The response will be an `AccountKycStatus` object which specifies 507 restrictions that currently apply to the account. If the 508 client attempts to exceed *soft* limits, the status may change 509 to a ``202 Accepted``. Hard limits cannot be lifted by passing KYC checks. 510 :http:statuscode:`202 Accepted`: 511 The account holder performed an operation that would have crossed 512 *soft* limits and must be redirected to the provided location to perform 513 the required KYC checks to satisfy the legal requirements. Afterwards, the 514 ``/kyc-check/`` request should be repeated to check whether the 515 user has completed the process. 516 The response will be an `AccountKycStatus` object. 517 :http:statuscode:`204 No content`: 518 The exchange is not configured to perform KYC and thus 519 the legal requirements are already satisfied. 520 :http:statuscode:`403 Forbidden`: 521 The provided signature is not acceptable for the payto hash. 522 :http:statuscode:`404 Not found`: 523 The requirement row is unknown. 524 525 .. http:get:: /aml-spa/$FILENAME 526 527 Serves the resources of the AML SPA. 528 529 .. http:get:: /kyc-spa/$FILENAME 530 531 Serves the resources of the KYC SPA. Note that 532 ``$FILENAME`` must be syntactically distinct from 533 the access token. Any ``$ACCESS_TOKEN`` will be 534 mapped internally to "index.html". 535 536 .. http:get:: /kyc-spa/$ACCESS_TOKEN 537 538 A set of ``/kyc-spa/$ACCESS_TOKEN`` GET endpoints is created per account 539 hash that serves the KYC SPA. This is where the ``/kyc-check/`` endpoint 540 will in principle redirect clients. The KYC SPA will use the 541 ``$ACCESS_TOKEN`` of its URL to initialize itself via the 542 ``/kyc-info/$ACCESS_TOKEN`` endpoint family. The KYC SPA may download 543 additional resources via ``/kyc-spa/$FILENAME``. The filenames must not 544 match base32-encoded 256-bit values. 545 546 .. http:get:: /kyc-info/$ACCESS_TOKEN 547 548 The ``/kyc-info/$ACCESS_TOKEN`` endpoints are created per client 549 account hash (but access controlled via a unique target token) 550 to return information about the state of the KYC or AML process 551 to the KYC SPA. The SPA uses this information to show the user an 552 appropriate dialog. The SPA should also long-poll this endpoint for changes 553 to the AML/KYC state. Note that this is a client-facing endpoint, so it will 554 only provide a restricted amount of information to the customer (as some 555 laws may forbid us to inform particular customers about their true status). 556 The endpoint will typically inform the SPA about possible choices to 557 proceed, such as directly uploading files, contacting AML staff, or 558 proceeding with a particular KYC process at an external provider (such as 559 Challenger). If the user chooses to initate a KYC process at an external 560 provider, the SPA must request the respective process to be set-up by the 561 exchange via the ``/kyc-start/`` endpoint. 562 563 **Request:** 564 565 *If-None-Match*: 566 The client MAY provide an ``If-None-Match`` header with an ETag. 567 568 :query timeout_ms=MILLISECONDS: 569 *Optional.* If specified, the exchange will wait up to MILLISECONDS for 570 a change to a more recent legitimization measure before returning a 304 571 Not Modified status. 572 573 **Response:** 574 575 *Etag*: Will be set to the serial ID of the measure. Used for long-polling (only for 200 OK responses). 576 577 :http:statuscode:`200 OK`: 578 The body is a `KycProcessClientInformation`. 579 :http:statuscode:`204 No Content`: 580 There are no open KYC requirements or possible voluntary checks 581 the client might perform. 582 :http:statuscode:`304 Not Modified`: 583 The KYC requirements did not change. 584 585 586 .. http:post:: /kyc-upload/$ID 587 588 The ``/kyc-upload/$ID`` POST endpoint allows the SPA to upload 589 client-provided evidence. The ``$ID`` will be provided as part of the 590 ``/kyc-info`` body. This is for checks of type ``FORM``. In practice, 591 ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of the selected 592 measure (but this should be irrelevant for the client). 593 594 **Request:** 595 596 Basically oriented along the possible formats of a HTTP form being 597 POSTed. Details will depend on the form. The server will try to decode the 598 uploaded body from whatever format it is provided in. 599 600 **Response:** 601 602 :http:statuscode:`204 No Content`: 603 The information was successfully uploaded. The SPA should fetch 604 an updated ``/kyc-info/``. 605 :http:statuscode:`404 Not Found`: 606 The ``$ID`` is unknown to the exchange. 607 :http:statuscode:`409 Conflict`: 608 The upload conflicts with a previous upload. 609 :http:statuscode:`413 Request Entity Too Large`: 610 The body is too large. 611 612 .. http:post:: /kyc-start/$ID 613 614 The ``/kyc-start/$ID`` POST endpoint allows the SPA to set up a new external 615 KYC process. It will return the URL that the client must GET to begin the 616 KYC process. The SPA should probably open this URL in a new window or tab. 617 The ``$ID`` will be provided as part of the ``/kyc-info`` body. In 618 practice, ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of 619 the selected measure (but this should be irrelevant for the client). 620 621 **Request:** 622 623 Use empty JSON body for now. 624 625 **Response:** 626 627 :http:statuscode:`200 Ok`: 628 The KYC process was successfully initiated. The URL is in a 629 `KycProcessStartInformation` object. 630 631 :http:statuscode:`404 Not Found`: 632 The ``$ID`` is unknown to the exchange. 633 634 .. note:: 635 636 As this endpoint is involved in every KYC check at the beginning, this 637 is also the place where we could integrate the payment process for the KYC fee 638 in the future (since **vATTEST**). 639 640 641 .. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO 642 643 Upon completion of the process at the external KYC provider, the provider 644 must redirect the client (browser) to trigger a GET request to a new 645 ``/kyc-proof/$H_PAYTO/$PROVIDER_SECTION`` endpoint. Once this endpoint is 646 triggered, the exchange will pass the received arguments to the respective 647 logic plugin. The logic plugin will then (asynchronously) update the KYC 648 status of the user. The logic plugin should redirect the user to the KYC 649 SPA. This endpoint deliberately does not use the ``$ACCESS_TOKEN`` as the 650 external KYC provider should not learn that token. 651 652 This endpoint is thus accessed from the user's browser at the *end* of a KYC 653 process, possibly providing the exchange with additional credentials to 654 obtain the results of the KYC process. Specifically, the URL arguments 655 should provide information to the exchange that allows it to verify that the 656 user has completed the KYC process. The details depend on the logic, which 657 is selected by the "$PROVIDER_SECTION". 658 659 While this is a GET (and thus safe, and idempotent), the operation may 660 actually trigger significant changes in the exchange's state. In 661 particular, it may update the KYC status of a particular payment target. 662 663 **Request:** 664 665 Details on the request depend on the specific KYC logic that was used. 666 667 If the KYC plugin logic is OAuth 2.0, the query parameters are: 668 669 :query code=CODE: 670 OAuth 2.0 code argument. 671 :query state=STATE: 672 OAuth 2.0 state argument with the H_PAYTO. 673 674 .. note:: 675 676 Depending on the OAuth variant used, additional 677 query parameters may need to be passed here. 678 679 **Response:** 680 681 Given that the response is returned to a user using a browser and **not** to 682 a Taler wallet, the response format is in human-readable HTML and not in 683 machine-readable JSON. 684 685 :http:statuscode:`302 Found`: 686 The KYC operation succeeded and the 687 payment target is now authorized to transact. 688 The browser is redirected to a human-readable 689 page configured by the exchange operator. 690 :http:statuscode:`401 Unauthorized`: 691 The provided authorization token is invalid. 692 :http:statuscode:`404 Not found`: 693 The payment target is unknown. 694 :http:statuscode:`502 Bad Gateway`: 695 The exchange received an invalid reply from the 696 legitimization service. 697 :http:statuscode:`504 Gateway Timeout`: 698 The exchange did not receive a reply from the legitimization 699 service within a reasonable time period. 700 701 702 .. http:get:: /kyc-webhook/$PROVIDER_SECTION/* 703 .. http:post:: /kyc-webhook/$PROVIDER_SECTION/* 704 .. http:get:: /kyc-webhook/$LOGIC/* 705 .. http:post:: /kyc-webhook/$LOGIC/* 706 707 Alternatively, the KYC confirmation may be triggered by a ``/kyc-webhook`` 708 request. As KYC **providers** do not necessarily support passing detailed 709 information in the URL arguments, the ``/kyc-webhook`` only needs to specify 710 either the ``PROVIDER_SECTION`` *or* the ``LOGIC`` (the name of the plugin 711 implementing the KYC API). The API-specific webhook logic must then figure 712 out what exactly the webhook is about on its own. The ``/kyc-webhook/`` 713 endpoint works for GET or POST, again as details depend on the KYC provider. 714 In contrast to ``kyc-proof``, the response does NOT go to the end-users' 715 browser and should thus only indicate success or failure. 716 717 **Request:** 718 719 Details on the request depend on the specific KYC logic that was used. 720 721 **Response:** 722 723 :http:statuscode:`204 No content`: 724 The operation succeeded. 725 :http:statuscode:`404 Not found`: 726 The specified logic is unknown. 727 728 729 .. http:post:: /kyc-wallet 730 731 The ``/kyc-wallet`` POST endpoint allows a wallet to notify an exchange if 732 it will cross a balance threshold. Here, the ``balance`` specified should be 733 the threshold (from the ``wallet_balance_limit_without_kyc`` array) that the 734 wallet would cross, and *not* the *exact* balance of the wallet. The exchange 735 will respond with a wire target UUID. The wallet can then use this UUID to 736 begin the KYC process at ``/kyc-check/``. The wallet must only proceed to 737 obtain funds exceeding the threshold after the KYC process has concluded. 738 While wallets could be "hacked" to bypass this measure (we cannot 739 cryptographically enforce this), such modifications are a terms of service 740 violation which may have legal consequences for the user. 741 742 Setup KYC identification for a wallet. Returns the KYC UUID. This endpoint 743 is used by compliant Taler wallets when they are about to hit the balance 744 threshold and thus need to have the customer provide their personal details 745 to the exchange. The wallet is identified by its long-lived reserve public 746 key (which is used for P2P payments, not for withdrawals). 747 748 **Request:** 749 750 The request body must be a `WalletKycRequest` object. 751 752 **Response:** 753 754 :http:statuscode:`204 No Content`: 755 KYC is disabled at this exchange, or the balance is below the 756 threshold that requires KYC, or this wallet already satisfied 757 the KYC check for the given balance. 758 :http:statuscode:`403 Forbidden`: 759 The provided signature is invalid. 760 This response comes with a standard `ErrorDetail` response. 761 :http:statuscode:`451 Unavailable for Legal Reasons`: 762 The wallet must undergo a KYC check. A KYC ID was created. 763 The response will be a `LegitimizationNeededResponse` object. 764 765 .. http:get:: /aml/$OFFICER_PUB/measures 766 767 To enable the AML staff SPA to give AML staff a choice of possible measures, a 768 new endpoint ``/aml/$OFFICER_PUB/measures`` is added that allows the AML SPA 769 to dynamically GET the list of available measures. It returns a list of known 770 KYC checks (by name) with their descriptions and a list of AML programs with 771 information about the required context. 772 773 **Request:** 774 775 *Taler-AML-Officer-Signature*: 776 The client must provide Base-32 encoded EdDSA signature with 777 ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that 778 this is merely a simple authentication mechanism, the details of the 779 request are not protected by the signature. 780 781 **Response:** 782 783 :http:statuscode:`200 Ok`: 784 Information about possible measures is returned in a 785 `AvailableMeasureSummary` object. 786 787 .. http:get:: /aml/$OFFICER_PUB/kyc-statistics/$NAME 788 789 Returns the number of KYC events matching the given event type ``$NAME`` in 790 the specified time range. Note that this query can be slow as the 791 statistics are computed on-demand. (This is OK as such requests should be 792 rare.) 793 794 **Request:** 795 796 *Taler-AML-Officer-Signature*: 797 The client must provide Base-32 encoded EdDSA signature with 798 ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that this 799 is merely a simple authentication mechanism, the details of the request are 800 not protected by the signature. 801 802 :query start_date=TIMESTAMP: 803 *Optional*. Specifies the date when to 804 start looking (inclusive). If not given, the start time of the 805 exchange operation is used. 806 :query end_date=TIMESTAMP: 807 *Optional*. Specifies the date when to 808 stop looking (exclusive). If not given, the current date is used. 809 810 **Response:** 811 812 :http:statuscode:`200 OK`: 813 The response will be an `EventCounter` message. 814 815 .. http:get:: /aml/$OFFICER_PUB/decisions 816 817 **Request:** 818 819 *Taler-AML-Officer-Signature*: 820 The client must provide Base-32 encoded EdDSA signature with 821 ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that 822 this is merely a simple authentication mechanism, the details of the 823 request are not protected by the signature. 824 825 :query limit: 826 *Optional*. takes value of the form ``N (-N)``, so that at 827 most ``N`` values strictly older (younger) than ``start`` are returned. 828 Defaults to ``-20`` to return the last 20 entries (before ``start``). 829 :query offset: 830 *Optional*. Row number threshold, see ``delta`` for its 831 interpretation. Defaults to ``INT64_MAX``, namely the biggest row id 832 possible in the database. 833 :query h_payto: 834 *Optional*. Account selector. All matching accounts are returned if this 835 filter is absent, otherwise only decisions for this account. 836 :query active: 837 *Optional*. If set to yes, only return active decisions, if no only 838 decisions that have been superseded. Do not give (or use "all") to 839 see all decisions regardless of activity status. 840 :query investigation: 841 *Optional*. If set to yes, only return accounts that are under 842 AML investigation, if no only accounts that are not under investigation. 843 Do not give (or use "all") to see all accounts regardless of 844 investigation status. 845 846 **Response:** 847 848 :http:statuscode:`200 OK`: 849 The response will be an `AmlDecisionsResponse` message. 850 :http:statuscode:`204 No content`: 851 There are no matching AML records. 852 :http:statuscode:`403 Forbidden`: 853 The signature is invalid. 854 :http:statuscode:`404 Not found`: 855 The designated AML account is not known. 856 :http:statuscode:`409 Conflict`: 857 The designated AML account is not enabled. 858 859 .. http:get:: /aml/$OFFICER_PUB/attributes/$H_PAYTO 860 861 Obtain attributes obtained as part of AML/KYC processes for a 862 given account. 863 864 **Request:** 865 866 *Taler-AML-Officer-Signature*: 867 The client must provide Base-32 encoded EdDSA signature with 868 ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that 869 this is merely a simple authentication mechanism, the details of the 870 request are not protected by the signature. 871 872 :query limit: 873 *Optional*. takes value of the form ``N (-N)``, so that at 874 most ``N`` values strictly older (younger) than ``start`` are returned. 875 Defaults to ``-20`` to return the last 20 entries (before ``start``). 876 :query offset: 877 *Optional*. Row number threshold, see ``delta`` for its 878 interpretation. Defaults to ``INT64_MAX``, namely the biggest row id 879 possible in the database. 880 881 **Response:** 882 883 :http:statuscode:`200 OK`: 884 The response will be an `KycAttributesResponse` message. 885 :http:statuscode:`204 No content`: 886 There are no matching KYC attributes. 887 :http:statuscode:`403 Forbidden`: 888 The signature is invalid. 889 :http:statuscode:`404 Not found`: 890 The designated AML account is not known. 891 :http:statuscode:`409 Conflict`: 892 The designated AML account is not enabled. 893 894 .. http:post:: /aml/$OFFICER_PUB/decision 895 896 Make an AML decision. Triggers the respective action and 897 records the justification. 898 899 **Request:** 900 901 The request body must be an `AmlDecisionRequest` message. 902 903 **Response:** 904 905 :http:statuscode:`204 No Content`: 906 The AML decision has been executed and recorded successfully. 907 :http:statuscode:`403 Forbidden`: 908 The signature is invalid. 909 :http:statuscode:`404 Not Found`: 910 The address the decision was made upon is unknown to the exchange or 911 the designated AML account is not known. 912 :http:statuscode:`409 Conflict`: 913 The designated AML account is not enabled or a more recent 914 decision was already submitted. 915 916 Modifications to existing endpoints 917 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 918 919 .. note:: 920 921 This subsection describes an earlier KYC API design. The core exchange API 922 and KYC manual supersede its endpoint names and processing model. 923 924 When withdrawing, the exchange checks if the KYC status is acceptable. If no 925 KYC was done and if either the amount withdrawn over a particular timeframe 926 exceeds the threshold or the reserve received a P2P transfer, then a 927 ``451 Unavailable for Legal Reasons`` is returned which redirects the consumer 928 to the new ``/kyc-check/`` handler. 929 930 When depositing, the exchange aggregator (!) checks the KYC status and if 931 negative, returns an additional information field via the 932 ``aggregation_transient`` table which is returned via GET ``/deposits/`` to the 933 merchant. 934 935 When merging into a reserve, the KYC status is checked and again the 936 merge fails with ``451 Unavailable for Legal Reasons`` to trigger the 937 KYC process. 938 939 To allow the wallet to do the KYC check if it is about to exceed a set balance 940 threshold, we modify the ``/keys`` response to add an optional array 941 ``wallet_balance_limit_without_kyc`` of threshold amounts is returned. 942 Whenever the wallet crosses one of these thresholds for the first time, it 943 should trigger the KYC process. If this field is absent, there is no limit. 944 If the field is provided, a correct wallet must create a long-term 945 account-reserve key pair. This should be the same key that is also used to 946 receive wallet-to-wallet payments. Then, *before* a wallet performs an 947 operation that would cause it to exceed the balance threshold in terms of 948 funds held from a particular exchange, it *should* first request the user to 949 complete the KYC process. For that, the wallet should POST to the new 950 ``/kyc-wallet`` endpoint, providing its long-term reserve-account public key 951 and a signature requesting permission to exceed the account limit. 952 953 954 Configuration of external KYC providers 955 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 956 957 For each KYC provider that could contribute to checks the configuration 958 specifies a ``$PROVIDER_SECTION`` for each authentication procedure. For each 959 (enabled) provider, the exchange has a logic plugin which (asynchronously) 960 determines the redirect URL for a given wire target. See below for a 961 description of the high-level process for different providers. 962 963 .. code-block:: ini 964 965 [kyc-provider-$PROVIDER_ID] 966 967 # Which plugin is responsible for this provider? 968 LOGIC = PLUGIN_NAME 969 970 # Plus additional logic-specific options, e.g.: 971 AUTHORIZATION_TOKEN = superdupersecret 972 973 # Other logic-specific internal options (example): 974 FORM_ID = business_legi_form 975 976 977 Configuration of possible KYC/AML checks 978 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 979 980 The configuration specifies a set of possible KYC checks offered by external 981 providers, one per configuration section: 982 983 .. code-block:: ini 984 985 [kyc-check-$CHECK_NAME] 986 987 # Which type of check is this? Also determines 988 # the SPA form to show to the user for this check. 989 # 990 # INFO: wait for staff or contact staff out-of band 991 # (only information shown, no SPA action) 992 # FORM: SPA should show an inline (HTML) form 993 # LINK: SPA may start external KYC process or upload 994 # 995 TYPE = INFO|LINK|FORM 996 997 # Provider id, present only if type is LINK. 998 # Refers to a ``kyc-provider-$PROVIDER_ID`` section. 999 PROVIDER_ID = id 1000 1001 # Name of the SPA form, if type is FORM 1002 # "INFO" and "LINK" are reserved and must not be used. 1003 # The exchange server and the SPA must agree on a list 1004 # of supported forms and the resulting attributes. 1005 # 1006 # The SPA should include a JSON resource file 1007 # "forms.json" mapping form names to arrays of 1008 # attribute names each form provides. 1009 FORM_NAME = name 1010 1011 # Descriptions to use in the SPA to display the check. 1012 DESCRIPTION = "Upload your passport picture" 1013 DESCRIPTION_I18N = "{"en":"Upload scan of your passport"}" 1014 1015 # ';'-separated list of fields that the CONTEXT must 1016 # provide as inputs to this check. For example, 1017 # for a FORM of type CHOICE, this might state 1018 # ``choices: string[];``. The type after the ":" 1019 # is for now purely for documentation and is 1020 # not checked. However, it may be shown to AML staff 1021 # when they configure measures. 1022 REQUIRES = requirement; 1023 1024 # Description of the outputs provided by the check. 1025 # Basically, the check's output is expected to 1026 # provide the following fields as attribute inputs into 1027 # a subsequent AML program. 1028 # Only given for type FORM; INFO never has any outputs, 1029 # and for type LINK we can obtain the same information 1030 # from the CONVERTER via ``--list-outputs``. 1031 OUTPUTS = business_name street city country registration 1032 1033 # **original** measure to take if the check fails 1034 # (for any reason, e.g. provider or form fail to 1035 # satisfy constraints or provider signals user error) 1036 # Usually should point to a measure that requests 1037 # AML staff to investigate. The fallback measure 1038 # context always includes the reasons for the 1039 # failure. 1040 FALLBACK = MEASURE_NAME 1041 1042 The list of possible FORM names is fixed in the SPA 1043 for a particular exchange release. 1044 1045 The outcome of *any* check should always be uploaded encrypted into the 1046 ``kyc_attributes`` table. It MUST include an ``expiration_time``. 1047 1048 The "check_name" value "skip" is reserved and must not be defined. It can be 1049 used in measures where the AML program must be run immediately without any 1050 input. 1051 1052 1053 Configuration of legitimization requirement triggers 1054 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1055 1056 The configuration also specifies a set of legitimization rules including the 1057 condition and the measure the condition triggers, one condition per 1058 configuration section: 1059 1060 .. code-block:: ini 1061 1062 [kyc-rule-$RULE_NAME] 1063 1064 # Operation that triggers this rule. 1065 # Must be one of "WITHDRAW", "DEPOSIT", 1066 # (p2p) "MERGE", (wallet) "BALANCE", 1067 # (reserve) "CLOSE", "AGGREGATE", 1068 # "TRANSACTION" or "REFUND". 1069 OPERATION_TYPE = WITHDRAW 1070 1071 # Space-separated list of next measures to be performed. 1072 # The SPA should display *all* of these measures to the user. 1073 # (They have a choice of either which ones, or in 1074 # which order they are to be performed.) 1075 # A special measure name "verboten" is used if the 1076 # specified threshold may never be crossed 1077 # (under this set of rules). 1078 NEXT_MEASURES = SWISSNESS KYB 1079 1080 # "YES" if all NEXT_MEASURES will eventually need 1081 # to be satisfied, "NO" if the user has a choice between 1082 # them. Not actually enforced by the exchange, but 1083 # primarily used to inform the user whether this is 1084 # an "and" or "or". YES for "and". 1085 IS_AND_COMBINATOR = YES 1086 1087 # YES if the rule (specifically, operation type, 1088 # threshold, timeframe) and the general nature of 1089 # the next measure (verboten or approval required) 1090 # should be exposed to the client. 1091 # Defaults to NO if not set. 1092 EXPOSED = YES 1093 1094 # Threshold amount above which the rule is 1095 # triggered. The total must be exceeded in the given 1096 # timeframe. 1097 THRESHOLD = KUDOS:100 1098 1099 # Timeframe over which the amount to be compared to 1100 # the THRESHOLD is calculated. 1101 # Ignored for WALLET-BALANCE. Can be 'forever'. 1102 TIMEFRAME = 30 days 1103 1104 # Set to YES to enable the rule (default is NO) 1105 ENABLED = NO 1106 1107 1108 AML programs 1109 ^^^^^^^^^^^^ 1110 1111 AML programs are helper programs that can: 1112 1113 * Generate a list of *required* context field names 1114 for the helper (introspection!) using the "--required-context" 1115 command-line switch. The output should use the same 1116 syntax as the REQUIRES clause of ``[kyc-check-]`` 1117 configuration sections, except that new lines 1118 MUST be used to separate fields instead of ";". 1119 * Generate a list of *required* attribute names 1120 for the helper (introspection!) using the "--required-attributes" 1121 command-line switch. The output should use the same 1122 list of names as the ATTRIBUTES in the 1123 ``[kyc-provider-]`` configuration section 1124 (but may also include FORM field names). 1125 * Process an input JSON object of type 1126 `AmlProgramInput` into a JSON object of 1127 type `AmlOutcome`. 1128 This is the default behavior if no command-line switches 1129 are provided. 1130 1131 If the AML program fails (exits with a failure code or 1132 does not provide well-formed JSON output) the AML/KYC 1133 process continues with the FALLBACK measure. This should 1134 usually be one that asks AML staff to contact the 1135 systems administrator. 1136 1137 AML programs are listed in the configuration file, one program per section: 1138 1139 .. code-block:: ini 1140 1141 [aml-program-$PROG_NAME] 1142 1143 # Program to run. 1144 COMMAND = taler-helper-aml-pep 1145 1146 # Human-readable description of what this 1147 # AML helper program will do. Used to show 1148 # to the AML staff. 1149 DESCRIPTION = "check if the customer is a PEP" 1150 1151 # True if this AML program is enabled (and thus can be 1152 # used in measures and exposed to AML staff). 1153 # Optional, default is NO. 1154 ENABLED = YES 1155 1156 # **original** measure to take if COMMAND fails 1157 # Usually points to a measure that asks AML staff 1158 # to contact the systems administrator. The fallback measure 1159 # context always includes the reasons for the 1160 # failure. 1161 FALLBACK = MEASURE_NAME 1162 1163 1164 Configuration of measures 1165 ^^^^^^^^^^^^^^^^^^^^^^^^^ 1166 1167 Finally, the configuration specifies a set of 1168 **original** *measures* one per configuration section: 1169 1170 .. code-block:: ini 1171 1172 [kyc-measure-$MEASURE_NAME] 1173 1174 # Possible check for this measure. Optional. 1175 # If not given, PROGRAM should be run immediately 1176 # (on an empty set of attributes). 1177 CHECK_NAME = IB_FORM 1178 1179 # Context for the check. The context can be 1180 # just an empty JSON object if there is none. 1181 CONTEXT = {"choices":["individual","business"]} 1182 1183 # Program name to run on the context and check data to 1184 # determine the outcome and next measure. 1185 # Refers to a ``[aml-program-$PROG_NAME]`` section name. 1186 PROGRAM = taler-aml-program 1187 1188 # Optional. Set to YES to allow this measure to be 1189 # done voluntarily by a client. Used to offer the 1190 # KYC SPA to display measure even if they are 1191 # not required. Default is NO. 1192 VOLUNTARY = YES/NO 1193 1194 1195 If ``CHECK_NAME`` is set to "SKIP" (or is not provided at all), the AML 1196 ``PROGRAM`` is to be run immediately. This is useful if no client-interaction 1197 is required to arrive at a decision. 1198 1199 .. note:: 1200 1201 The list of *measures* is not complete: AML staff may freely define new 1202 measures dynamically, usually by selecting checks, an AML program, and 1203 providing context. 1204 1205 1206 Sanity checking 1207 ^^^^^^^^^^^^^^^ 1208 1209 On start-up, ``taler-exchange-httpd`` should sanity-check its 1210 configuration. Specifically, it should validate that for all AML programs the 1211 input requirements (attributes and context) are claimed to be satisfied by the 1212 respective checks that may trigger those programs, and similarly that for all 1213 checks the original measures satisfy the context requirements for their KYC 1214 checks. 1215 1216 As a result, any component (AML program, form or external check) is warranted 1217 to be always called with the declared required inputs. Furthermore, we can 1218 detect if a component fails to produce the required output and the 1219 configuration contains (presumably safe) FALLBACKs to address this case. The 1220 exchange *MUST* detect circular failures, like when a FALLBACK triggers a 1221 measure that itself immediately triggers again the same FALLBACK. 1222 1223 1224 Exchange database schema 1225 ^^^^^^^^^^^^^^^^^^^^^^^^ 1226 1227 We introduce a new ``wire_targets`` table into the exchange database. This 1228 table is referenced as the source or destination of payments (regular deposits 1229 and also P2P payments). A positive side-effect is that we reduce duplication 1230 in the ``reserves_in``, ``wire_out`` and ``deposits`` tables as they can 1231 reference this table. 1232 1233 We introduce a new ``legitimization_processes`` table that tracks the status 1234 of a legitimization process at a provider, including the configuration section 1235 name, the user/account name at the provider, and some legitimization 1236 identifier for the process at the provider. In this table, we additionally 1237 store information related to the KYC status of the underlying payto://-URI, in 1238 particular when the KYC expires (0 if it was never done). 1239 1240 Finally, we introduce a new ``legitimization_requirements`` table that 1241 contains a list of checks required for a particular wire target. When KYC is 1242 triggered (say when some endpoint returns an HTTP status code of 451) a 1243 new requirement is first put into the requirements table. Then, when the 1244 client identifies as business or individual the specific legitimization 1245 process is started. When the taler-exchange-aggregator triggers a KYC check 1246 the merchant can observe this when a 202 (Accepted) status code is returned 1247 on GET ``/deposits/`` with the respective legitimization requirement row. 1248 1249 1250 .. sourcecode:: sql 1251 1252 CREATE TABLE wire_targets 1253 (wire_target_serial_id BIGSERIAL UNIQUE 1254 ,wire_target_h_payto BYTEA PRIMARY KEY CHECK (LENGTH(wire_target_h_payto)=32), 1255 ,access_token BYTEA UNIQUE CHECK (LENGTH(access_token)=32) DEFAULT gen_random_bytes(32) 1256 ,target_pub BYTEA CHECK (LENGTH(target_pub)=32) DEFAULT NULL 1257 ,payto_uri STRING NOT NULL 1258 ) 1259 PARTITION BY HASH (wire_target_h_payto); 1260 1261 COMMENT ON TABLE wire_targets 1262 IS 'All recipients of money via the exchange'; 1263 COMMENT ON COLUMN wire_targets.h_payto 1264 IS 'Unsalted hash of payto_uri'; 1265 COMMENT ON COLUMN wire_targets.access_token 1266 IS 'high-entropy random value that is used as a token to authorize access to the KYC process (without requiring a signature by target_priv)'; 1267 COMMENT ON COLUMN wire_targets.target_pub 1268 IS 'Public key (reserve_pub or merchant_pub) associated with the account; NULL if KYC is not allowed for the account (if there was no incoming KYC wire transfer yet); updated, thus NOT available to the auditor'; 1269 COMMENT ON COLUMN wire_targets.payto_uri 1270 IS 'Can be a regular bank account, or also be a URI identifying a reserve-account (for P2P payments)'; 1271 1272 CREATE TABLE IF NOT EXISTS legitimization_measures 1273 (legitimization_measure_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY 1274 ,access_token BYTEA NOT NULL UNIQUE CHECK (LENGTH(access_token)=32) 1275 REFERENCES wire_targets (access_token) 1276 ,start_time INT8 NOT NULL 1277 ,jmeasures TEXT NOT NULL 1278 ,display_priority INT4 NOT NULL 1279 ,is_finished BOOL NOT NULL DEFAULT(FALSE) 1280 ) 1281 PARTITION BY HASH (access_token); 1282 1283 COMMENT ON TABLE legitimization_measures 1284 IS 'Rules that have been triggered for the account (FIXME: check this is consistent with usage)'; 1285 COMMENT ON COLUMN legitimization_measures.access_token 1286 IS 'Used to uniquely identify the account and as a symmetric access control mechanism for the SPA'; 1287 COMMENT ON COLUMN legitimization_measures.start_time 1288 IS 'Time when the measure was triggered (by decision or rule)'; 1289 COMMENT ON COLUMN legitimization_measures.jmeasures 1290 IS 'JSON object of type LegitimizationMeasures with KYC/AML measures for the account encoded'; 1291 COMMENT ON COLUMN legitimization_measures.display_priority 1292 IS 'Display priority of the rule that triggered this measure; if in the meantime another rule also triggers, the measure is only replaced if the new rule has a higher display priority'; 1293 COMMENT ON COLUMN legitimization_measures.is_finished 1294 IS 'Set to TRUE if this set of measures was processed; used to avoid indexing measures that are done'; 1295 1296 CREATE INDEX ON legitimization_measures (access_token) 1297 WHERE NOT is_finished; 1298 1299 CREATE TABLE legitimization_outcomes 1300 (outcome_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY 1301 ,h_payto BYTEA CHECK (LENGTH(h_payto)=32) 1302 REFERENCES wire_targets (wire_target_h_payto) 1303 ,decision_time INT8 NOT NULL DEFAULT(0) 1304 ,expiration_time INT8 NOT NULL DEFAULT(0) 1305 ,jproperties TEXT, 1306 ,new_measure_name TEXT, 1307 ,to_investigate BOOL NOT NULL 1308 ,is_active BOOL NOT NULL DEFAULT(TRUE) 1309 ,jnew_rules TEXT NOT NULL 1310 ) 1311 PARTITION BY HASH (h_payto); 1312 1313 COMMENT ON TABLE legitimization_outcomes 1314 IS 'Outcomes can come from AML programs'; 1315 COMMENT ON COLUMN legitimization_outcomes.h_payto 1316 IS 'hash of the payto://-URI this outcome is about'; 1317 COMMENT ON COLUMN legitimization_outcomes.decision_time 1318 IS 'when was this outcome decided'; 1319 COMMENT ON COLUMN legitimization_outcomes.expiration_time 1320 IS 'time when the decision expires and the expiration jnew_rules should be applied'; 1321 COMMENT ON COLUMN legitimization_outcomes.jproperties 1322 IS 'JSON object of type AccountProperties, such as PEP status, business domain, risk assessment, etc.'; 1323 COMMENT ON COLUMN legitimization_outcomes.to_investigate 1324 IS 'AML staff should investigate the activity of this account'; 1325 COMMENT ON COLUMN legitimization_outcomes.is_active 1326 IS 'TRUE if this is the current authoritative legitimization outcome'; 1327 COMMENT ON COLUMN legitimization_outcomes.new_measure_name 1328 IS 'space-separated list of measures to trigger immediately, NULL for none, prefixed with a "+" to indicate AND combination for the measures'; 1329 COMMENT ON COLUMN legitimization_outcomes.jnew_rules 1330 IS 'JSON object of type LegitimizationRuleSet with rules to apply to the various operation types for this account; all KYC checks should first check if active new rules for a given account exist in this table (and apply specified measures); if not, it should check the default rules to decide if a measure is required'; 1331 1332 CREATE INDEX legitimization_outcomes_active 1333 ON legitimization_outcomes(h_payto) 1334 WHERE is_active; 1335 1336 CREATE TABLE legitimization_processes 1337 (legitimization_process_serial_id BIGSERIAL UNIQUE 1338 ,h_payto BYTEA NOT NULL CHECK (LENGTH(h_payto)=64) 1339 REFERENCES wire_targets (wire_target_h_payto) 1340 ,start_time INT8 NOT NULL 1341 ,expiration_time INT8 NOT NULL DEFAULT (0) 1342 ,legitimization_measure_serial_id INT8 1343 REFERENCES legitimization_measures (legitimization_measure_serial_id) 1344 ,measure_index INT4 1345 ,provider_section TEXT NOT NULL 1346 ,provider_user_id TEXT DEFAULT NULL 1347 ,provider_legitimization_id TEXT DEFAULT NULL 1348 ,redirect_url TEXT DEFAULT NULL 1349 ,finished BOOLEAN DEFAULT (FALSE) 1350 ) 1351 PARTITION BY HASH (h_payto); 1352 1353 COMMENT ON TABLE legitimization_processes 1354 IS 'here we track KYC processes we initiated with external providers; the main reason is so that we do not initiate a second process when an equivalent one is still active; note that h_payto, provider_section, jcontext must match and the process must not be finished or expired for an existing redirect_url to be re-used; given that clients may voluntarily initiate KYC processes, there may not always be a legitimization_measure that triggered the setup'; 1355 COMMENT ON COLUMN legitimization_processes.h_payto 1356 IS 'foreign key linking the entry to the wire_targets table, NOT a primary key (multiple KYC setups are possible per wire target)'; 1357 COMMENT ON COLUMN legitimization_processes.start_time 1358 IS 'when was the legitimization process initiated'; 1359 COMMENT ON COLUMN legitimization_processes.expiration_time 1360 IS 'when does the process expire (and needs to be manually set up again)'; 1361 COMMENT ON COLUMN legitimization_processes.measure_index 1362 IS 'index of the measure in legitimization_measures that was selected for this KYC setup; NULL if legitimization_measure_serial_id is NULL; enables determination of the context data provided to the external process'; 1363 COMMENT ON COLUMN legitimization_processes.provider_section 1364 IS 'Configuration file section with details about this provider'; 1365 COMMENT ON COLUMN legitimization_processes.provider_user_id 1366 IS 'Identifier for the user at the provider that was used for the legitimization. NULL if provider is unaware.'; 1367 COMMENT ON COLUMN legitimization_processes.provider_legitimization_id 1368 IS 'Identifier for the specific legitimization process at the provider. NULL if legitimization was not started.'; 1369 COMMENT ON COLUMN legitimization_processes.legitimization_measure_serial_id 1370 IS 'measure that enabled this setup, NULL if client voluntarily initiated the process'; 1371 COMMENT ON COLUMN legitimization_processes.redirect_url 1372 IS 'Where the user should be redirected for this external KYC process'; 1373 COMMENT ON COLUMN legitimization_processes.finished 1374 IS 'set to TRUE when the specific legitimization process is finished'; 1375 1376 CREATE TABLE kyc_attributes 1377 (kyc_attributes_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY 1378 ,h_payto BYTEA PRIMARY KEY CHECK (LENGTH(h_payto)=32) 1379 REFERENCES wire_targets (wire_target_h_payto) 1380 ,legitimization_process_serial_id INT8 1381 REFERENCES legitimization_processes (legitimization_process_serial_id) 1382 DEFAULT NULL 1383 ,collection_time INT8 NOT NULL 1384 ,expiration_time INT8 NOT NULL 1385 ,trigger_outcome_serial INT8 NOT NULL 1386 REFERENCES legitimization_outcomes(outcome_serial_id) 1387 ,encrypted_attributes BYTEA NOT NULL 1388 ) PARTITION BY HASH (h_payto); 1389 1390 COMMENT ON COLUMN kyc_attributes.h_payto 1391 IS 'identifies the account this is about'; 1392 COMMENT ON COLUMN kyc_attributes.legitimization_process_serial_id 1393 IS 'serial ID of the legitimization process that resulted in these attributes, NULL if the attributes are from a form directly supplied by the account owner via a form'; 1394 COMMENT ON COLUMN kyc_attributes.collection_time 1395 IS 'when were these attributes collected'; 1396 COMMENT ON COLUMN kyc_attributes.expiration_time 1397 IS 'when are these attributes expected to expire'; 1398 COMMENT ON COLUMN kyc_attributes.trigger_outcome_serial 1399 IS 'ID of the outcome that was returned by the AML program based on the KYC data collected'; 1400 COMMENT ON COLUMN kyc_attributes.encrypted_attributes 1401 IS 'encrypted JSON object with the attribute data the check provided'; 1402 1403 CREATE TABLE aml_history 1404 (aml_history_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY 1405 ,h_payto BYTEA CHECK (LENGTH(h_payto)=32) 1406 REFERENCES wire_targets (wire_target_h_payto) 1407 ,outcome_serial_id INT8 NOT NULL 1408 REFERENCES legitimization_outcomes (outcome_serial_id) 1409 ,justification TEXT NOT NULL 1410 ,decider_pub BYTEA CHECK (LENGTH(decider_pub)=32) 1411 ,decider_sig BYTEA CHECK (LENGTH(decider_sig)=64); 1412 1413 COMMENT ON TABLE aml_history 1414 IS 'Records decisions by AML staff with the respective signature and free-form justification.'; 1415 COMMENT ON COLUMN aml_history.outcome_serial_id 1416 IS 'Actual outcome for the account (included in what decider_sig signs over)'; 1417 COMMENT ON COLUMN aml_history.decider_sig 1418 IS 'Signature key of the staff member affirming the AML decision; of type AML_DECISION'; 1419 1420 CREATE TABLE kyc_events 1421 (kyc_event_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY 1422 ,event_timestamp INT8 NOT NULL 1423 ,event_type TEXT NOT NULL); 1424 1425 COMMENT ON TABLE kyc_events 1426 IS 'Records of key events for statistics. Populated via triggers.'; 1427 COMMENT ON COLUMN kyc_events.event_type 1428 IS 'Name of the event, such as account-open or sar-filed'; 1429 1430 CREATE INDEX kyc_event_index 1431 ON kyc_events(event_type,event_timestamp); 1432 1433 1434 The ``jmeasures`` JSON in the ``legitimization_measures`` 1435 table is of type `LegitimizationMeasures`. 1436 1437 The ``jnew_rules`` JSON in the ``legitimization_outcomes`` 1438 table is of type `LegitimizationRuleSet`. 1439 1440 The ``jproperties`` JSON in the ``legitimization_outcomes`` table is of 1441 type `AccountProperties`. 1442 1443 1444 KYC forms 1445 ^^^^^^^^^ 1446 1447 The KYC SPA run by clients needs to support three TYPEs of checks. INFO is 1448 only about displaying the provided information, LINK is about setting up an 1449 exteral KYC check and redirecting there. FORM is about displaying a particular 1450 (HTML) form to the user and POSTing the entered information directly with the 1451 exchange. Here we describe the forms that must be supported: 1452 1453 * **CHOICE**: Asks the client a multiple-choice question. The context must 1454 include "choices: string[]" with a list of choices to show. Used, for 1455 example, to ask a client if they are an individual or a business. The 1456 resulting HTML FORM field name must be "choice" and it must be mapped to 1457 strings from the choices list. 1458 1459 * **UPLOAD**: Asks the client to upload a single file. 1460 The context must include a ``validity_duration`` which 1461 will be converted to the ``expiration_time`` for 1462 the uploaded data. The context may furthermore include 1463 ``extensions?: string[]`` with a list of allowed file extensions the client's 1464 file must end with (e.g. "png", "pdf", "gif"). In the absence of this 1465 context, any file may be uploaded. The context may also include a 1466 ``size_limit?: Integer`` with the maximum file size in bytes that can be 1467 uploaded. The resulting HTTP POST should provide at least two fields, "filename" and 1468 "filedata". "filename" must be set to the basename of the original file (to 1469 the extend that it is available), and "filedata" to the base64-encoding of 1470 the uploaded data. 1471 1472 As with other SPA checks, the KYC form should also show 1473 the description of the check. 1474 1475 1476 Merchant modifications 1477 ^^^^^^^^^^^^^^^^^^^^^^ 1478 1479 A new setting is required where the merchant backend can be configured for a 1480 business (default) or individual. 1481 1482 We introduce new ``kyc_ok``, ``aml_decision``, ``kyc_timestamp`` and 1483 ``exchange_kyc_serial`` fields into a new table ``merchant_kyc`` with primary 1484 keys ``exchange_url`` and ``account_serial``. This status is updated whenever 1485 a deposit is created or tracked, or whenever the mechant backend receives a 1486 ``/kyc-check/`` response from the exchange. Initially, 1487 ``exchange_kyc_serial`` is zero, indicating that the merchant has not yet made 1488 any deposits and thus does not have an account at the exchange. 1489 1490 A new private endpoint ``/kyc`` is introduced which allows frontends to 1491 request the ``/kyc`` status of any configured account (including with long 1492 polling). If the KYC status is negative or the ``kyc_timestamp`` not recent 1493 (say older than one month), the merchant backend will re-check the KYC status 1494 at the exchange (and update its cached status). The endpoint then returns 1495 either that the KYC is OK, or information (same as from the exchange endpoint) 1496 to begin the KYC process. 1497 1498 The merchant backend uses the new field to remember that a KYC is pending 1499 (after detection in ``taler-merchant-depositcheck``) and the SPA then shows a 1500 notification whenever the staff is logged in to the system. The notification 1501 can be hidden for the current day (remembered in local storage). 1502 1503 The notification links to a (new) KYC status page. When opened, the KYC SPA 1504 first re-checks the KYC status with the exchange. If the KYC is still 1505 unfinished, that SPA will show forms, links or contact information to begin 1506 the KYC process (for example, redirecting to the OAuth 2.0 login page of the 1507 legitimization resource server), otherwise it shows that the KYC process is 1508 done. If the KYC is unfinished, the merchant SPA should use long-polling on 1509 the KYC status on this page to ensure it is always up-to-date, and change to 1510 ``KYC satisfied`` should the long-poller return with positive news. 1511 1512 .. note:: 1513 1514 Semi-related: The TMH_setup_wire_account() is changed to use 1515 128-bit salt values (to keep ``deposits`` table small) and checks for salt 1516 to be well-formed should be added "everywhere". 1517 1518 1519 1520 Bank requirements 1521 ^^^^^^^^^^^^^^^^^ 1522 1523 The exchange primarily requires a KYC provider to be operated by the 1524 bank that offers an endpoint for with an API implemented by one of 1525 the logic plugins (and the respective legitimization configuration). 1526 1527 1528 Logic plugins 1529 ^^^^^^^^^^^^^ 1530 1531 The ``$PROVIDER_SECTION`` is based on the name of the configuration section, 1532 not on the name of the logic plugin (that we call ``$LOGIC``). Using the 1533 configuration section, the exchange then determines the logic plugin to use. 1534 1535 This section describes the general API for all of the supported KYC providers, 1536 as well as some details of how this general API could be implemented by the 1537 logic for different APIs. 1538 1539 1540 General KYC Logic Plugin API 1541 ---------------------------- 1542 1543 This section provides a sketch of the proposed API for the KYC logic plugins. 1544 1545 * initiation of KYC check (``kyc-check``): 1546 1547 - inputs: 1548 + provider_section (for additional configuration) 1549 + h_payto 1550 - outputs: 1551 + success/provider-failure 1552 + redirect URL (or NULL) 1553 + provider_user_id (or NULL) 1554 + provider_legitimization_id (or NULL) 1555 1556 * KYC status check (``kyc-proof``): 1557 1558 - inputs: 1559 + provider_section (for additional configuration) 1560 + h_payto 1561 + provider_user_id (or NULL) 1562 + provider_legitimization_id (or NULL) 1563 - outputs: 1564 + success/pending/user-aborted/user-failure/provider-failure status code 1565 + HTML response for end-user 1566 1567 * Webhook notification handler (``kyc-webhook``): 1568 1569 - inputs: 1570 + HTTP method (GET/POST) 1571 + rest of URL (after provider_section) 1572 + HTTP body (if applicable!) 1573 - outputs: 1574 + success/pending/user-aborted/user-failure/provider-failure status code 1575 + h_payto (for DB status update) 1576 + HTTP response to be returned to KYC provider 1577 1578 The plugins do not directly interact with the database, the caller sets the 1579 expiration on ``success`` and also updates ``provider_user_id`` and 1580 ``provider_legitimization_id`` in the tables as required. 1581 1582 1583 For the webhook, we need a way to lookup ``h_payto`` by other data, so the 1584 KYC logic plugin API should be provided a method lookup with: 1585 1586 - inputs: 1587 1588 + ``provider_section`` 1589 + ``provider_legitimization_id`` 1590 - outputs: 1591 1592 + ``h_payto`` 1593 + ``legitimization_process_row`` 1594 1595 1596 OAuth 2.0 specifics 1597 ------------------- 1598 1599 In terms of configuration, the OAuth 2.0 logic requires the respective client 1600 credentials to be configured apriori to enable access to the legitimization 1601 service. 1602 1603 For the ``/kyc-check/`` endpoint, the OAuth 2.0 logic may need to create and 1604 store a nonce to be used during ``/kyc-proof/``, depending on the OAuth 1605 variant used. This may require another exchange table. The OAuth 2.0 process 1606 must then be set up to end at the new ``/kyc-proof/$PROVIDER_ID/`` endpoint. 1607 1608 This ``/kyc-proof/oauth2/`` endpoint must query the OAuth 2.0 server using the 1609 ``code`` argument provided as a query parameter. Based on the result, it then 1610 updates the KYC table of the exchange with the legitimization status and 1611 returns a human-readable KYC status page. 1612 1613 The ``/kyc-webhook/`` is not applicable. 1614 1615 1616 Persona specifics 1617 ----------------- 1618 1619 We would use the hosted flow. Endpoints return a ``request-id``, which we should 1620 log for diagnosis. 1621 1622 For ``/kyc-check/``: 1623 1624 * Post to ``/api/v1/accounts`` using ``reference-id`` set to our ``h_payto``. 1625 Returns ``id`` (account_id). 1626 1627 * Create ``/verify`` endpoint using ``template-id`` (from configuration), 1628 and ``account_id`` (from previous step) and a ``reference-id`` (use 1629 the ``legitimization_serial_id`` for the new process). Set 1630 ``redirect-uri`` to ``/kyc-proof/$PROVIDER_ID/``. However, we cannot 1631 rely on the user clicking this, so we must also configure a webhook. 1632 The request returns a '``verification-id``. That we store under 1633 the ``provider_legitimization_id`` in the database. 1634 1635 For ``/kyc-proof/``: 1636 1637 * Use the ``/api/v1/verifications`` endpoint to get the verification 1638 status. Requires the ``verification-id`` from the previous step. 1639 Results include: created/pending/completed/expired (aborted)/failed. 1640 1641 For ``/kyc-webhook/``: 1642 1643 * The webhook is authenticated using a shared secret, which should 1644 be in the configuration. So all we should have to do is parse 1645 the POSTed body to find the status and the ``verification-id`` to 1646 lookup ``h_payto`` and return the result. 1647 1648 1649 KYC AID specifics 1650 ----------------- 1651 1652 For ``/kyc-check/``: 1653 1654 * Post to ``/applicants`` with a type (person or company) to 1655 obtain ``applicant_id``. Store that under ``provider_user_id``. 1656 ISSUE: *we* need to get the company_name, business_activity_id 1657 and registration_country before this somehow! 1658 1659 * start with create form URL ``/forms/$FORM_ID/urls`` 1660 providing our ``h_payto`` as the ``external_applicant_id``, 1661 using the ``applicant_id`` from above, 1662 and the ``/kyc-proof/$PROVIDER_ID`` for the ``redirect_url``. 1663 1664 * redirect customer to the ``form_url``, 1665 store the ``verification_id`` under ``provider_legitimization_id`` 1666 in the database. 1667 1668 For ``/kyc-proof/``: 1669 1670 * Not needed, just return an error. 1671 1672 For ``/kyc-webhook/``: 1673 1674 * For security, we should probably simply trigger the GET on 1675 ``/verifications/{verification_id}`` to not trust an unsigned POST 1676 to tell us anything for sure. The result is then returned. 1677 1678 1679 Types of KYC events 1680 ^^^^^^^^^^^^^^^^^^^ 1681 1682 The ``/aml/$OFFICER_PUB/kyc-statistics`` endpoint exposes statistics for 1683 various KYC event types. 1684 1685 We will initially support the use of the following types of KYC events in the 1686 SPA (and have a dialog to show the total number of any of these for any 1687 specified time range): 1688 1689 * account-open 1690 * account-closed 1691 * voluntary-sar 1692 * mandatory-sar 1693 * pep-started 1694 * pep-ended 1695 * risky-started 1696 * risky-ended 1697 * account-frozen 1698 * account-unfrozen 1699 1700 Based on these, the SPA should also be albe to show active 1701 statistics (for any given timestamp) on the total number of: 1702 1703 * open accounts 1704 * frozen accounts 1705 * high-risk accounts 1706 * PEPs served 1707 1708 .. note:: 1709 1710 This can be done by simply running the queries with 1711 a start time of zero and subtracting. 1712 1713 1714 Alternatives 1715 ============ 1716 1717 We could also store the access token (returned by OAuth 2.0), but that seems 1718 slightly more dangerous and given the close business relationship is 1719 unnecessary. Furthermore, not all APIs offer this. 1720 1721 We could extend the KYC logic API to return key attributes about the user 1722 (such as legal name, phone number, address, etc.) which we could then sign and 1723 return to the user. This would be useful in P2P payments to identify the 1724 origin of an invoice. However, we might want to be careful to not disclose 1725 the key attributes via the API by accident. This could likely be done by 1726 limiting access to the respective endpoint to messages with a signature by the 1727 reserve private key (which is the only case where we care to certify things 1728 anyway). 1729 1730 1731 Drawbacks 1732 ========= 1733 1734 1735 Discussion / Q&A 1736 ================ 1737 1738 (This should be filled in with results from discussions on mailing lists / personal communication.) 1739 1740 1741 If you have questions, remarks or suggestions regarding this information, 1742 please feel free to leave a comment at our 1743 `TALER Integration Community Hub <https://ich.taler.net/t/gnu-taler-exchange-documentation/78>`_.