-more legwork for new auth method support

6 files changed, 50 insertions, 390 deletions

diff --git a/doc/sphinx/design-documents/001-anastasis-ux.rst b/doc/sphinx/design-documents/001-anastasis-ux.rst
deleted file mode 100644
index 741d6ca..0000000
--- a/doc/sphinx/design-documents/001-anastasis-ux.rst
+++ /dev/null
@@ -1,318 +0,0 @@
-Design Doc 001: Anastasis User Experience
-#########################################
-
-Summary
-=======
-
-This document describes the recommended way of implementing the user experience
-of setting up and making use of :doc:`../introduction` account recovery.
-
-Motivation
-==========
-
-Wallet state consisting of digital cash, transaction history etc. should not be lost.
-Taler provides a backup mechanism to prevent that.
-As an additional protection measure Anastasis can be used to provide access to the backup,
-even if all devices and offline secrets have been lost.
-
-Access to the backup key is shared with escrow providers that can be chosen by the user.
-
-Setup Steps
-===========
-
-.. graphviz::
-
-   digraph G {
-       rankdir=LR;
-       nodesep=0.5;
-       settings [
-           label = "Backup\nSettings";
-           shape = oval;
-       ];
-       backup_is_setup [
-           label = "Backup\nsetup?";
-           shape = diamond;
-       ];
-       provide_id [
-           label = "Provide\nIdentification";
-           shape = rectangle;
-       ];
-       select_auth [
-           label = "Select\nAuthentication Methods";
-           shape = rectangle;
-       ];
-       provide_auth [
-           label = "Provide\nAuthentication Data";
-           shape = rectangle;
-       ];
-       select_providers [
-           label = "Select\nService Providers";
-           shape = rectangle;
-       ];
-       review_policy [
-           label = "Review Recovery Policy";
-           shape = rectangle;
-       ];
-       edit_policy [
-           label = "Edit Recovery Policy";
-           shape = rectangle;
-       ];
-       pay [
-           label = "Confirm Payment";
-           shape = oval;
-       ];
-       settings -> backup_is_setup;
-       backup_is_setup -> provide_id [label="Yes: Setup Recovery"];
-       backup_is_setup -> settings [label="No"];
-       provide_id -> select_auth;
-       select_auth -> provide_auth;
-       provide_auth -> select_auth;
-       select_auth -> select_providers;
-       select_providers -> select_auth;
-       select_providers -> review_policy;
-       review_policy -> edit_policy;
-       edit_policy -> review_policy;
-       review_policy -> pay;
-   }
-
-Entry point: Settings
----------------------
-
-The app settings should have a section for Anastasis using a different more
-universally understood name like Wallet Recovery.
-
-The section should have an option to setup Anastasis initially.  This option
-should be disabled as long as no backup has been set up.  The section could
-maybe be integrated into the backup settings.
-
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/menu.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/settings.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/backupsettings.png
-  :width: 800
-
-Providing Identification
-------------------------
-
-Instead of a forgettable freely chosen user name, Anastasis collects various
-static information from the user to generate a unique user identifier from
-that.  Examples for such identifier would be a concatenation of the full name
-of the user and their social security or passport number(s).
-
-The information that can reasonably used here various from cultural context
-and jurisdiction.  Therefore, one idea is to start by asking for continent and
-then the country of primary legal residence, and then continue from there with
-country-specific attributes (and also offer a stateless person option).
-
-Special care should be taken to avoid that information can later be provided
-ambiguously thus changing the user identifier and not being able to restore
-the user's data.  This can be typographic issues like someone providing
-"Seestr."  and later "Seestrasse" or "Seestraße" or "seestrasse".  But it can
-also be simple typos that we can only prevent in some instances like when
-checking checksums in passport numbers.
-
-The user should be made aware that this data will not leave the app and that
-it is only used to compute a unique identifier that can not be forgotten.
-
-If possible, we should guide the user in the country selection by accessing
-permission-less information such as the currently set language/locale and the
-country of the SIM card.  But nothing invasive like the actual GPS location.
-
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/userid.png
-  :width: 800
-
-Add Authentication Methods
---------------------------
-
-After creating a unique identifier, the user can chose one or more
-:ref:`anastasis-auth-methods` supported by Anastasis.
-
-When selecting a method, the user is already asked to provide the information
-required for the recovery with that method.  For example, a photo of
-themselves, their phone number or mailing address.
-
-The user interface validates that the inputs are well-formed, and refuses
-inputs that are clearly invalid. Where possible, it pre-fills the fields with
-sane values (phone number, e-mail addresses, country of residence).
-
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/truth.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addtruth.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addtruthmail.png
-  :width: 800
-
-
-Confirm/Change Service Providers
---------------------------------
-
-From the dialog where the user is adding authentication methods, the user can
-optionally jump to a side-action with list of available providers (and their
-status) and possibly add additional providers that are not included in the
-default list provided by the wallet.
-
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/policy.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addpolicy.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/addpolicymethod.png
-  :width: 800
-
-
-Defining Recovery Options
--------------------------
-
-After mapping authentication methods to providers, the user needs select which
-combinations are sufficient to recover the secret.  Here, the system
-pre-computes a reasonably sane allocation, for small ``n`` the default could
-be ``n-1`` out of ``n``.
-
-We should propose a mapping of authentication methods to providers by
-minimizing cost (tricky: sign-up vs. recovery costs, different currencies) and
-distributing the selected authentication methods across as many providers as
-possible.
-
-The user should be able to change the proposed default selection
-and add more than one provider to each chosen method.
-
-Using Anastatis providers usually is not free.  From here on, the UI should
-show estimated recurring costs (yearly) and the cost of recovery.  These costs
-should get updated with each user action affecting those costs such as
-when the user reconfigures the policies.
-
-
-Pay for Setup
--------------
-
-As the last step when all information has been properly provided, the user is
-asked to pay for the service with the regular wallet payment confirmation
-screen.
-
-
-Show Service Status After Setup
-===============================
-
-TODO
-
-Recovery Steps
-==============
-
-.. graphviz::
-
-   digraph G {
-       rankdir=LR;
-       nodesep=0.5;
-       settings [
-           label = "Restore from Backup";
-           shape = oval;
-       ];
-       provide_id [
-           label = "Provide\nIdentification";
-           shape = rectangle;
-       ];
-       select_challenge [
-           label = "Select\nAuthentication Challenge";
-           shape = rectangle;
-       ];
-       satisfy_challenge [
-           label = "Enter\nChallenge Response";
-           shape = rectangle;
-       ];
-       pay [
-           label = "Confirm Payment";
-           shape = oval;
-       ];
-       finished [
-           label = "Success";
-           shape = rectangle;
-       ];
-       settings -> provide_id;
-       provide_id -> settings [label="Back"];
-       provide_id -> select_challenge;
-       select_challenge -> provide_id [label="Back"];
-       select_challenge -> satisfy_challenge;
-       select_challenge -> pay;
-       satisfy_challenge -> pay;
-       pay -> satisfy_challenge;
-       satisfy_challenge -> select_challenge;
-       pay -> finished;
-       satisfy_challenge -> finished;
-   }
-
-
-Entry point: Settings
----------------------
-
-Like the backup, the recovery option should be available via
-the App settings.
-
-The section should have an option to recover from backup.  If a previous
-recovery was not completed, the interaction should resume from that previous
-checkpoint instead of from the beginning.
-
-
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/menu.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/settings.png
-  :width: 800
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/backupsettings.png
-  :width: 800
-
-
-Providing Identification
-------------------------
-
-The first dialog(s) during recovery should be identical to the first dialog
-during backup: the user is asked to select a continent, country of residence
-and then to provide country-specific inputs for identification.
-
-.. image:: https://git.taler.net/anastasis.git/plain/doc/wireframe/png-export/userid.png
-  :width: 800
-
-Select Authentication Challenge
--------------------------------
-
-If Anastasis could recover the recovery document via any provider, it should
-show a dialog allowing the user to select one of the open challenges, and
-highlight which challenges still need to be satisfied for the various policies.
-
-Additionally, the specific provider and recovery document version should be shown.
-The user should be able to change the provider or recovery document version,
-resulting in a switch of the recovery document and policies. If the user has
-already satisfied some challenges of the current recovery document, switching to a
-different recovery document should only be done after a confirmation pop-up dialog
-warning the user that the existing progress will be lost.
-
-When selecting a challenge, the user may be asked to confirm making a payment
-for this challenge if the provider requires payment.
-
-
-Payment
--------
-
-Typcially, this would be the canonical wallet payment confirmation dialog.
-
-However, in the case of a security question, the payment confirmation should
-be combined with the dialog where the user enters the security answer (so
-instead of an ``Ok`` button, text showing the amount due and ``Pay`` should be
-used -- except of course if the security question challenge is free of
-charge).
-
-
-Enter Challenge Response
-------------------------
-
-If the challenge was not a security question, the dialog to enter the security
-code (PIN/TAN) should open after payment.  The security code field should have
-a prefix ``A-``. However, the user should be able to enter both only the
-numeric code, or the full code with the ``A-`` prefix (or ideally, the user
-cannot delete the pre-filled ``A-`` text).
-
-
-Success
--------
-
-The user is informed about the successful recovery.  We may want to do this
-as part of a separate screen, or simply with a notification bar in the
-main wallet screen.
diff --git a/doc/sphinx/design-documents/999-template.rst b/doc/sphinx/design-documents/999-template.rst
deleted file mode 100644
index f620248..0000000
--- a/doc/sphinx/design-documents/999-template.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-Template
-########
-
-Summary
-=======
-
-Motivation
-==========
-
-Requirements
-============
-
-Proposed Solution
-=================
-
-Alternatives
-============
-
-Drawbacks
-=========
-
-Discussion / Q&A
-================
-
-(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/doc/sphinx/design-documents/index.rst b/doc/sphinx/design-documents/index.rst
deleted file mode 100644
index 3fb647a..0000000
--- a/doc/sphinx/design-documents/index.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-Design Documents
-################
-
-This is a collection of design documents related to Anastasis.
-The goal of these documents is to discuss facilitate discussion around
-new features while keeping track of the evolution of the whole system
-and protocol.
-
-.. toctree::
-  :glob:
-
-  001-anastasis-ux
-  999-template
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 8c19ebc..1f74056 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -63,7 +63,6 @@ Documentation Overview
   reducer
   authentication
   db
-  design-documents/index
   global-licensing
   manindex
   genindex
diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst
index bfff83a..cf1630a 100644
--- a/doc/sphinx/introduction.rst
+++ b/doc/sphinx/introduction.rst
@@ -54,24 +54,28 @@ to recover their core secret.
 The recovery document
 ---------------------
 
-A **recovery document** includes all of the information a user needs to
-recover access to their core secret.  It specifies a set of **escrow
-methods**, which specify how the user should convince the Anastasis server
-that they are "real".  Escrow methods can for example include SMS-based
-verification, video identification or a security question.  For each escrow
-method, the Anastasis server is provided with **truth**, that is data the
-Anastasis operator may learn during the recovery process to authenticate the
-user.  Examples for truth would be a phone number (for SMS), a picture of the
-user (for video identification), or the (hash of) a security answer.  A strong
-adversary is assumed to be able to learn the truth, while weak adversaries
-must not.  In addition to a set of escrow methods and associated Anastasis
-server operators, the **recovery document** also specifies **policies**, which
-describe the combination(s) of the escrow methods that suffice to obtain
-access to the core secret.  For example, a **policy** could say that the
-escrow methods (A and B) suffice, and a second policy may permit (A and C).  A
-different user may choose to use the policy that (A and B and C) are all
-required.  Anastasis imposes no limit on the number of policies in a
-**recovery document**, or the set of providers or escrow methods involved in
+A **recovery document** includes all of the information a user needs
+to recover access to their core secret.  It specifies a set of
+**escrow methods**, which specify how the user should convince the
+Anastasis server that they are "real".  Escrow methods can for example
+include SMS-based verification, video identification or a security
+question.  For each escrow method, the Anastasis server is provided
+with **truth**, that is data the Anastasis operator may learn during
+the recovery process.  Truth always consists of an encrypted key share
+and associated data to authenticate the user.  Examples for truth
+would be a phone number (for SMS), a picture of the user (for video
+identification), or the (hash of) a security answer.  A strong
+adversary is assumed to be able to learn the truth, while weak
+adversaries must not.  In addition to a set of escrow methods and
+associated Anastasis server operators, the **recovery document** also
+specifies **policies**, which describe the combination(s) of the
+escrow methods that suffice to obtain access to the core secret.  For
+example, a **policy** could say that the escrow methods (A and B)
+suffice, and a second policy may permit (A and C).  A different user
+may choose to use the policy that (A and B and C) are all required.
+Anastasis imposes no limit on the number of policies in a **recovery
+document**, or the set of providers or escrow methods involved in
 guarding a user's secret.  Weak adversaries must not be able to deduce
-information about a user's **recovery document** (except for its length, which
-may be exposed to an adversary which monitors the user's network traffic).
+information about a user's **recovery document** (except for its
+length, which may be exposed to an adversary which monitors the user's
+network traffic).
diff --git a/doc/sphinx/rest.rst b/doc/sphinx/rest.rst
index ba9d768..67c1fef 100644
--- a/doc/sphinx/rest.rst
+++ b/doc/sphinx/rest.rst
@@ -343,6 +343,13 @@ In the following, UUID is always defined and used according to `RFC 4122`_.
 Managing truth
 ^^^^^^^^^^^^^^
 
+Truth always consists of an encrypted key share and encrypted
+authentication data.  The key share and the authentication data
+are encrypted using different keys. Additionally, truth includes
+the name of the authentication method, the mime-type of the
+authentication data, and an expiration time in
+cleartext.
+
 This API is used by the Anastasis client to deposit **truth** or request a (encrypted) **key share** with
 the escrow provider.
 
@@ -398,13 +405,6 @@ charge per truth operation using GNU Taler.
       // Key share method, i.e. "security question", "SMS", "e-mail", ...
       type: string;
 
-      // Nonce used to compute the (iv,key) pair for encryption of the
-      // encrypted_truth.
-      nonce: [32]; //bytearray
-
-      // Authentication tag of ``encrypted_truth``.
-      aes_gcm_tag: [16]; //bytearray
-
       // Variable-size truth. After decryption,
       // this contains the ground truth, i.e. H(challenge answer),
       // phone number, e-mail address, picture, fingerprint, ...
@@ -412,10 +412,10 @@ charge per truth operation using GNU Taler.
       //
       // The nonce of the HKDF for this encryption must include the
       // string "ECT".
-      encrypted_truth: [80]; //bytearray
+      encrypted_truth: []; //bytearray
 
       // MIME type of truth, i.e. text/ascii, image/jpeg, etc.
-      truth_mime: string;
+      truth_mime?: string;
 
       // For how many years from now would the client like us to
       // store the truth?
@@ -423,14 +423,23 @@ charge per truth operation using GNU Taler.
 
     }
 
-.. http:get:: /truth/$UUID[?response=$H_RESPONSE]
+.. http:get:: /truth/$UUID
 
-  Get the stored encrypted key share. If ``$H_RESPONSE`` is specified by the client, the server checks
-  if ``$H_RESPONSE`` matches the expected response specified before within the `TruthUploadRequest`_ (see ``encrypted_truth``).
+  Get the stored encrypted key share.
   Also, the user has to provide the correct *truth_encryption_key* with every get request (see below).
-  When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share.
   The encrypted key share is returned simply as a byte array and not in JSON format.
 
+  :query response=H_RESPONSE: *Optional.*  If ``$H_RESPONSE`` is specified by the client,
+    the server checks if ``$H_RESPONSE`` matches the expected response. This can be the
+    hash of the security question (as specified before by the client
+    within the `TruthUploadRequest`_ (see ``encrypted_truth``)), or the hash of the
+    PIN code sent via SMS, E-mail or postal communication channels.
+    When ``$H_RESPONSE`` is correct, the server responds with the encrypted key share.
+  :query timeout_ms=NUMBER: *Optional.*  If specified, the Anastasis server will
+    wait up to ``timeout_ms`` milliseconds for completion of the payment or the
+    challenge before sending the HTTP response.  A client must never rely on this
+    behavior, as the backend may return a response immediately.
+
   **Response**:
 
   :http:statuscode:`200 OK`:
@@ -454,6 +463,10 @@ charge per truth operation using GNU Taler.
     The server requires a valid "response" to the challenge associated with the UUID.
   :http:statuscode:`404 Not found`:
     The server does not know any truth under the given UUID.
+  :http:statuscode:`408 Request Timeout`:
+    Accessing this truth requires satisfying an external authentication challenge
+    (and not merely passing a response in the request) and this has not happened
+    before the timeout was reached.
   :http:statuscode:`410 Gone`:
     The server has not (recently) issued a challenge under the given UUID,
     but a reply was provided. (This does not apply for secure question.)