commit fb3be9fd8a33ba17121363b6ac6f850927d2a697
parent 7a05b442fe9c3f22144a2db5151bbf1cb7eadca1
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 30 Mar 2021 19:20:53 +0200
more docs
Diffstat:
| M | anastasis.rst | | | 112 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------- |
1 file changed, 85 insertions(+), 27 deletions(-)
diff --git 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"):
