commit 1173ab8e99c321f5d9db780cf49142b1176612bf
parent 6d0bf4fa5aded1a218383b2fa4f759907f2fe085
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 31 Mar 2021 12:34:10 +0200
expand docs
Diffstat:
| M | anastasis.rst | | | 84 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- |
1 file changed, 73 insertions(+), 11 deletions(-)
diff --git a/anastasis.rst b/anastasis.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2019 Taler Systems SA
+ Copyright (C) 2019. 2021 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
@@ -1942,23 +1942,85 @@ a state where the user can choose which challenges to satisfy:
{
"recovery_state": "CHALLENGE_SELECTING",
- FIXME: document rest of state here!
+ "recovery_information": {
+ "challenges": [
+ {
+ "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G",
+ "cost": "TESTKUDOS:0",
+ "type": "question",
+ "instructions": "q1"
+ },
+ {
+ "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+ "cost": "TESTKUDOS:0",
+ "type": "email",
+ "instructions": "e-mail address m?il@f*.bar"
+ }
+ ],
+ "policies": [
+ [
+ {
+ "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G"
+ },
+ {
+ "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0"
+ }
+ ]
+ ],
+ "provider_url": "http://localhost:8088/",
+ "version": 1 // FIXME: wrong in code!
+ },
+ "recovery_document": {
+ ...
+ }
}
+The ``recovery_document`` is an internal representation of the recovery
+information and of no concern to the user interface. The pertinent information
+is in the ``recovery_information``. Here, the ``challenges`` array is a list
+of possible challenges the user could attempt to solve next, while ``policies``
+is an array of policies, with each policy being an array of challenges.
+Satisfying all of the challenges of one of the policies will enable the secret
+to be recovered. The ``provider_url`` from where the recovery document was
+obtained and its ``version`` are also provided. Each challenge comes with
+four mandatory fields:
+
+ - **uuid**: a unique identifier of the challenge; this is what the
+ UUIDs in the policies array refer to, but also this UUID may be
+ included in messages sent to the user. They allow the user to
+ distinguish different PIN/TANs should say the same phone number be
+ used for SMS-authentication with different providers.
+ - **cost**: this is the amount the Anastasis provider will charge
+ to allow the user to pass the challenge.
+ - **type**: this is the type of the challenge, as a string.
+ - **instructions**: contains additional important hints for the user
+ to allow the user to satisfy the challenge. It typically includes
+ an abbreviated form of the contact information or the security
+ question. Details depend on ``type``.
+
If a recovery document was not found, either the user never performed
a backup, entered incorrect attributes or used a provider not yet in
the list of Anastasis providers. Hence, the user must now either
select a different provider, or go ``back`` and update the identity
-attributes. In the case a recovery document was not found, an
-example for the new state is:
+attributes. In the case a recovery document was not found, the
+transition fails, returning the error code and a human-readable error
+message together with a transition failure:
.. code-block:: json
{
- "recovery_state": "CHALLENGE_SELECTING",
- FIXME: document rest of state here!
+ "recovery_state": "ERROR",
+ "error_message": "account unknown to Anastasis server",
+ "error_code": 9,
}
+Here, the ``error_code`` is from the ``enum ANASTASIS_RecoveryStatus``
+and describes precisely what failed about the download, while the
+``error_message`` is a human-readable (English) explanation of the code.
+However, in general it should be sufficient to display the slightly
+more generic Taler error code that is returned with the new state.
+
+
**change_version:**
Even if a recovery document was found, it is possible that the user
@@ -1972,13 +2034,13 @@ which takes a provider URL and policy version as arguments:
{
"provider_url": "https://localhost:8080/",
- "version": 2 // FIXME: correct like this?
+ "version": 2
}
-The resulting states are the same as those of the
-``enter_user_attributes`` transition, except that the recovery
-document version is not necessarily the latest available version
-at the provider.
+Note that using a version of 0 implies fetching ``the latest version``. The
+resulting states are the same as those of the ``enter_user_attributes``
+transition, except that the recovery document version is not necessarily the
+latest available version at the provider.
**select_challenge:**
