write first KYC setup documentation in exchange manual

1 files changed, 252 insertions, 0 deletions

diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 84ac4261..15dc90ae 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1365,6 +1365,246 @@ the exchange would return ``TERMS_DIR/en/v1.html`` lacking an HTML version in
 French.
 
 
+KYC Configuration
+-----------------
+
+To legally operate, Taler exchange operators may have to comply with KYC
+regulation that requires financial institutions to identify parties involved
+in transactions at certain points.
+
+Taler permits an exchange to require KYC data under the following circumstances:
+
+  * Customer withdraws money over a threshold
+  * Wallet receives (via refunds) money resulting in a balance over a threshold
+  * Wallet receives money via P2P payments over a threshold
+  * Merchant receives money over a threshold
+  * Reserve is "opened" for invoicing or tipping (**planned feature**)
+
+
+Taler KYC Terminology
+^^^^^^^^^^^^^^^^^^^^^
+
+* **Check**: A check establishes a particular attribute of a user, such as
+  their name based on an ID document and lifeness, mailing address, phone
+  number, taxpayer identity, etc.
+
+* **Type of operation**: The operation type determines which Taler-specific
+  operation has triggered the KYC requirement. We support four types of
+  operation: withdraw (by customer), deposit (by merchant), P2P receive (by
+  wallet) and (high) wallet balance.
+
+* **Condition**: A condition specifies when KYC is required. Conditions
+  include the *type of operation*, a threshold amount (e.g. above EUR:1000)
+  and possibly a time period (e.g. over the last month).
+
+* **Cost**: Metric for the business expense for a KYC check at a certain
+  *provider*. Not in any currency, costs are simply relative and non-negative
+  values. Costs are considered when multiple choices are allowed by the
+  *configuration*.
+
+* **Expiration**: KYC legitimizations may be outdated. Expiration rules
+  determine when *checks* have to be performed again.
+
+* **Legitimization rules**: The legitimization rules determine under which
+  *conditions* which *checks* must be performend and the *expiration* time
+  period for the *checks*.
+
+* **Logic**: Logic refers to a specific bit of code (realized as an exchange
+  plugin) that enables the interaction with a specific *provider*.  Logic
+  typically requires configuration for access control (such as an
+  authorization token) and possibly the endpoint of the specific *provider*
+  implementing the respective API.
+
+* **Provider**: A provider performs a specific set of *checks* at a certain
+  *cost*. Interaction with a provider is performed by provider-specific
+  *logic*.
+
+
+KYC Configuration Options
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The KYC configuration determines the *legitimization rules*, and specifies
+which providers offer which *checks* at what *cost*.
+
+The configuration specifies a set of providers, one per configuration section. The names of the configuration
+sections must being with ``kyc-proider-`` followed by
+an arbitrary ``$PROVIDER_ID``:
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-kyc-providers.conf
+
+  [kyc-provider-$PROVIDER_ID]
+  # How expensive is it to use this provider?
+  # Used to pick the cheapest provider possible.
+  COST = 42
+  # Which plugin is responsible for this provider?
+  # Choices include "oauth2", "kycaid" and "persona".
+  LOGIC = oauth2
+  # Which type of user does this provider handle?
+  # Either INDIVIDUAL or BUSINESS.
+  USER_TYPE = INDIVIDUAL
+  # Which checks does this provider provide?
+  # List of strings, no specific semantics.
+  PROVIDED_CHECKS = SMS GOVID PHOTO
+  # Plus additional logic-specific options, e.g.:
+  AUTHORIZATION_TOKEN = superdupersecret
+  FORM_ID = business_legi_form
+  # How long is the check considered valid?
+  EXPIRATION = 3650d
+
+The configuration also must specify a set of legitimization requirements, again one
+per configuration section:
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-kyc-rules.conf
+
+  [kyc-legitimization-$RULE_NAME]
+  # Operation that triggers this legitimization.
+  # Must be one of WITHDRAW, DEPOSIT, P2P-RECEIVE
+  # or WALLET-BALANCE.
+  OPERATION_TYPE = WITHDRAW
+  # Required checks to be performed.
+  # List of strings, must individually match the
+  # strings in one or more provider's PROVIDED_CHECKS.
+  REQUIRED_CHECKS = SMS GOVID
+  # Threshold amount above which the legitimization is
+  # triggered.  The total must be exceeded in the given
+  # timeframe.
+  THRESHOLD = KUDOS:100
+  # Timeframe over which the amount to be compared to
+  # the  THRESHOLD is calculated.  Can be 'forever'.
+  # Ignored for WALLET-BALANCE.
+  TIMEFRAME = 30d
+
+
+OAuth 2.0 specifics
+^^^^^^^^^^^^^^^^^^^
+
+In terms of configuration, the OAuth 2.0 logic requires the respective client
+credentials to be configured apriori to enable access to the legitimization
+service.  The OAuth 2.0 configuration options are:
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-oauth2.conf
+  [kyc-provider-example-oauth2]
+  LOGIC = oauth2
+  # (generic options omitted)
+  # How long is the KYC check valid?
+  KYC_OAUTH2_VALIDITY = forever
+
+  # URL to which we redirect the user for the login process
+  # FIXME: we should rename this option to AUTHORIZATION_URL
+  KYC_OAUTH2_LOGIN_URL = "http://kyc.example.com/authorization"
+  # URL where we POST the user's authentication information
+  # FIXME: we should rename this option to TOKEN_URL
+  KYC_OAUTH2_AUTH_URL = "http://kyc.example.com/token"
+  # URL of the user info access point.
+  KYC_OAUTH2_INFO_URL = "http://kyc.example.com/info"
+
+  # Where does the client get redirected upon completion?
+  KYC_OAUTH2_POST_URL = "http://example.com/thank-you"
+
+  # For authentication to the OAuth2.0 service
+  KYC_OAUTH2_CLIENT_ID = testcase
+  KYC_OAUTH2_CLIENT_SECRET = password
+
+  # Mustach template that converts OAuth2.0 data about the user
+  # into GNU Taler standardized attribute data.
+  #
+  KYC_OAUTH2_ATTRIBUTE_TEMPLATE = "{"fullname":"{{last_name}}, {{first_name}}","phone":"{{phone}}"}"
+
+The ``KYC_OAUTH2_ATTRIBUTE_TEMPLATE`` provides a generic way to convert data
+returned by an OAuth-provider into the internal format used by the exchange.
+
+The Challenger service for address validation supports OAuth2.0, but does not
+have a static LOGIN_URL. Instead, the LOGIN_URL must be enabled by the client
+using a special authenticated request to the Challenger's ``/setup`` endpoint.
+The exchange supports this by appending ``#setup`` to the LOGIN_URL (note
+that fragments are illegal in OAuth2.0 URLs).  Be careful to quote the URL,
+as ``#`` is otherwise interpreted as the beginning of a comment by the
+configuration file syntax.
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-challenger-oauth2.conf
+  [kyc-provider-challenger-oauth2]
+  LOGIC = oauth2
+  KYC_OAUTH2_LOGIN_URL = "http://challenger.example.com/authorize/#setup"
+  KYC_OAUTH2_AUTH_URL = "http://challenger.example.com/token"
+  KYC_OAUTH2_INFO_URL = "http://challenger.example.com/info"
+
+
+Persona specifics
+^^^^^^^^^^^^^^^^^
+
+We use the hosted flow. The Persona endpoints return a ``request-id``, which
+we log for diagnosis.
+
+Persona should be configured to use the ``/kyc-webhook/`` endpoint of the
+exchange to notify the exchange about the completion of KYC processes.
+The webhook is authenticated using a shared secret, which should
+be in the configuration.
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-persona.conf
+
+  [kyclogic-persona]
+  # Webhook authorization token. Global for all uses
+  # of the persona provider!
+  WEBHOOK_AUTH_TOKEN = wbhsec_698b5a19-c790-47f6-b396-deb572ec82f9
+
+  [kyc-provider-example-persona]
+  LOGIC = persona
+  # (generic options omitted)
+
+  # How long is the KYC check valid?
+  KYC_PERSONA_VALIDITY = 365d
+
+  # Which subdomain is used for our API?
+  KYC_PERSONA_SUBDOMAIN = taler
+
+  # Authentication token to use.
+  KYC_PERSONA_AUTH_TOKEN = persona_sandbox_42
+
+  # Form to use.
+  KYC_PERSONA_TEMPLATE_ID = itempl_Uj6Xxxxx
+
+  # Where do we redirect to after KYC finished successfully.
+  KYC_PERSONA_POST_URL = "https://taler.net/"
+
+  # Salt to give to requests for idempotency.
+  # Optional.
+  # KYC_PERSONA_SALT = salt
+
+
+KYC AID specifics
+-----------------
+
+We use the hosted flow.
+
+KYCAID should be configured to use the ``/kyc-webhook/`` endpoint of the
+exchange to notify the exchange about the completion of KYC processes.
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-kycaid.conf
+
+  [kyc-provider-example-kycaid]
+  LOGIC = kycaid
+  # (generic options omitted)
+
+  # How long is the KYC check valid?
+  KYC_KYCAID_VALIDITY = 365d
+
+  # Authentication token to use.
+  KYC_KYCAID_AUTH_TOKEN = XXX
+
+  # Form to use.
+  KYC_KYCAID_FORM_ID = XXX
+
+  # URL to go to after the process is complete.
+  KYC_KYCAID_POST_URL = "https://taler.net/"
+
+
+
 .. _OfflineConfiguration:
 
 Setting up the offline signing key
@@ -1691,6 +1931,18 @@ of ``taler-exchange-offline``.
    under highly unusual (“emergency”) conditions and not in normal
    operation.
 
+AML Configuration
+-----------------
+
+The AML configuration steps are used to add or remove keys of exchange
+operator staff that are responsible for anti-money laundering (AML)
+compliance.  These AML officers are shown suspicious transactions and are
+granted access to the KYC data of an exchange. They can then investigate the
+transaction and decide on freezing or permitting the transfer. They may also
+request additional KYC data from the consumer and can change the threshold
+amount above which a further AML review is triggered.
+
+FIXME: describe use of taler-exchange-offline commands!
 
 
 Setup Linting