commit 4a8ae5654906acf850eebc7807a0fd47575eae44
parent 52fcb58d64b1b7e0454d47fee695ebe021540ae5
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 12 Sep 2024 12:02:18 +0200
document KycStructuredFormData and also LINK attribute data, addressing #9187
Diffstat:
| M | taler-kyc-manual.rst | | | 74 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- |
1 file changed, 73 insertions(+), 1 deletion(-)
diff --git a/taler-kyc-manual.rst b/taler-kyc-manual.rst
@@ -475,6 +475,73 @@ input.
The outcome of *any* check is stored encrypted in the ``kyc_attributes``
table. It MUST include an ``expiration_time``.
+The INFO Type
+^^^^^^^^^^^^^
+
+When using KYC checks of type "INFO", the KYC-SPA
+will simply show the given DESCRIPTION (or translations
+from DESCRIPTION_I18N) to the user.
+
+
+The FORM Type
+^^^^^^^^^^^^^
+
+When using KYC checks of type "FORM", the KYC-SPA
+will show different forms based on "FORM_NAME" while
+also showing the user the text from DESCRIPTION
+as instructions.
+
+Some of the forms may be further parameterized via
+the context in which the form is executed.
+
+.. note::
+
+ For build-in forms, it should in the future not be
+ necessary to specify the context requirements via
+ REQUIRES as the KYC SPA should inform the exchange
+ about the requirements of each form automatically.
+ However, this is not yet implemented, see #9187.
+
+When forms are submitted, the exchange converts the form data into key-value
+pairs where the key is the form field name and the value is of type
+`KycStructuredFormData`. The respective AML program can then evaluate the data from the form
+submission from `attributes`.
+
+ .. ts:def:: KycStructuredFormData
+
+ interface KycStructuredFormData {
+
+ // Content type. Missing if unknown.
+ content_type?: string;
+
+ // Name of the uploaded file. Missing if unknown
+ // or this was not a file upload.
+ filename?: string;
+
+ // Base32-encoded binary form value. Only present
+ // if form data was determined to be binary data.
+ data?: string;
+
+ // Text form value. Only present if the form data
+ // was determined to be in textual format.
+ text?: string;
+
+ }
+
+The LINK Type
+^^^^^^^^^^^^^
+
+When using KYC checks of type "FORM", the KYC-SPA will show a link that allows
+the user to begin the KYC process at an external provider under the given
+DESCRIPTION.
+
+The external providers are expected to yield KYC attributes in the form of
+key-value pairs where the list of key is defined in the GANA
+``gnu-taler-kyc-attributes`` registry, which also defines the format of each
+attribute. External providers may not directly yield attributes using the
+correct encodings, thus CONVERTER programs are typically used to convert
+external attribute data into the standardized format.
+
Configuration of legitimization rules
-------------------------------------
@@ -626,10 +693,15 @@ administrator.
// JSON object that captures the
// output of a ``[kyc-provider-]`` or (HTML) FORM.
- // The keys in the JSON object will be the attribute
+ // In the case of KYC data provided by providers,
+ // the keys in the JSON object will be the attribute
// names and the values must be strings representing
// the data. In the case of file uploads, the data
// MUST be base64-encoded.
+ // In the case of KYC data provided by HTML FORMs, the
+ // keys will match the HTML FORM field names and
+ // the values will use the `KycStructuredFormData`
+ // encoding.
attributes: Object;
// JSON array with the results of historic
