summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-10-06 09:10:47 +0200
committerChristian Grothoff <christian@grothoff.org>2021-10-06 09:10:47 +0200
commit5c2d90681490515ea3daf8de53dbcbbc166133f4 (patch)
treee0ebfcb6bad4ff009fb914947058075a97fda876
parentb5a2ce02c784d2303e8af203aa5f1a0a930e9c6d (diff)
downloaddocs-5c2d90681490515ea3daf8de53dbcbbc166133f4.tar.gz
docs-5c2d90681490515ea3daf8de53dbcbbc166133f4.tar.bz2
docs-5c2d90681490515ea3daf8de53dbcbbc166133f4.zip
update KYC DD based on discussions with Martin
-rw-r--r--core/api-exchange.rst62
-rw-r--r--design-documents/023-taler-kyc.rst31
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
^^^^^^^^^^^^^^^^^