From 3e364b9c8daab32566c945d369cba5de9f74e801 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 30 Mar 2021 20:28:30 +0200 Subject: document more of reducer --- anastasis.rst | 143 ++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 120 insertions(+), 23 deletions(-) (limited to 'anastasis.rst') diff --git a/anastasis.rst b/anastasis.rst index 8eab4612..562c2964 100644 --- a/anastasis.rst +++ b/anastasis.rst @@ -1536,12 +1536,19 @@ response: ] } -If the index is invalid, the reducer will transition into an ERROR state. +If the index is invalid, the reducer will instead +transition into an ERROR state. **next** (from "AUTHENTICATIONS_EDITING"): -Optional arguments to try uploading recovery document only to specific providers (example): +This transition confirms that the user has finished adding (or removing) +authentication methods, and that the system should now automatically compute +a set of reasonable recovery policies. + +This transition does not take any mandatory arguments. Optional arguments can +be provided to upload the recovery document only to a specific subset of the +providers: .. code-block:: json @@ -1554,21 +1561,72 @@ Optional arguments to try uploading recovery document only to specific providers ..note:: - This is currently not supported (#6760). + This is currently not supported (#6760), the current implementation of the + reducer ignores this optional argument. -Expected new state (backup process): +The resulting state provides the suggested recovery policies in a way suitable +for presentation to the user: .. code-block:: javascript { "backup_state": "POLICIES_REVIEWING", - // FIXME: give example of calculated policies here! + "policies": [ + { + "recovery_cost": "TESTKUDOS:0", + "methods": [ + { + "authentication_method": 0, + "provider": "http://localhost:8088/" + }, + { + "authentication_method": 1, + "provider": "http://localhost:8089/" + }, + { + "authentication_method": 2, + "provider": "http://localhost:8087/" + } + ] + }, + { + "recovery_cost": "TESTKUDOS:0", + "methods": [ + { + "authentication_method": 0, + "provider": "http://localhost:8088/" + }, + { + "authentication_method": 1, + "provider": "http://localhost:8089/" + }, + { + "authentication_method": 3, + "provider": "http://localhost:8089/" + } + ] + } + ] } +For each recovery policy, the state includes the ``recovery_cost`` (which is +the sum of the costs to solve all challenges associated with the policy with +the respective providers), as well as the specific details of which +authentication ``methods`` must be solved to recovery the secret using this +policy. The ``methods`` array specifies the index of the +``authentication_method`` in the ``authentication_methods`` array, as well as +the provider that was selected to supervise this authentication. + +If no authentication method was provided, the reducer will transition into an +ERROR state instead of suggesting policies. + **add_policy**: -Arguments (example): +Using this transition, the user can add an additional recovery policy to the +state. The argument format is the same that is used in the existing state, +except that the ``recovery_cost`` should be omitted (as the reducer will +calculate it). An example for a possible argument would thus be: .. code-block:: javascript @@ -1585,7 +1643,10 @@ Arguments (example): ] } -Expected new state: +Note that the specified providers must already be in the +``authentication_providers`` of the state. You cannot add new providers at +this stage. The reducer will simply attempt to append the suggested policy to +the "policies" array, returning an updated state: .. code-block:: json @@ -1647,10 +1708,16 @@ Expected new state: ] } +If the new policy is invalid, for example because it add 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 +adding the new policy. + **delete_policy:** -Arguments (example): +This transition allows the deletion of a recovery policy. The argument +simply specifies the index of the policy to delete, for example: .. code-block:: json @@ -1658,7 +1725,8 @@ Arguments (example): "policy_index": 3 } -Expected new state: +Given as input the state from the example above, the expected new state would +be: .. code-block:: json @@ -1707,12 +1775,16 @@ Expected new state: ] } +If the index given is invalid, the reducer will transition into an ERROR state +instead of deleting a policy. + **next** (from "POLICIES_REVIEWING"): -No arguments. +Using this transition, the user confirms that the policies in the current +state are acceptable. The transition does not take any arguments. -Expected new state (backup process): +The reducer will simply transition to the ``SECRET_EDITING`` state: .. code-block:: json @@ -1721,29 +1793,56 @@ Expected new state (backup process): } +If the array of ``policies`` is currently empty, the reducer will transition +into an ERROR state instead of allowing the user to continue. + + **enter_secret:** -Arguments (example): +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 ``secret``, for example: .. code-block:: javascript { - "secret": string + "secret": "EDJP6WK5EG50" } -- secret: must be a Crockford-Base32 encoded string of some data +Applications SHOULD prefix the encoded ``secret`` with some data that allows +applications to recognize the application and the version of the secret. The +suggested notation is ``$APPLICATION/$VERSION:$SECRET``, for example +``taler-wallet/42:KEYMATERIAL``. In case the secret is provided from a file +and the application is oblivious to the details, the same syntax can be used +to prefix the secret with a MIME type, for example ``image/png:IMAGE``. If +the application is unaware of the format, it should use ``*/*:DATA``. +..note:: -Expected new states include: + The prefixing of the secret with the mime-type or application version + is currently not implemented (#6825). + + +After adding a secret, the reducer may transition into different states +depending on whether payment(s) are necessary. If payments are needed, the +``secret`` will be stored in the state under ``core_secret``. Applications +should be careful when persisting the resulting state, as the ``core_secret`` +is not protected in the ``PAYING`` states. The ``PAYING`` states only differ +in terms of what the payments are for (key shares or the recovery document), +in all cases the state simply includes an array of Taler URIs that refer to +payments that need to be made with the Taler wallet. + +If all payments are complete, the reducer will transition into the +``BACKUP_FINISHED`` state and (if applicable) delete the ``core_secret`` as an +additional safety measure. + +Example results are thus: .. code-block:: json { "backup_state": "TRUTHS_PAYING", - "core_secret" : { - "secret": "DATA", - "type": "passpharse" - }, + "core_secret" : "DATA", "payments": [ "taler://pay/...", "taler://pay/..." @@ -1754,10 +1853,7 @@ Expected new states include: { "backup_state": "POLICIES_PAYING", - "core_secret" : { - "secret": "DATA", - "type": "passpharse" - }, + "core_secret" : "DATA", "payments": [ "taler://pay/...", "taler://pay/..." @@ -1773,6 +1869,7 @@ Expected new states include: **pay:** +FIXME: this is wrong! long polling! Optional arguments to try uploading just specific truths (example): .. code-block:: json -- cgit v1.2.3