diff options
Diffstat (limited to 'doc/sphinx/reducer.rst')
| -rw-r--r-- | doc/sphinx/reducer.rst | 135 |
1 files changed, 102 insertions, 33 deletions
diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst index 9728d7d..50fec42 100644 --- a/doc/sphinx/reducer.rst +++ b/doc/sphinx/reducer.rst @@ -1,6 +1,6 @@ .. This file is part of Anastasis - Copyright (C) 2019-2021 Anastasis SARL + Copyright (C) 2019-2022 Anastasis SARL Anastasis is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -499,7 +499,8 @@ If contacting the provider failed, the information returned is: **add_provider**: -This operation can be performed in state ``USER_ATTRIBUTES_COLLECTING``. It +This operation can be performed in state ``USER_ATTRIBUTES_COLLECTING``. +It adds one or more Anastasis providers to the list of providers the reducer should henceforth consider. Note that removing providers is not possible at this time. @@ -513,8 +514,8 @@ use. For example: { "http://localhost:8088/" : { "disabled" : false }, - "http://localhost:8089/" : { "disabled" : false } - "http://localhost:8090/" : { "disabled" : true }, + "http://localhost:8089/" : { "disabled" : false }, + "http://localhost:8090/" : { "disabled" : true } } Note that existing providers will remain in the state they were in. The following is an @@ -1055,7 +1056,7 @@ The reducer will simply transition to the ``SECRET_EDITING`` state: { "backup_state": "SECRET_EDITING", - "upload_fees" : [ "KUDOS:42" ], + "upload_fees" : [ { "fee": "KUDOS:42" } ], "expiration" : { "t_ms" : 1245362362 } } @@ -1101,7 +1102,7 @@ be updated. "mime" : "text/plain" }, "expiration" : { "t_ms" : 1245362362 }, - "upload_fees" : [ "KUDOS:42" ] + "upload_fees" : [ { "fee": "KUDOS:42" } ] } @@ -1293,11 +1294,73 @@ the backup process. Example arguments would thus be: } } -However, in contrast to the backup process, the reducer will attempt to -retrieve the latest recovery document from all known providers for the -selected currency given the above inputs. If a recovery document was found -by any provider, the reducer will attempt to load it and transition to -a state where the user can choose which challenges to satisfy: +Afterwards, the reducer transitions into the ``SECRET_SELECTING`` state: + +.. code-block:: json + + { + "recovery_state": "SECRET_SELECTING", + "identity_attributes": { + "full_name": "Max Musterman", + "social_security_number": "123456789", + "birthdate": "2000-01-01", + "birthplace": "Earth" + } + } + +Typically, the special policy discovery process (outside of the state +machine) is expected to be run in this state. The discovery process +will use the state (and in particular the identity attributes and the +list of active providers) to discover a set of possible recovery +documents with their respective provider URLs, policy version and +identity attribute mask. An identity attribute mask is a bitmask that +describes which of the optional attributes from the identity +attributes should be omitted to recover this backup. Once the user +has selected a backup providing this triplet, it is possible to +proceed using ``next``. + +Especially if the discovered policies are inadequate, it is again +possible to add providers using ``add_provider``. + + +**add_provider**: + +This operation can be performed in state ``SECRET_SELECTING``. It +adds one additional Anastasis provider to the list of providers that +the discovery process should henceforth consider. Note that removing +providers is not possible at this time. + +Here, the client must provide an object with the base URL of the +providers to add, for example: + +.. code-block:: json + + { + "provider_url" : "http://localhost:8088/" + } + + +**select_version**: + +Using the ``select_version`` transition in the ``SECRET_SELECTING`` state, +it is possible to trigger the download and decryption of a recovery +policy document. Here, the arguments specify which provider, version +and mask should be used to download the document: + +.. code-block:: json + + { + "providers" : [ { + "url": "https://localhost:8088/", + "version": 0 + } ], + "attribute_mask": 0 + } + +The reducer will attempt to retrieve the specified recovery document +from that provider. If a recovery document was found, the reducer +will attempt to load it and transition to a state where the user can +choose which challenges to satisfy: .. code-block:: json @@ -1307,13 +1370,13 @@ a state where the user can choose which challenges to satisfy: "challenges": [ { "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G", - "cost": "TESTKUDOS:0", + "uuid-display": "MW2R3RC", "type": "question", "instructions": "q1" }, { "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", - "cost": "TESTKUDOS:0", + "uuid-display": "TXYKGE", "type": "email", "instructions": "e-mail address m?il@f*.bar" }, @@ -1347,12 +1410,11 @@ 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 + UUIDs in the policies array refer to. + - **uuid-display**: Shortened idenfier which is included in messages + send to the user. Allows 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 @@ -1383,26 +1445,33 @@ 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:** +**sync_providers** + +The downloaded policy may include secrets from providers for which +we do not (yet) have the cost structure or even the salt. So here +an application can use the ``sync_providers`` request to download +``/config`` from providers that are in the challenge list but not +yet known with their salt and other attributes in the provider list. -Even if a recovery document was found, it is possible that the user -intended to recover a different version, or recover a backup where -the recovery document is stored at a different provider. Thus, the -reducer allows the user to explicitly switch to a different provider -or recovery document version using the ``change_version`` transition, -which takes a provider URL and policy version as arguments: +The transition fails if all providers relevant for the selected +policy are already downloaded. Applications may either internally +check the state for this, or call ``sync_providers`` until it fails +with this error: .. code-block:: json - { - "provider_url": "https://localhost:8080/", - "version": 2 - } + { + "detail": "already in sync", + "code": 8400, + "hint": "The given action is invalid for the current state of the reducer." + } -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. +As providers may fail to respond, this action may need to be called +repeatedly. The action will block until progress is made on any provider. +As some providers may never respond, the application should disable +challenge buttons for challenges where providers are down. However, +users should be able to solve challenges where the provider is up while +the reducer is polling for ``/config`` in the background. **select_challenge:** @@ -1691,7 +1760,7 @@ that applications must all handle. States other than ``solved`` are: **poll:** -With a ``poll`` transition, the application indicates that it wants to wait longer for one or more of the challenges that are in state ``authentication-timeout`` to possibly complete. While technically optional, the ``timeout`` argument should really be provided to enable long-polling, for example: +With a ``poll`` transition, the application indicates that it wants to wait longer for one or more of the challenges that are awaiting some external authentication (state ``external-instructions``) or experienced some kind of timeout (state ``authentication-timeout``) to possibly complete. While technically optional, the ``timeout`` argument should really be provided to enable long-polling, for example: .. code-block:: json |