[taler-docs] branch master updated: more docs

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new fb3be9f  more docs
fb3be9f is described below

commit fb3be9fd8a33ba17121363b6ac6f850927d2a697
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Tue Mar 30 19:20:53 2021 +0200

    more docs
---
 anastasis.rst | 112 ++++++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 85 insertions(+), 27 deletions(-)

diff --git a/anastasis.rst b/anastasis.rst
index b27b516..8eab461 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1219,6 +1219,7 @@ providers that accept payments in the selected currency:
       ],
       "authentication_providers": {
         "http://localhost:8089/": {
+          "http_status": 200,
           "methods": [
             { "type" : "question",
               "usage_fee" : "EUR:0.0" },
@@ -1235,6 +1236,7 @@ providers that accept payments in the selected currency:
           "salt": "CXAPCKSH9D3MYJTS9536RHJHCW"
         },
         "http://localhost:8088/": {
+          "http_status": 200,
           "methods": [
             { "type" : "question",
               "usage_fee" : "EUR:0.01" },
@@ -1286,8 +1288,9 @@ that must be provided includes:
 
 The authentication providers are listed under a key that is the
 base URL of the service. For each provider, the following
-information is provided:
+information is provided if the provider was successfully contacted:
 
+  - **http_status**: HTTP status code, always 200 on success.
   - **methods**: array of authentication methods supported by this
     provider. Includes the **type** of the authentication method
     and the **usage_fee** (how much the user must pay for authorization
@@ -1310,14 +1313,22 @@ information is provided:
     and must never change for a given provider.  The salt is
     base32 encoded.
 
-FIXME: specify what will be provided in case GET /config fails!
+If contacting the provider failed, the information returned is:
+
+  - **http_status**: HTTP status code (if available, possibly 0 if
+    we did not even obtain an HTTP response).
+  - **error_code**: Taler error code, never 0.
 
 
 **add_provider**:
 
-This operation can be performed in state "USER_ATTRIBUTES_COLLECTING".
+This operation can be performed in state "USER_ATTRIBUTES_COLLECTING".  It
+adds one or more Anastasis providers to the list of providers the reducer
+should henceforth consider.  Note that removing providers is not possible at
+this time.
 
-Arguments (example):
+Here, the client must provide an array with the base URLs of the
+providers to add, for example:
 
 .. code-block:: json
 
@@ -1328,9 +1339,10 @@ Arguments (example):
       ]
     }
 
-Example for an expected new state (presuming service on port 8089 is
-unreachable, service on port 8088 was previously known, and service on port
-8888 was now added):
+Note that existing providers will remain in the state.  The following is an
+example for an expected new state where the service on port 8089 is
+unreachable, the service on port 8088 was previously known, and service on
+port 8888 was now added:
 
 .. code-block:: json
 
@@ -1342,6 +1354,7 @@ unreachable, service on port 8088 was previously known, 
and service on port
           "http_status": 0
         },
         "http://localhost:8088/": {
+          "http_status": 200,
           "methods": [
             { "type" : "question",
               "usage_fee" : "EUR:0.01" },
@@ -1383,7 +1396,11 @@ Backup transitions
 
 **enter_user_attributes:**
 
-Arguments (example):
+This transition provides the user's personal attributes. The specific set of
+attributes required depends on the country of residence of the user.  Some
+attributes may be optional, in which case they should be omitted entirely
+(that is, not simply be set to ``null`` or an empty string).  Example
+arguments would be:
 
 .. code-block:: json
 
@@ -1391,13 +1408,18 @@ Arguments (example):
       "identity_attributes": {
         "full_name": "Max Musterman",
         "social_security_number": "123456789",
-        "birth_year": 2000,
-        "birth_month": 1,
-        "birth_day": 1
-      }
+        "birthdate": "2000-01-01",
+        "birthplace": "Earth"
+     }
     }
 
-Expected new state:
+Note that at this stage, the state machines between backup and
+recovery diverge and the ``recovery_state`` will begin to look
+very different from the ``backup_state``.
+
+For backups, if all required attributes are present, the reducer will
+transition to an ``AUTHENTICATIONS_EDITING`` state with the attributes added
+to it:
 
 .. code-block:: json
 
@@ -1406,20 +1428,48 @@ Expected new state:
       "identity_attributes": {
         "full_name": "Max Musterman",
         "social_security_number": "123456789",
-        "birth_year": 2000,
-        "birth_month": 1,
-        "birth_day": 1
+        "birthdate": "2000-01-01",
+        "birthplace": "Earth"
       }
     }
 
+If required attributes are missing, do not match the required regular
+expression or fail the custom validation logic, the reducer SHOULD transition
+to an error state indicating what was wrong about the input.  A reducer that
+does not support some specific validation logic MAY accept the invalid input
+and proceed anyway.  The error state will include a Taler error code that
+is specific to the failure, and optional details.  Example:
 
-**add_authentication**:
+.. code-block:: json
+
+    {
+      "backup_state": "ERROR",
+      "code": 8404,
+      "hint": "An input did not match the regular expression.",
+      "detail": "social_security_number"
+    }
 
-Note that the "instructions" must be given in Crockford Base32
-encoding. We use here ASCII-Text that is both, but in reality,
-any text must be first Crockford Base32 encoded!
+Clients may safely repeat this transition to validate the user's inputs
+until they statisfy all of the constraints.  This way, the user interface
+does not have to perform the input validation directly.
 
-Arguments (example):
+
+**add_authentication**:
+
+This transition adds an authentication method.  The method must be supported
+by one or more providers that are included in the current state.  Adding an
+authentication method requires specifying the ``type`` and ``instructions`` to
+be given to the user.  The ``challenge`` is encrypted and stored at the
+Anastasis provider. The specific semantics of the value depend on the
+``type``.  Typical challenges values are a phone number (to send an SMS to),
+an e-mail address (to send a PIN code to) or the answer to a security
+question.  Note that these challenge values will still be encrypted (and
+possibly hashed) before being given to the Anastasis providers.
+
+Note that the ``challenge`` must be given in Crockford Base32 encoding, as it
+MAY include binary data (such as a photograph of the user).  In the latter
+case, the optional ``mime_type`` field must be provided to give the MIME type
+of the value encoded in ``challenge``.
 
 .. code-block:: json
 
@@ -1429,11 +1479,12 @@ Arguments (example):
         "type": "question",
         "mime_type" : "text/plain",
         "instructions" : "What is your favorite GNU package?",
-        "challenge" : "poke",
+        "challenge" : "E1QPPS8A",
       }
     }
 
-Expected new state:
+If the information provided is valid, the reducer will add the new
+authentication method to the array of authentication methods:
 
 .. code-block:: json
 
@@ -1444,11 +1495,12 @@ Expected new state:
           "type": "question",
           "mime_type" : "text/plain",
           "instructions" : "What is your favorite GNU package?",
-          "challenge" : "poke",
+          "challenge" : "E1QPPS8A",
         },
         {
           "type": "email",
-          "challenge": "max@musterman.de"
+          "instructions" : "E-mail to user@*le.com",
+          "challenge": "ENSPAWJ0CNW62VBGDHJJWRVFDM50"
         }
       ]
     }
@@ -1456,7 +1508,9 @@ Expected new state:
 
 **delete_authentication**:
 
-Arguments (example):
+This transition can be used to remove an authentication method from the
+array of authentication methods. It simply requires the index of the
+authentication method to remove. Note that the array is 0-indexed:
 
 .. code-block:: json
 
@@ -1464,7 +1518,9 @@ Arguments (example):
       "auth_method_index": 1
     }
 
-Expected new state:
+Assuming we begin with the state from the example above, this would
+remove the ``email`` authentication method, resulting in the following
+response:
 
 .. code-block:: json
 
@@ -1480,6 +1536,8 @@ Expected new state:
       ]
     }
 
+If the index is invalid, the reducer will transition into an ERROR state.
+
 
 **next** (from "AUTHENTICATIONS_EDITING"):
 

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.