diff options
Diffstat (limited to 'anastasis.rst')
-rw-r--r-- | anastasis.rst | 150 |
1 files changed, 140 insertions, 10 deletions
diff --git a/anastasis.rst b/anastasis.rst index 1c4e39ef..0cca44b6 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 |