update KYC DD based on discussions with Martin

1 files changed, 26 insertions, 5 deletions

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
 ^^^^^^^^^^^^^^^^^