From 5c2d90681490515ea3daf8de53dbcbbc166133f4 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 6 Oct 2021 09:10:47 +0200 Subject: update KYC DD based on discussions with Martin --- core/api-exchange.rst | 62 ++++++++++++++++++++++++++++---------- design-documents/023-taler-kyc.rst | 31 ++++++++++++++++--- 2 files changed, 72 insertions(+), 21 deletions(-) diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 4f81f5b7..d25c2e52 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -3324,26 +3324,23 @@ KYC status updates This is a draft API that is not yet implemented. -.. http:POST:: /kyc/$PAYMENT_TARGET_UUID +.. http:GET:: /kyc-check/$PAYMENT_TARGET_UUID Check or update KYC status of a particular payment target. - Returns the current KYC status of the account and possibly - causes the exchange to inquire with its legitimization - resource server as to the KYC status of the respective - payment target. + Returns the current KYC status of the account and, if + negative, returns the URL where the KYC process can be + initiated using OAuth. **Request:** + :query h_payto=HASH: Specifies the hash of the payto:// URI of the payment + target. Weak security check used to authorize the status request. :query timeout_ms=NUMBER: *Optional.* If specified, the exchange will wait up to ``timeout_ms`` milliseconds if the payment target is currently not legitimized. Ignored if the payment target is already legitimized. Note that the legitimization would be triggered by another request to the same endpoint with a valid ``token``. - :query token=TOKEN: *Optional.* If specified, TOKEN must be an OAuth - access token that the exchange can use to verify that the user has - an account with the OAuth resource server that holds the - legitimization data. **Response:** @@ -3359,13 +3356,10 @@ KYC status updates :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus generally all accounts are simply considered legitimate. - :http:statuscode:`502 Bad Gateway`: - The exchange received an invalid reply from the OAuth-based - legitimization service. - :http:statuscode:`504 Gateway Timeout`: - The exchange did not receive a reply from the OAuth legitimization - service within the specified time period. Used when long-polling - for the result. + :http:statuscode:`401 Unauthorized`: + The provided hash does not match the payment target. + :http:statuscode:`404 Not found`: + The payment target is unknown. **Details:** @@ -3396,3 +3390,39 @@ KYC status updates kyc_url: string; } + + +.. http:GET:: /kyc-proof/$PAYMENT_TARGET_UUID + + Update KYC status of a particular payment target. Provides + the token to the exchange that allows it to verify that the + user has completed the KYC process. The HTTP method must be + a GET due to requirements from the OAuth 2.0 protocol. + + **Request:** + + :query code=CODE: OAuth 2.0 code argument. + :query state=CODE: OAuth 2.0 state argument. + + ..note:: + + Depending on the OAuth variant used, additional + query parameters may need to be passed here. + + **Response:** + + :http:statuscode:`302 Found`: + The KYC operation succeeded and the + payment target is now authorized to transact. + The browser is redirected to a human-readable + page configured by the exchange operator. + :http:statuscode:`401 Unauthorized`: + The provided OAuth 2.0 authentication token is invalid. + :http:statuscode:`404 Not found`: + The payment target is unknown. + :http:statuscode:`502 Bad Gateway`: + The exchange received an invalid reply from the OAuth-based + legitimization service. + :http:statuscode:`504 Gateway Timeout`: + The exchange did not receive a reply from the OAuth legitimization + service within a reasonable time period. diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst index 51d0427b..499b9c93 100644 --- a/design-documents/023-taler-kyc.rst +++ b/design-documents/023-taler-kyc.rst @@ -52,25 +52,33 @@ in the ``reserves_in``, ``wire_out`` and ``deposits`` tables as they can reference this table. In this table, we additionally store information related to the KYC status of the underlying payto://-URI. -A new ``/kyc/`` endpoint is based on the ``wire_targets`` serial +The new ``/kyc-check/`` endpoint is based on the ``wire_targets`` serial number. Access is ``authenticated`` by also passing the hash of the payto://-URI (weak authentication is acceptable, as the KYC status or the ability to initiate a KYC process are not very sensitive). Given this pair, -the ``/kyc/`` endpoint returns either the (positive) KYC status or redirects -the client (302) to the current stage of the KYC process. The redirection is +the ``/kyc-check/`` endpoint returns either the (positive) KYC status or +redirects the client (202) to the current stage of the KYC process. (The +endpoint may have to create and store a nonce to be used during +``/kyc-proof/``, depending on the OAuth variant used.) The redirection is offered using an HTTP-redirect for Web-based clients and a JSON body with information for triggering a browser-based KYC process using OAuth 2.0. +The OAuth 2.0 process is setup to end at a new ``/kyc-proof/`` endpoint. This +endpoint then updates the KYC table of the exchange with the legitimization +status (which is checked using OAuth 2.0). The endpoint also wakes up any +long-polling ``/kyc-check/`` requests. Naturally, the exchange's OAuth 2.0 +client credentials must be configured apriori with the legitimization service. + When withdrawing, the exchange checks if the KYC status is acceptable. If no KYC was done and if either the amount withdrawn over the last X days exceeds the threshold or the reserve received received a P2P transfer, then a ``202 -Accepted`` is returned which redirects the consumer to the new ``/kyc/`` +Accepted`` is returned which redirects the consumer to the new ``/kyc-check/`` handler. When depositing, the exchange checks the KYC status and if negative, returns an additional information field that tells the merchant the ``wire_target_serial`` number needed to begin the KYC process (this is independent of the amount) -at the new ``/kyc/`` handler. +at the new ``/kyc-check/`` handler. When tracking deposits, the exchange also adds the ``wire_target_serial`` to the reply if the KYC status is negative. @@ -147,11 +155,17 @@ migration with C logic (so not just SQL statements). -- ALTER TABLE deposits ADD COLUMN wire_target_serial_id INT8 NOT NULL, + ADD COLUMN salt BYTEA NOT NULL CHECK (LENGTH(salt)=64), DROP COLUMN h_wire, DROP COLUMN wire; COMMENT ON COLUMN deposits.wire_target_serial_id IS 'Identifies the target bank account and KYC status'; -- Complete transaction + -- + -- FIXME: 512-bit SALT is likely not specified/checked + -- anywhere in the code (salt==string), and we probably + -- should move to a 128-bit salt anyway! + -- COMMIT; @@ -190,6 +204,13 @@ unfinished, the SPA should use long-polling on the KYC status on this page to ensure it is always up-to-date, and change to ``KYC satisfied`` should the long-poller return with positive news. + ..note:: + + Semi-related: The TMH_setup_wire_account() should be changed to use + 128-bit salt values (to keep ``deposits`` table small) and checks for salt + to be well-formed should be added "everywhere". + + Bank requirements ^^^^^^^^^^^^^^^^^ -- cgit v1.2.3