diff options
Diffstat (limited to 'doc/sphinx/reducer.rst')
| -rw-r--r-- | doc/sphinx/reducer.rst | 1656 |
1 files changed, 1656 insertions, 0 deletions
diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst new file mode 100644 index 0000000..e5f1699 --- /dev/null +++ b/doc/sphinx/reducer.rst @@ -0,0 +1,1656 @@ +.. + This file is part of Anastasis + Copyright (C) 2019-2021 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 + Foundation; either version 2.1, or (at your option) any later version. + + Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Christian Grothoff + @author Dominik Meister + @author Dennis Neufeld + +----------- +Reducer API +----------- + +This section describes the Anastasis Reducer API which is used by client applications +to store or load the different states the client application can have. +The reducer takes a state_ in JSON syntax and returns the new state in JSON syntax. + +For example a **state** may take the following structure: + +.. code-block:: json + + { + "backup_state": "CONTINENT_SELECTING", + "continents": [ + "Europe", + "North_America" + ] + } + +The new state depends on the previous one and on the transition action_ with its +arguments given to the reducer. A **transition argument** also is a statement in JSON syntax: + +.. code-block:: json + + { + "continent": "Europe" + } + +The new state returned by the reducer with the state and transition argument defined +above would look like following for the transition action_ ``select_continent``: + +.. code-block:: json + + { + "backup_state": "COUNTRY_SELECTING", + "continents": [ + "Europe", + "North_America" + ], + "selected_continent": "Europe", + "countries": [ + { + "code": "ch", + "name": "Switzerland", + "continent": "Europe", + "name_i18n": { + "de_DE": "Schweiz", + "de_CH": "Schwiiz", + "fr": "Suisse", + "en": "Swiss" + }, + "currency": "CHF" + }, + { + "code": "de", + "name": "Germany", + "continent": "Europe", + "continent_i18n": { + "de": "Europa" + }, + "name_i18n": { + "de_DE": "Deutschland", + "de_CH": "Deutschland", + "fr": "Allemagne", + "en": "Germany" + }, + "currency": "EUR" + } + ] + } + +States +^^^^^^ + +Overall, the reducer knows the following states: + + - **ERROR**: The transition led to an error. No further transitions are possible from + this state, but the client may want to continue from a previous state. + - **CONTINENT_SELECTING**: The user should specify the continent where they are living, + so that we can show a list of countries to choose from. + - **COUNTRY_SELECTING**: The user should specify the country where they are living, + so that we can determine appropriate attributes, currencies and Anastasis + providers. + - **USER_ATTRIBUTES_COLLECTING**: The user should provide the country-specific personal + attributes. + - **AUTHENTICATIONS_EDITING**: The user should add authentication methods to be used + during recovery. + - **POLICIES_REVIEWING**: The user should review the recovery policies. + - **SECRET_EDITING**: The user should edit the secret to be backed up. + - **TRUTHS_PAYING**: The user needs to pay for one or more uploads of data associated + 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. + - **CHALLENGE_SOLVING**: The user needs to solve the authorization challenge. + - **RECOVERY_FINISHED**: The secret of the user has been recovered. + +State names: + + - In SELECTING-states, the user has to choose one value out of a predefined set of values (for example a continent out of a set of continents). + - In COLLECTING-states, the user has to give certain values. + - In EDITING-states, the user is free to choose which values he wants to give. + - In REVEIWING-states, the user may make a few choices, but primarily is expected to affirm something. + - in PAYING-states, the user must make a payment. + - in FINISHED-states, the operation has definitively concluded. + + +Backup Reducer +^^^^^^^^^^^^^^ +.. _state: +.. _action: +.. figure:: anastasis_reducer_backup.png + :name: fig-anastasis_reducer_backup + :alt: fig-anastasis_reducer_backup + :scale: 75 % + :align: center + + Backup states and their transitions. + + +The illustration above shows the different states the reducer can have during a backup +process. + + +Recovery Reducer +^^^^^^^^^^^^^^^^ +.. figure:: anastasis_reducer_recovery.png + :name: fig-anastasis_reducer_recovery + :alt: fig-anastasis_reducer_recovery + :scale: 75 % + :align: center + + Recovery states and their transitions. + + +The illustration above shows the different states the reducer can have during a recovery +process. + + +Reducer transitions +^^^^^^^^^^^^^^^^^^^ +In the following, the individual transitions will be specified in more detail. +Note that we only show fields added by the reducer, typically the previous +state is preserved to enable "back" transitions to function smoothly. + + +Initial state +------------- + +The initial states for backup and recovery processes are: + +**Initial backup state:** + +.. code-block:: json + + { + "backup_state": "CONTINENT_SELECTING", + "continents": [ + "Europe", + "North America" + ] + } + + +**Initial recovery state:** + +.. code-block:: json + + { + "recovery_state": "CONTINENT_SELECTING", + "continents": [ + "Europe", + "North America" + ] + } + +Here, "continents" is an array of English strings with the names of the +continents which contain countries for which Anastasis could function (based +on having providers that are known to operate and rules being provided for +user attributes from those countries). + +For internationalization, another field ``continents_i18n`` may be present. +This field would be a map of language names to arrays of translated +continent names: + +.. code-block:: json + + { + "recovery_state": "CONTINENT_SELECTING", + "continents": [ + "Europe", + "North America" + ] + "continents_i18n": + { + "de_DE" : [ + "Europa", + "Nordamerika" + ], + "de_CH" : [ + "Europa", + "Nordamerika" + ] + } + } + +Translations must be given in the same order as the main English array. + + +Common transitions +------------------ + +**select_continent:** + +Here the user specifies the continent they live on. Arguments (example): + +.. code-block:: json + + { + "continent": "Europe" + } + +The continent must be given using the English name from the ``continents`` array. +Using a translated continent name is invalid and may result in failure. + +The reducer returns an updated state with a list of countries to choose from, +for example: + +.. code-block:: json + + { + "backup_state": "COUNTRY_SELECTING", + "selected_continent": "Europe", + "countries": [ + { + "code": "ch", + "name": "Switzerland", + "continent": "Europe", + "name_i18n": { + "de_DE": "Schweiz", + "de_CH": "Schwiiz", + "fr": "Suisse", + "en": "Swiss" + }, + "currency": "CHF" + }, + { + "code": "de", + "name": "Germany", + "continent": "Europe", + "continent_i18n": { + "de": "Europa" + }, + "name_i18n": { + "de_DE": "Deutschland", + "de_CH": "Deutschland", + "fr": "Allemagne", + "en": "Germany" + }, + "currency": "EUR" + } + ] + } + +Here ``countries`` is an array of countries on the ``selected_continent``. For +each country, the ``code`` is the ISO 3166-1 alpha-2 country code. The +``continent`` is only present because some countries span continents, the +information is redundant and will always match ``selected_continent``. The +``name`` is the name of the country in English, internationalizations of the +name may be provided in ``name_i18n``. The ``currency`` is **an** official +currency of the country, if a country has multiple currencies, it may appear +multiple times in the list. In this case, the user should select the entry +with the currency they intend to pay with. It is also possible for users +to select a currency that does not match their country, but user interfaces +should by default try to use currencies that match the user's residence. + + +**select_country:** + +Selects the country (via the country code) and specifies the currency. +The latter is needed as some countries have more than one currency, +and some use-cases may also involve users insisting on paying with +foreign currency. + +Arguments (example): + +.. code-block:: json + + { + "country_code": "de", + "currency": "EUR" + } + +The ``country_code`` must be an ISO 3166-1 alpha-2 country code from +the array of ``countries`` of the reducer's state. The ``currency`` +field must be a valid currency accepted by the Taler payment system. + +The reducer returns a new state with the list of attributes the +user is expected to provide, as well as possible authentication +providers that accept payments in the selected currency: + +.. code-block:: json + + { + "backup_state": "USER_ATTRIBUTES_COLLECTING", + "selected_country": "de", + "currency": "EUR", + "required_attributes": [ + { + "type": "string", + "name": "full_name", + "label": "Full name", + "label_i18n": { + "de_DE": "Vollstaendiger Name", + "de_CH": "Vollstaendiger. Name", + "fr": "Nom complet", + "en": "Full name" + }, + "widget": "anastasis_gtk_ia_full_name", + "uuid" : "9e8f463f-575f-42cb-85f3-759559997331" + }, + { + "type": "date", + "name": "birthdate", + "label": "Birthdate", + "label_i18n": { + "de_DE": "Geburtsdatum", + "de_CH": "Geburtsdatum", + "fr": "Date de naissance", + "en": "Birthdate" + }, + "uuid" : "83d655c7-bdb6-484d-904e-80c1058c8854" + "widget": "anastasis_gtk_ia_birthdate" + }, + { + "type": "string", + "name": "tax_number", + "label": "Taxpayer identification number", + "label_i18n":{ + "de_DE": "Steuerliche Identifikationsnummer", + "de_CH": "Steuerliche Identifikationsnummer", + "en": "German taxpayer identification number" + }, + "widget": "anastasis_gtk_ia_tax_de", + "uuid": "dae48f85-e3ff-47a4-a4a3-ed981ed8c3c6", + "validation-regex": "^[0-9]{11}$", + "validation-logic": "DE_TIN_check" + }, + { + "type": "string", + "name": "social_security_number", + "label": "Social security number", + "label_i18n": { + "de_DE": "Sozialversicherungsnummer", + "de_CH": "Sozialversicherungsnummer", + "fr": "Numéro de sécurité sociale", + "en": "Social security number" + }, + "widget": "anastasis_gtk_ia_ssn", + "validation-regex": "^[0-9]{8}[[:upper:]][0-9]{3}$", + "validation-logic": "DE_SVN_check" + "optional" : true + } + ], + "authentication_providers": { + "http://localhost:8089/": { + "http_status": 200, + "methods": [ + { "type" : "question", + "usage_fee" : "EUR:0.0" }, + { "type" : "sms", + "usage_fee" : "EUR:0.5" } + ], + "annual_fee": "EUR:4.99", + "truth_upload_fee": "EUR:4.99", + "liability_limit": "EUR:1", + "currency": "EUR", + "truth_lifetime": { "d_ms" : 50000000 }, + "storage_limit_in_megabytes": 1, + "provider_name": "Anastasis 4", + "salt": "CXAPCKSH9D3MYJTS9536RHJHCW" + }, + "http://localhost:8088/": { + "http_status": 200, + "methods": [ + { "type" : "question", + "usage_fee" : "EUR:0.01" }, + { "type" : "sms", + "usage_fee" : "EUR:0.55" } + ], + "annual_fee": "EUR:0.99", + "truth_upload_fee": "EUR:3.99", + "liability_limit": "EUR:1", + "currency": "EUR", + "truth_lifetime": { "d_ms" : 50000000 }, + "storage_limit_in_megabytes": 1, + "provider_name": "Anastasis 4", + "salt": "CXAPCKSH9D3MYJTS9536RHJHCW" + } + } + } + +The array of ``required_attributes`` contains attributes about the user +that must be provided includes: + + - **type**: The type of the attribute, for now only ``string`` and ``date`` are + supported. + - **name**: The name of the attribute, this is the key under which the + attribute value must be provided later. The name must be unique per response. + - **label**: A human-readable description of the attribute in English. + Translated descriptions may be provided under **label_i18n**. + - **uuid**: A UUID that uniquely identifies identical attributes across + different countries. Useful to preserve values should the user enter + some attributes, and then switch to another country. Note that + attributes must not be preserved if they merely have the same **name**, + only the **uuid** will be identical if the semantics is identical. + - **widget**: An optional name of a widget that is known to nicely render + the attribute entry in user interfaces where named widgets are + supported. + - **validation-regex**: An optional extended POSIX regular expression + that is to be used to validate (string) inputs to ensure they are + well-formed. + - **validation-logic**: Optional name of a function that should be called + to validate the input. If the function is not known to the particular + client, the respective validation can be skipped (at the expense of + typos by users not being detected, possibly rendering secrets + irrecoverable). + - **optional**: Optional boolean field that, if ``true``, indicates that + this attribute is not actually required but optional and users MAY leave + it blank in case they do not have the requested information. Used for + common fields that apply to some large part of the population but are + not sufficiently universal to be actually required. + +The authentication providers are listed under a key that is the +base URL of the service. For each provider, the following +information is provided if the provider was successfully contacted: + + - **http_status**: HTTP status code, always ``200`` on success. + - **methods**: Array of authentication methods supported by this + provider. Includes the **type** of the authentication method + and the **usage_fee** (how much the user must pay for authorization + using this method during recovery). + - **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. + - **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. + - **currency**: Currency in which the provider wants to be paid, + will match all of the fees. + - **storage_limit_in_megabytes**: Maximum size of an upload (for + both recovery document and truth data) in megabytes. + - **provider_name**: Human-readable name of the provider's business. + - **salt**: Salt value used by the provider, used to derive the + user's identity at this provider. Should be unique per provider, + and must never change for a given provider. The salt is + base32 encoded. + +If contacting the provider failed, the information returned is: + + - **http_status**: HTTP status code (if available, possibly 0 if + we did not even obtain an HTTP response). + - **error_code**: Taler error code, never 0. + + +**add_provider**: + +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. + +Here, the client must provide an array with the base URLs of the +providers to add, for example: + +.. code-block:: json + + { + "urls": [ + "http://localhost:8888/", + "http://localhost:8089/" + ] + } + +Note that existing providers will remain in the state. The following is an +example for an expected new state where the service on port 8089 is +unreachable, the service on port 8088 was previously known, and service on +port 8888 was now added: + +.. code-block:: json + + { + "backup_state": "USER_ATTRIBUTES_COLLECTING", + "authentication_providers": { + "http://localhost:8089/": { + "error_code": 11, + "http_status": 0 + }, + "http://localhost:8088/": { + "http_status": 200, + "methods": [ + { "type" : "question", + "usage_fee" : "EUR:0.01" }, + { "type" : "sms", + "usage_fee" : "EUR:0.55" } + ], + "annual_fee": "EUR:0.99", + "truth_upload_fee": "EUR:3.99", + "liability_limit": "EUR:1", + "currency": "EUR", + "truth_lifetime": { "d_ms" : 50000000 }, + "storage_limit_in_megabytes": 1, + "provider_name": "Anastasis 4", + "salt": "CXAPCKSH9D3MYJTS9536RHJHCW" + } + "http://localhost:8888/": { + "methods": [ + { "type" : "question", + "usage_fee" : "EUR:0.01" }, + { "type" : "sms", + "usage_fee" : "EUR:0.55" } + ], + "annual_fee": "EUR:0.99", + "truth_upload_fee": "EUR:3.99", + "liability_limit": "EUR:1", + "currency": "EUR", + "truth_lifetime": { "d_ms" : 50000000 }, + "storage_limit_in_megabytes": 1, + "provider_name": "Anastasis 42", + "salt": "BXAPCKSH9D3MYJTS9536RHJHCX" + } + } + } + + + +Backup transitions +------------------ + +**enter_user_attributes:** + +This transition provides the user's personal attributes. The specific set of +attributes required depends on the country of residence of the user. Some +attributes may be optional, in which case they should be omitted entirely +(that is, not simply be set to ``null`` or an empty string). Example +arguments would be: + +.. code-block:: json + + { + "identity_attributes": { + "full_name": "Max Musterman", + "social_security_number": "123456789", + "birthdate": "2000-01-01", + "birthplace": "Earth" + } + } + +Note that at this stage, the state machines between backup and +recovery diverge and the ``recovery_state`` will begin to look +very different from the ``backup_state``. + +For backups, if all required attributes are present, the reducer will +transition to an ``AUTHENTICATIONS_EDITING`` state with the attributes added +to it: + +.. code-block:: json + + { + "backup_state": "AUTHENTICATIONS_EDITING", + "identity_attributes": { + "full_name": "Max Musterman", + "social_security_number": "123456789", + "birthdate": "2000-01-01", + "birthplace": "Earth" + } + } + +If required attributes are missing, do not match the required regular +expression, or fail the custom validation logic, the reducer SHOULD transition +to an error state indicating what was wrong about the input. A reducer that +does not support some specific validation logic MAY accept the invalid input +and proceed anyway. The error state will include a Taler error code that +is specific to the failure, and optional details. Example: + +.. code-block:: json + + { + "backup_state": "ERROR", + "code": 8404, + "hint": "An input did not match the regular expression.", + "detail": "social_security_number" + } + +Clients may safely repeat this transition to validate the user's inputs +until they satisfy all of the constraints. This way, the user interface +does not have to perform the input validation directly. + + +**add_authentication**: + +This transition adds an authentication method. The method must be supported +by one or more providers that are included in the current state. Adding an +authentication method requires specifying the ``type`` and ``instructions`` to +be given to the user. The ``challenge`` is encrypted and stored at the +Anastasis provider. The specific semantics of the value depend on the +``type``. Typical challenges values are a phone number (to send an SMS to), +an e-mail address (to send a PIN code to) or the answer to a security +question. Note that these challenge values will still be encrypted (and +possibly hashed) before being given to the Anastasis providers. + +Note that the ``challenge`` must be given in Crockford Base32 encoding, as it +MAY include binary data (such as a photograph of the user). In the latter +case, the optional ``mime_type`` field must be provided to give the MIME type +of the value encoded in ``challenge``. + +.. code-block:: json + + { + "authentication_method": + { + "type": "question", + "mime_type" : "text/plain", + "instructions" : "What is your favorite GNU package?", + "challenge" : "E1QPPS8A", + } + } + +If the information provided is valid, the reducer will add the new +authentication method to the array of authentication methods: + +.. code-block:: json + + { + "backup_state": "AUTHENTICATIONS_EDITING", + "authentication_methods": [ + { + "type": "question", + "mime_type" : "text/plain", + "instructions" : "What is your favorite GNU package?", + "challenge" : "E1QPPS8A", + }, + { + "type": "email", + "instructions" : "E-mail to user@*le.com", + "challenge": "ENSPAWJ0CNW62VBGDHJJWRVFDM50" + } + ] + } + + +**delete_authentication**: + +This transition can be used to remove an authentication method from the +array of authentication methods. It simply requires the index of the +authentication method to remove. Note that the array is 0-indexed: + +.. code-block:: json + + { + "authentication_method": 1 + } + +Assuming we begin with the state from the example above, this would +remove the ``email`` authentication method, resulting in the following +response: + +.. code-block:: json + + { + "backup_state": "AUTHENTICATIONS_EDITING", + "authentication_methods": [ + { + "type": "question", + "mime_type" : "text/plain", + "instructions" : "What is your favorite GNU package?", + "challenge" : "gdb", + } + ] + } + +If the index is invalid, the reducer will instead +transition into an ``ERROR`` state. + + +**next** (from ``AUTHENTICATIONS_EDITING``): + +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 + + { + "providers": [ + "http://localhost:8088/", + "http://localhost:8089/" + ] + } + +The resulting state provides the suggested recovery policies in a way suitable +for presentation to the user: + +.. code-block:: javascript + + { + "backup_state": "POLICIES_REVIEWING", + "policy_providers" : [ + { "provider_url" : "http://localhost:8088/" }, + { "provider_url" : "http://localhost:8089/" } + ], + "policies": [ + { + "methods": [ + { + "authentication_method": 0, + "provider": "http://localhost:8088/" + }, + { + "authentication_method": 1, + "provider": "http://localhost:8089/" + }, + { + "authentication_method": 2, + "provider": "http://localhost:8087/" + } + ] + }, + { + "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 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**: + +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. +An example for a possible argument would thus be: + +.. code-block:: javascript + + { + "policy": [ + { + "authentication_method": 1, + "provider": "http://localhost:8088/" + }, + { + "authentication_method": 3, + "provider": "http://localhost:8089/" + } + ] + } + +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 + + { + "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/" + }, + { + "authentication_method": 2, + "provider": "http://localhost:8088/" + } + ] + }, + { + "methods": [ + { + "authentication_method": 1, + "provider": "http://localhost:8089/" + }, + { + "authentication_method": 2, + "provider": "http://localhost:8088/" + } + ] + }, + { + "methods": [ + { + "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 +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 +simply specifies the index of the policy to delete, for example: + +.. code-block:: json + + { + "policy_index": 3 + } + +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/" + }, + { + "authentication_method": 2, + "provider": "http://localhost:8088/" + } + ] + }, + { + "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 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 +state are acceptable. The transition does not take any arguments. + +The reducer will simply transition to the ``SECRET_EDITING`` state: + +.. code-block:: json + + { + "backup_state": "SECRET_EDITING", + "upload_fees" : [ "KUDOS:42" ], + "expiration" : { "t_ms" : 1245362362 } + } + +Here, ``upload_fees`` is an array of applicable upload fees for the +given policy expiration time. This is an array because fees could +be in different currencies. The final cost may be lower if the +user already paid for some of the time. + +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:** + +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, or a ``text`` field with a human-readable secret text. +For example: + +.. code-block:: javascript + + { + "secret": { + "value": "EDJP6WK5EG50", + "mime" : "text/plain" + }, + "expiration" : { "t_ms" : 1245362362 } + } + +If the application is unaware of the format, it set the ``mime`` field to ``null``. +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 +be updated. + +.. code-block:: json + + { + "backup_state": "SECRET_EDITING", + "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 built-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 +and to update the associated cost. For example: + +.. code-block:: javascript + + { + "expiration" : { "t_ms" : 1245362362 } + } + +The reducer remains in the ``SECRET_EDITING`` state, but the +expiration time and cost calculation will be updated. + +.. code-block:: json + + { + "backup_state": "SECRET_EDITING", + "expiration" : { "t_ms" : 1245362362 }, + "upload_fees" : [ { "fee": "KUDOS:43" } ] + } + + +**next** (from ``SECRET_EDITING``): + +Using this transition, the user confirms that the secret and expiration +settings in the current state are acceptable. The transition does not take any +arguments. + +If the secret is currently empty, the reducer will transition into an +``ERROR`` state instead of allowing the user to continue. + +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", + "secret_name" : "$NAME", + "core_secret" : { "$anything":"$anything" }, + "payments": [ + "taler://pay/...", + "taler://pay/..." + ] + } + +.. code-block:: json + + { + "backup_state": "POLICIES_PAYING", + "secret_name" : "$NAME", + "core_secret" : { "$anything":"$anything" }, + "payments": [ + "taler://pay/...", + "taler://pay/..." + ] + } + +.. code-block:: json + + { + "backup_state": "BACKUP_FINISHED", + "success_details": { + "http://localhost:8080/" : { + "policy_version" : 1, + "policy_expiration" : { "t_ms" : 1245362362000 } + }, + "http://localhost:8081/" : { + "policy_version" : 3, + "policy_expiration" : { "t_ms" : 1245362362000 } + } + } + } + + +**pay:** + +This transition suggests to the reducer that a payment may have been made or +is immanent, and that the reducer should check with the Anastasis service +provider to see if the operation is now possible. The operation takes one +optional argument, which is a ``timeout`` value that specifies how long the +reducer may wait (in long polling) for the payment to complete: + +.. code-block:: json + + { + "timeout": { "d_ms" : 5000 }, + } + +The specified timeout is passed on to the Anastasis service provider(s), which +will wait this long before giving up. If no timeout is given, the check is +done as quickly as possible without additional delays. The reducer will continue +to either an updated state with the remaining payment requests, to the +``BACKUP_FINISHED`` state (if all payments have been completed and the backup +finished), or into an ``ERROR`` state in case there was an irrecoverable error, +indicating the specific provider and how it failed. An example for this +final error state would be: + +.. code-block:: json + + { + "backup_state": "ERROR", + "http_status" : 500, + "upload_status" : 52, + "provider_url" : "https://bad.example.com/", + } + +Here, the fields have the following meaning: + + - **http_status** is the HTTP status returned by the Anastasis provider. + - **upload_status** is the Taler error code return by the provider. + - **provider_url** is the base URL of the failing provider. + +In the above example, 52 would thus imply that the Anastasis provider failed to +store information into its database. + + +Recovery transitions +-------------------- + +**enter_user_attributes:** + +This transition provides the user's personal attributes. The specific set of +attributes required depends on the country of residence of the user. Some +attributes may be optional, in which case they should be omitted entirely +(that is, not simply be set to ``null`` or an empty string). The +arguments are identical to the **enter_user_attributes** transition from +the backup process. Example arguments would thus be: + +.. code-block:: json + + { + "identity_attributes": { + "full_name": "Max Musterman", + "social_security_number": "123456789", + "birthdate": "2000-01-01", + "birthplace": "Earth" + } + } + +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: + +.. code-block:: json + + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "challenges": [ + { + "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G", + "cost": "TESTKUDOS:0", + "type": "question", + "instructions": "q1" + }, + { + "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "cost": "TESTKUDOS:0", + "type": "email", + "instructions": "e-mail address m?il@f*.bar" + }, + ], + "policies": [ + [ + { + "uuid": "MW2R3RCBZPHNC78AW8AKWRCHF9KV3Y82EN62T831ZP54S3K5599G" + }, + { + "uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0" + }, + ], + ], + "provider_url": "http://localhost:8088/", + "version": 1, + }, + "recovery_document": { + "...": "..." + } + } + +The ``recovery_document`` is an internal representation of the recovery +information and of no concern to the user interface. The pertinent information +is in the ``recovery_information``. Here, the ``challenges`` array is a list +of possible challenges the user could attempt to solve next, while ``policies`` +is an array of policies, with each policy being an array of challenges. +Satisfying all of the challenges of one of the policies will enable the secret +to be recovered. The ``provider_url`` from where the recovery document was +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 + 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 + an abbreviated form of the contact information or the security + question. Details depend on ``type``. + +If a recovery document was not found, either the user never performed +a backup, entered incorrect attributes, or used a provider not yet in +the list of Anastasis providers. Hence, the user must now either +select a different provider, or go ``back`` and update the identity +attributes. In the case a recovery document was not found, the +transition fails, returning the error code and a human-readable error +message together with a transition failure: + +.. code-block:: json + + { + "recovery_state": "ERROR", + "error_message": "account unknown to Anastasis server", + "error_code": 9, + } + +Here, the ``error_code`` is from the ``enum ANASTASIS_RecoveryStatus`` +and describes precisely what failed about the download, while the +``error_message`` is a human-readable (English) explanation of the code. +Applications may want to translate the message using GNU gettext; +translations should be available in the ``anastasis`` text domain. +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:** + +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: + +.. code-block:: json + + { + "provider_url": "https://localhost:8080/", + "version": 2 + } + +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. + + +**select_challenge:** + +Selecting a challenge takes different, depending on the state of the payment. +A comprehensive example for ``select_challenge`` would be: + +.. code-block:: json + + { + "uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" + "timeout" : { "d_ms" : 5000 }, + "payment_secret": "3P4561HAMHRRYEYD6CM6J7TS5VTD5SR2K2EXJDZEFSX92XKHR4KG" + } + +The ``uuid`` field is mandatory and specifies the selected challenge. +The other fields are optional, and are needed in case the user has +previously been requested to pay for the challenge. In this case, +the ``payment_secret`` identifies the previous payment request, and +``timeout`` says how long the Anastasis service should wait for the +payment to be completed before giving up (long polling). + +Depending on the type of the challenge and the need for payment, the +reducer may transition into ``CHALLENGE_SOLVING`` or ``CHALLENGE_PAYING`` +states. In ``CHALLENGE_SOLVING``, the new state will primarily specify +the selected challenge: + +.. code-block:: json + + { + "backup_state": "CHALLENGE_SOLVING", + "selected_challenge_uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" + } + +In ``CHALLENGE_PAYING``, the new state will include instructions for payment +in the ``challenge_feedback``. In general, ``challenge_feedback`` includes +information about attempted challenges, with the final state being ``solved``: + +.. code-block:: json + + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "...": "..." + } + "challenge_feedback": { + "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" : { + "state" : "solved" + } + } + } + +Challenges feedback for a challenge can have many different ``state`` values +that applications must all handle. States other than ``solved`` are: + + - **payment**: Here, the user must pay for a challenge. An example would be: + + .. code-block:: json + + { + "backup_state": "CHALLENGE_PAYING", + "selected_challenge_uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30", + "challenge_feedback": { + "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30" : { + "state" : "payment", + "taler_pay_uri" : "taler://pay/...", + "provider" : "https://localhost:8080/", + "payment_secret" : "3P4561HAMHRRYEYD6CM6J7TS5VTD5SR2K2EXJDZEFSX92XKHR4KG" + } + } + } + + - **body**: Here, the server provided an HTTP reply for + how to solve the challenge, but the reducer could not parse + them into a known format. A mime-type may be provided and may + help parse the details. + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "body", + "body": "CROCKFORDBASE32ENCODEDBODY", + "http_status": 403, + "mime_type" : "anything/possible" + } + } + } + + - **hint**: Here, the server provided human-readable hint for + how to solve the challenge. Note that the ``hint`` provided this + time is from the Anastasis provider and may differ from the ``instructions`` + for the challenge under ``recovery_information``: + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "hint", + "hint": "Recovery TAN send to email mail@DOMAIN", + "http_status": 403 + } + } + } + + - **details**: Here, the server provided a detailed JSON status response + related to solving the challenge: + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "details", + "details": { + "code": 8111, + "hint": "The client's response to the challenge was invalid.", + "detail" : null + }, + "http_status": 403 + } + } + } + + - **redirect**: To solve the challenge, the user must visit the indicated + Web site at ``redirect_url``, for example to perform video authentication: + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SOLVING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "redirect", + "redirect_url": "https://videoconf.example.com/", + "http_status": 303 + } + } + } + + - **server-failure**: This indicates that the Anastasis provider encountered + a failure and recovery using this challenge cannot proceed at this time. + Examples for failures might be that the provider is unable to send SMS + messages at this time due to an outage. The body includes details about + the failure. The user may try again later or continue with other challenges. + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "server-failure", + "http_status": "500", + "error_code": 52 + } + } + } + + - **truth-unknown**: This indicates that the Anastasis provider is unaware of + the specified challenge. This is typically a permanent failure, and user + interfaces should not allow users to re-try this challenge. + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "truth-unknown", + "error_code": 8108 + } + } + } + + - **rate-limit-exceeded**: + + .. code-block:: json + + { + "recovery_state": "CHALLENGE_SELECTING", + "recovery_information": { + "...": "..." + } + "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0", + "challenge_feedback": { + "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": { + "state": "rate-limit-exceeded", + "error_code": 8121 + } + } + } + +**pay:** + +With a ``pay`` transition, the application indicates to the reducer that +a payment may have been made. Here, it is again possible to specify an +optional ``timeout`` argument for long-polling, for example: + +.. code-block:: json + + { + "payment_secret": "ABCDADF242525AABASD52525235ABABFDABABANALASDAAKASDAS" + "timeout" : { "d_ms" : 5000 }, + } + +Depending on the type of the challenge and the result of the operation, the +new state may be ``CHALLENGE_SOLVING`` (if say the SMS was now sent to the +user), ``CHALLENGE_SELECTING`` (if the answer to the security question was +correct), ``RECOVERY_FINISHED`` (if this was the last challenge that needed to +be solved) or still ``CHALLENGE_PAYING`` (if the challenge was not actually +paid for). For sample messages, see the different types of +``challenge_feedback`` in the section about ``select_challenge``. + + +**solve_challenge:** + +Solving a challenge takes various formats, depending on the type of the +challenge and what is known about the answer. The different supported +formats are: + +.. code-block:: json + + { + "answer": "answer to security question" + } + +.. code-block:: json + + { + "pin": 1234 + } + +.. code-block:: json + + { + "hash": "SOMEBASE32ENCODEDHASHVALUE" + } |