update docs

1 files changed, 218 insertions, 39 deletions

diff --git a/anastasis.rst b/anastasis.rst
index 77fb1d6d..0f89230d 100644
--- a/anastasis.rst
+++ b/anastasis.rst
@@ -1968,7 +1968,7 @@ a state where the user can choose which challenges to satisfy:
           ]
         ],
         "provider_url": "http://localhost:8088/",
-        "version": 1 // FIXME: wrong in code!
+        "version": 1
       },
       "recovery_document": {
         ...
@@ -2045,22 +2045,28 @@ latest available version at the provider.
 
 **select_challenge:**
 
-Selecting a challenge takes various formats, depending on the method.
-Specifically, in the case of a security question, the answer should
-already be provided.
-
-FIXME: give more details!
-
-Arguments (example):
+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": "FIXME-EXAMPLE"
     }
 
+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).
 
-Expected new state (depending on method and whether it requires payment):
+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
 
@@ -2069,36 +2075,171 @@ Expected new state (depending on method and whether it requires payment):
       "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
 
     {
-      "backup_state": "CHALLENGE_PAYING",
-      "selected_challenge_uuid": "80H646H5ZBR453C02Y5RT55VQSJZGM5REWFXVY0SWXY1TNE8CT30"
+      "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" : "FIXME-EXAMPLE"
+            }
+          }
+        }
+
+    - **instructions**: Here, the server provided human-readable instructions for
+      how to solve the challenge.  Note that the ``instructions`` provided this
+      time are 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": "instructions",
+               "instructions": "Recovery TAN send to email mail@DOMAIN",
+               "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:
+
+         {
+           "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.
+
+         {
+           "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.
+
+         {
+           "recovery_state": "CHALLENGE_SELECTING",
+           "recovery_information": {
+             // ...
+           }
+           "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+           "challenge_feedback": {
+             "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+               "state": "truth-unknown",
+               "error_code": 8108
+             }
+           }
+         }
+
+      - **rate-limit-exceeded**:
+
+         {
+           "recovery_state": "CHALLENGE_SELECTING",
+           "recovery_information": {
+             // ...
+           }
+           "selected_challenge_uuid": "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0",
+           "challenge_feedback": {
+             "TXYKGE1SJZHJ4M2FKSV1P2RZVNTHZFB9E3A79QE956D3SCAWXPK0": {
+               "state": "rate-limit-exceeded",
+               "error_code": 8121
+             }
+           }
+         }
 
 **pay:**
 
-Arguments (example):
+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 method and
-what is known about the answer.
-
-Arguments (example):
+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 secure question"
+        "answer": "answer to security question"
     }
 
 .. code-block:: json
@@ -2120,49 +2261,87 @@ Arguments (example):
 Authentication Methods
 ----------------------
 
-This section describes the supported authentication methods in
-detail.
+This section describes the supported authentication methods in detail.  We
+note that the server implements rate limiting for all authentication methods
+to ensure that malicious strong attackers cannot guess the values by
+brute-force. Typically, a user is given three attempts per hour to enter the
+correct code from 2^63 possible values.  Transmitted codes also come with an
+expiration date. If the user re-requests a challenge to be sent, the same
+challenge may be transmitted (with the three attempts counter not increasing!)
+for a limited period of time (depending on the authentication method) before
+the service eventually rotates to a fresh random code with a fresh retry
+counter. Given the default value range and time intervals (which providers are
+at liberty to adjust), brute-force attacks against this are expected to
+succeed with a 50% probability after about 200000 years of attempts at the
+maximum permissible frequency.
 
 
 SMS (sms)
 ^^^^^^^^^
 
-Sends an SMS with a code to the users phone.
-The user must send this code back with his request (see ``$RESPONSE`` under `Managing truth`_).
-If the transmitted code is correct, the server responses with the requested encrypted key share.
-FIXME: details!
+Sends an SMS with a code (prefixed with ``A-``) to the user's phone, including
+a UUID which identifies the challenge the code is for.  The user must send
+this code back with his request (see ``$RESPONSE`` under `Managing truth`_).
+If the transmitted code is correct, the server responses with the requested
+encrypted key share.
+
 
 
 Email verification (email)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
-Sends an email with a code to the users mail address.
-The user must send this code back with his request (see ``$RESPONSE`` under `Managing truth`_).
-If the transmitted code is correct, the server responses with the requested encrypted key share.
-FIXME: details!
+
+Sends an email with a code (prefixed with ``A-``) to the user's mail address,
+including a UUID which identifies the challenge the code is for.  The user
+must send this code back with his request (see ``$RESPONSE`` under `Managing
+truth`_).  If the transmitted code is correct, the server responses with the
+requested encrypted key share.
 
 
 Video identification (vid)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Requires the user to identify via video-call. The user is expected to delete all metadata revealing
-information about him/her from the images before uploading them. Since the respective images must
-be passed on to the video identification service in the event of password recovery, it must be
-ensured that no further information about the user can be derived from them.
-FIXME: details!
+Requires the user to identify via video-call.  In the video-call, the
+user is told the code (prefixed with ``A-``) needed to authenticate.
+
+The user is expected to delete all metadata revealing information about per
+from the images before uploading them. Since the respective images must be
+passed on to the video identification service in the event of password
+recovery, it should be ensured that no further information about the user can
+be derived from them.
+
+Video identification will typically result in the Anastasis provider
+requesting the user to be redirected to a Web site (or other URL) for the
+video-call.
+
 
 
 Security question (qa)
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Asks the user a security question.  The user sends back a hash over the
-answer.  If the hash value matches with the one the server is expecting, the
-server answers with the requested encrypted key share.  A different hash
-function over the same security answer is used to provide **optional data**
-for the decryption of the (encrypted) **key share**.
+Asks the user a security question.  The user sends back a **salted**
+hash over the answer.  The **question-salt** is stored encrypted as
+part of the recovery document and never revealed to the providers. This
+ensures that providers cannot derive the answer from the hash value.
+Furthermore, the security question itself is also only in the recovery
+document and never given to the Anastasis provider.  A moderately expensive
+hash function is used to further limit strong attackers that have obtained
+the recovery document from brute-forcing the answer.
+
+If the hash value matches with the one the server is expecting, the server
+answers with the requested encrypted key share.  However, unlike other
+encrypted key shares, the encrypted key share of a security question uses a
+special variation of the Anastasis encryption: Here, a different hash function
+over the security answer is used to provide an additional **key-salt** for the
+decryption of the (encrypted) **key share**.  This ensures that the key share
+remains irrecoverable without the answer even if the Anastasis provider
+storing the security question is malicious.
 
 
 Snail mail verification (post)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Physical address verification via snail mail.
-FIXME: details!
+Sends physical mail (snail mail) with a code (prefixed with ``A-``) to the
+user's mail address, including a UUID which identifies the challenge the code
+is for.  The user must send this code back with their request (see
+``$RESPONSE`` under `Managing truth`_).  If the transmitted code is correct,
+the server responds with the requested encrypted key share.