[taler-docs] branch master updated: update anastasis state machine spec

[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 f4b5e48  update anastasis state machine spec
f4b5e48 is described below

commit f4b5e48d5667e9eb4126aa8e060db0f041ef2318
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Jul 18 06:34:26 2021 +0200

    update anastasis state machine spec
---
 anastasis.rst | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 140 insertions(+), 10 deletions(-)

diff --git a/anastasis.rst b/anastasis.rst
index 1c4e39e..0cca44b 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1068,6 +1068,8 @@ Overall, the reducer knows the following states:
                with an authentication method.
   - **POLICIES_PAYING**: The user needs to pay for storing the recovery policy 
document.
   - **BACKUP_FINISHED**: A backup has been successfully generated.
+  - **SECRET_SELECTING**: The user needs to select a recovery policy document 
with
+               the secret that is to be recovered.
   - **CHALLENGE_SELECTING**: The user needs to select an authorization 
challenge to
                proceed with recovery.
   - **CHALLENGE_PAYING**: The user needs to pay to proceed with the 
authorization challenge.
@@ -1091,7 +1093,7 @@ Backup Reducer
 .. figure:: anastasis_reducer_backup.png
     :name: fig-anastasis_reducer_backup
     :alt: fig-anastasis_reducer_backup
-    :scale: 35 %
+    :scale: 75 %
     :align: center
 
     Backup states and their transitions.
@@ -1106,7 +1108,7 @@ Recovery Reducer
 .. figure:: anastasis_reducer_recovery.png
     :name: fig-anastasis_reducer_recovery
     :alt: fig-anastasis_reducer_recovery
-    :scale: 35 %
+    :scale: 75 %
     :align: center
 
     Recovery states and their transitions.
@@ -1422,8 +1424,6 @@ information is provided if the provider was successfully 
contacted:
   - **annual_fee**: Fee the provider charges to store the recovery
     policy for one year.
   - **truth_upload_fee**: Fee the provider charges to store a key share.
-  - **truth_lifetime**: Taler-style relative time that specifies how
-    long the provider will store truth data (key shares) after an upload.
   - **liability_limit**: Amount the provider can be held liable for in
     case a key share or recovery document cannot be recovered due to
     provider failures.
@@ -1828,6 +1828,38 @@ authentication, the reducer will transition into an 
``ERROR`` state instead of
 adding the new policy.
 
 
+**update_policy**:
+
+Using this transition, the user can modify an existing recovery policy
+in the state.
+The argument format is the same that is used in **add_policy**,
+except there is an additional key ``policy_index`` which
+identifies the policy to modify.
+An example for a possible argument would thus be:
+
+.. code-block:: javascript
+
+    {
+      "policy_index" : 1,
+      "policy": [
+        {
+          "authentication_method": 1,
+          "provider": "http://localhost:8088/";
+        },
+        {
+          "authentication_method": 3,
+          "provider": "http://localhost:8089/";
+        }
+      ]
+    }
+
+If the new policy is invalid, for example because it adds an unknown
+authentication method, or the selected provider does not support the type of
+authentication, the reducer will transition into an ``ERROR`` state instead of
+modifying the policy.
+
+
+
 **delete_policy:**
 
 This transition allows the deletion of a recovery policy. The argument
@@ -1890,6 +1922,67 @@ If the index given is invalid, the reducer will 
transition into an ``ERROR`` sta
 instead of deleting a policy.
 
 
+**delete_challenge:**
+
+This transition allows the deletion of an individual
+challenge from a recovery policy. The argument
+simply specifies the index of the policy and challenge
+to delete, for example:
+
+.. code-block:: json
+
+    {
+      "policy_index": 1,
+      "challenge_index" : 1
+    }
+
+Given as input the state from the example above, the expected new state would
+be:
+
+.. code-block:: json
+
+    {
+      "backup_state": "POLICIES_REVIEWING",
+      "policies": [
+        {
+          "methods": [
+            {
+              "authentication_method": 0,
+              "provider": "http://localhost:8089/";
+            },
+            {
+              "authentication_method": 1,
+              "provider": "http://localhost:8088/";
+            }
+          ]
+        },
+        {
+          "methods": [
+            {
+              "authentication_method": 0,
+              "provider": "http://localhost:8089/";
+            }
+          ]
+        },
+        {
+          "methods": [
+            {
+              "authentication_method": 1,
+              "provider": "http://localhost:8089/";
+            },
+            {
+              "authentication_method": 2,
+              "provider": "http://localhost:8088/";
+            }
+          ]
+        }
+      ]
+    }
+
+If the index given is invalid, the reducer will transition into an ``ERROR`` 
state
+instead of deleting a challenge.
+
+
 **next** (from ``POLICIES_REVIEWING``):
 
 Using this transition, the user confirms that the policies in the current
@@ -1918,8 +2011,8 @@ into an ``ERROR`` state instead of allowing the user to 
continue.
 
 This transition provides the reducer with the actual core ``secret`` of the 
user
 that Anastasis is supposed to backup (and possibly recover). The argument is
-simply the Crockford-Base32 encoded ``value`` together with its ``mime`` type,
-for example:
+simply the Crockford-Base32 encoded ``value`` together with its ``mime`` type, 
or a ``text`` field with a human-readable secret text.
+For example:
 
 .. code-block:: javascript
 
@@ -1928,12 +2021,11 @@ for example:
          "value": "EDJP6WK5EG50",
          "mime" : "text/plain"
       },
-      "name": "$NAME",
       "expiration" : { "t_ms" : 1245362362 }
     }
 
 If the application is unaware of the format, it set the ``mime`` field to 
``null``.
-The ``name`` and ``expiration`` fields are optional.
+The ``expiration`` field is optional.
 
 The reducer remains in the ``SECRET_EDITING`` state, but now the secret and
 updated expiration time are part of the state and the cost calculations will
@@ -1943,13 +2035,51 @@ be updated.
 
     {
       "backup_state": "SECRET_EDITING",
-      "core_secret" : { "$anything":"$anything" },
-      "secret_name" : "$NAME",
+      "core_secret" : {
+         "value": "EDJP6WK5EG50",
+         "mime" : "text/plain"
+      },
       "expiration" : { "t_ms" : 1245362362 },
       "upload_fees" : [ "KUDOS:42" ]
     }
 
 
+**clear_secret:**
+
+This transition removes the core secret from the state.  It is simply a
+convenience function to undo ``enter_secret`` without providing a new value
+immediately. The transition takes no arguments.  The resuting state will no
+longer have the ``core_secret`` field, and be otherwise unchanged. Calling
+**clear_secret** on a state without a ``core_secret`` will result in an error.
+
+
+**enter_secret_name:**
+
+This transition provides the reducer with a name for the core ``secret`` of 
the user. This name will be given to the user as a hint when seleting a 
recovery policy document during recovery, prior to satisfying any of the 
challenges. The argument simply contains the name for the secret.
+Applications that have build-in support for Anastasis MUST prefix the
+secret name with an underscore and an application-specific identifier
+registered in GANA so that they can use recognize their own backups.
+An example argument would be:
+
+.. code-block:: javascript
+
+    {
+      "name": "_TALERWALLET_MyPinePhone",
+    }
+
+Here, ``MyPinePhone`` might be chosen by the user to identify the
+device that was being backed up.
+
+The reducer remains in the ``SECRET_EDITING`` state, but now the
+secret name is updated:
+
+.. code-block:: json
+
+    {
+      "secret_name" : "_TALERWALLET_MyPinePhone"
+    }
+
+
 **update_expiration:**
 
 This transition asks the reducer to change the desired expiration time

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