summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-07-18 06:34:26 +0200
committerChristian Grothoff <christian@grothoff.org>2021-07-18 06:34:26 +0200
commitf4b5e48d5667e9eb4126aa8e060db0f041ef2318 (patch)
tree5575f2f848c6b83acb8a53caf355a81dbcf6ef91
parent442de7161b84b9f28f51a39584ffbfd682a259ed (diff)
downloaddocs-f4b5e48d5667e9eb4126aa8e060db0f041ef2318.tar.gz
docs-f4b5e48d5667e9eb4126aa8e060db0f041ef2318.tar.bz2
docs-f4b5e48d5667e9eb4126aa8e060db0f041ef2318.zip
update anastasis state machine spec
-rw-r--r--anastasis.rst150
1 files 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