commit eb97aa4cf503bdc7955dda78bc1599d5a0660603
parent 77065e31d20b680ebd7e922e4b2a1b8769b385e7
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 29 Mar 2021 21:24:31 +0200
work on Anastasis docs
Diffstat:
| M | anastasis.rst | | | 173 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------ |
1 file changed, 160 insertions(+), 13 deletions(-)
diff --git a/anastasis.rst b/anastasis.rst
@@ -922,10 +922,42 @@ above would look like following for the transition action_ "select_continent":
]
}
-**State**:
- - 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.
+States
+^^^^^^
+
+Overall, the reducer knows the following states:
+
+ - **ERROR**: The transition lead 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.
+ - **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
@@ -963,12 +995,14 @@ 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 looking like following:
+The initial states for backup and recovery processes are:
**Initial backup state:**
@@ -978,7 +1012,7 @@ The initial states for backup and recovery processes are looking like following:
"backup_state": "CONTINENT_SELECTING",
"continents": [
"Europe",
- "North_America"
+ "North America"
]
}
@@ -991,17 +1025,49 @@ The initial states for backup and recovery processes are looking like following:
"recovery_state": "CONTINENT_SELECTING",
"continents": [
"Europe",
- "North_America"
+ "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:**
-Arguments (example):
+Here the user specifies the continent they live on. Arguments (example):
.. code-block:: json
@@ -1009,7 +1075,11 @@ Arguments (example):
"continent": "Europe"
}
-Expected new state:
+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
@@ -1047,6 +1117,19 @@ Expected new state:
]
}
+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.
@@ -1063,7 +1146,13 @@ Arguments (example):
"currency": "EUR"
}
-Expected new state:
+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
@@ -1082,7 +1171,8 @@ Expected new state:
"fr": "Nom complet",
"en": "Full name"
},
- "widget": "anastasis_gtk_ia_full_name"
+ "widget": "anastasis_gtk_ia_full_name",
+ "uuid" : "9e8f463f-575f-42cb-85f3-759559997331"
},
{
"type": "date",
@@ -1094,6 +1184,7 @@ Expected new state:
"fr": "Date de naissance",
"en": "Birthdate"
},
+ "uuid" : "83d655c7-bdb6-484d-904e-80c1058c8854"
"widget": "anastasis_gtk_ia_birthdate"
},
{
@@ -1106,8 +1197,10 @@ Expected new state:
"fr": "Numéro de sécurité sociale",
"en": "Social security number"
},
- "widget": "anastasis_gtk_ia_ssn"
- }
+ "widget": "anastasis_gtk_ia_ssn",
+ "validation-regex": "^[0-9]{8}[[:upper:]][0-9]{3}$",
+ "validation-logic": "DE_SVN_check"
+ }
],
"authentication_providers": {
"http://localhost:8089/": {
@@ -1145,6 +1238,60 @@ Expected new state:
}
}
+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 identicial.
+ - **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).
+
+The authentication providers are listed under a key that is the
+base URL of the service. For each provider, the following
+information is provided:
+
+ - **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.
+ - **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.
+ - **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.
+
+FIXME: specify what will be provided in case GET /config fails!
+
**add_provider**:
