summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-08-14 13:32:31 +0200
committerChristian Grothoff <christian@grothoff.org>2021-08-14 13:32:31 +0200
commitf4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6 (patch)
tree5b095579d4cc244f65472477a74c17674d329196 /doc
parent71c62583d81f149cef2bdbe13870da70b50f3cbd (diff)
downloadanastasis-f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6.tar.gz
anastasis-f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6.tar.bz2
anastasis-f4a4a0806bf361ccbd2d0f9bbdc34187cccba6c6.zip
-more legwork for new auth method support
Diffstat (limited to 'doc')
-rw-r--r--doc/anastasis.texi1398
-rw-r--r--doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.pngbin0 -> 45040 bytes
-rw-r--r--doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png.map2
-rw-r--r--doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.pngbin0 -> 43918 bytes
-rw-r--r--doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png.map2
-rw-r--r--doc/sphinx/design-documents/001-anastasis-ux.rst318
-rw-r--r--doc/sphinx/design-documents/999-template.rst25
-rw-r--r--doc/sphinx/design-documents/index.rst13
-rw-r--r--doc/sphinx/index.rst1
-rw-r--r--doc/sphinx/introduction.rst44
-rw-r--r--doc/sphinx/rest.rst39
11 files changed, 578 insertions, 1264 deletions
diff --git a/doc/anastasis.texi b/doc/anastasis.texi
index c103f7a..d0f281a 100644
--- a/doc/anastasis.texi
+++ b/doc/anastasis.texi
@@ -21,7 +21,7 @@
@copying
@quotation
-GNU Anastasis 0.0.0, Jul 30, 2021
+Anastasis 0.0.0pre0, Aug 14, 2021
Anastasis SARL
@@ -50,21 +50,21 @@ Copyright @copyright{} 2020-2021 Anastasis SARL (AGPLv3+ or GFDL 1.3+)
@anchor{index doc}@anchor{0}
@c This file is part of GNU Anastasis.
@c Copyright (C) 2020-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
-GNU Anastasis is Free Software protocol and implementation that allows
+Anastasis is Free Software protocol and implementation that allows
users to securely deposit @strong{core secrets} with an open set of escrow
providers and to recover these secrets if their original copies are
lost.
@@ -93,245 +93,203 @@ problem to encrypting the @strong{core secret} using some other key
material in possession of the user.
@menu
-* Documentation Overview::
+* Documentation Overview::
@detailmenu
--- The Detailed Node Listing ---
Documentation Overview
-* Introduction::
-* Installation::
-* Configuration::
-* Cryptography::
-* REST API::
-* Reducer API::
-* Authentication Methods::
-* DB Schema::
-* Design Documents::
-* Anastasis licensing information::
-* Man Pages::
-* Complete Index::
-* GNU Free Documentation License::
+* Introduction::
+* Installation::
+* Configuration::
+* Cryptography::
+* REST API::
+* Reducer API::
+* Authentication Methods::
+* DB Schema::
+* Anastasis licensing information::
+* Man Pages::
+* Complete Index::
+* GNU Free Documentation License::
Introduction
-* User Identifiers::
-* Adversary models::
-* The recovery document::
+* User Identifiers::
+* Adversary models::
+* The recovery document::
Installation
-* Installing from source::
-* Installing Anastasis binary packages on Debian::
-* Installing Anastasis binary packages on Ubuntu::
+* Installing from source::
+* Installing Anastasis binary packages on Debian::
+* Installing Anastasis binary packages on Ubuntu::
Installing from source
-* Installing GNUnet::
-* Installing the Taler Exchange::
-* Installing the Taler Merchant::
-* Installing Anastasis::
-* Installing GNUnet-gtk::
-* Installing Anastasis-gtk::
+* Installing GNUnet::
+* Installing the Taler Exchange::
+* Installing the Taler Merchant::
+* Installing Anastasis::
+* Installing GNUnet-gtk::
+* Installing Anastasis-gtk::
Installing Anastasis binary packages on Debian
-* Installing the graphical front-end::
-* Installing the backend::
+* Installing the graphical front-end::
+* Installing the backend::
Installing Anastasis binary packages on Ubuntu
-* Installing the graphical front-end: Installing the graphical front-end<2>.
-* Installing the backend: Installing the backend<2>.
+* Installing the graphical front-end: Installing the graphical front-end<2>.
+* Installing the backend: Installing the backend<2>.
Configuration
-* Configuration format::
-* Using anastasis-config::
+* Configuration format::
+* Using anastasis-config::
Cryptography
-* Key derivations::
-* Key Usage::
-* Availability Considerations::
+* Key derivations::
+* Key Usage::
+* Availability Considerations::
Key derivations
-* Verification::
-* Encryption::
+* Verification::
+* Encryption::
Key Usage
-* Encryption: Encryption<2>.
-* Signatures::
+* Encryption: Encryption<2>.
+* Signatures::
REST API
-* HTTP Request and Response::
-* Protocol Version Ranges::
-* Common encodings::
+* HTTP Request and Response::
+* Protocol Version Ranges::
+* Common encodings::
Common encodings
-* Binary Data::
-* Hash codes::
-* Large numbers::
-* Timestamps::
-* Integers::
-* Objects::
-* Keys::
-* Signatures: Signatures<2>.
-* Amounts::
-* Time::
-* Cryptographic primitives::
-* Signatures: Signatures<3>.
-* Receiving Configuration::
-* Receiving Terms of Service::
-* Manage policy::
-* Managing truth::
+* Binary Data::
+* Hash codes::
+* Large numbers::
+* Timestamps::
+* Integers::
+* Objects::
+* Keys::
+* Signatures: Signatures<2>.
+* Amounts::
+* Time::
+* Cryptographic primitives::
+* Signatures: Signatures<3>.
+* Receiving Configuration::
+* Receiving Terms of Service::
+* Manage policy::
+* Managing truth::
Reducer API
-* States::
-* Backup Reducer::
-* Recovery Reducer::
-* Reducer transitions::
+* States::
+* Backup Reducer::
+* Recovery Reducer::
+* Reducer transitions::
Reducer transitions
-* Initial state::
-* Common transitions::
-* Backup transitions::
-* Recovery transitions::
+* Initial state::
+* Common transitions::
+* Backup transitions::
+* Recovery transitions::
Authentication Methods
-* SMS (sms): SMS sms.
-* Email verification (email): Email verification email.
-* Video identification (vid): Video identification vid.
-* Security question (qa): Security question qa.
-* Snail mail verification (post): Snail mail verification post.
-
-Design Documents
-
-* Design Doc 001; Anastasis User Experience: Design Doc 001 Anastasis User Experience.
-* Template::
-
-Design Doc 001: Anastasis User Experience
-
-* Summary::
-* Motivation::
-* Setup Steps::
-* Show Service Status After Setup::
-* Recovery Steps::
-
-Setup Steps
-
-* Entry point; Settings: Entry point Settings.
-* Providing Identification::
-* Add Authentication Methods::
-* Confirm/Change Service Providers::
-* Defining Recovery Options::
-* Pay for Setup::
-
-Recovery Steps
-
-* Entry point; Settings: Entry point Settings<2>.
-* Providing Identification: Providing Identification<2>.
-* Select Authentication Challenge::
-* Payment::
-* Enter Challenge Response::
-* Success::
-
-Template
-
-* Summary: Summary<2>.
-* Motivation: Motivation<2>.
-* Requirements::
-* Proposed Solution::
-* Alternatives::
-* Drawbacks::
-* Discussion / Q&A::
+* SMS (sms): SMS sms.
+* Email verification (email): Email verification email.
+* Video identification (vid): Video identification vid.
+* Security question (qa): Security question qa.
+* Snail mail verification (post): Snail mail verification post.
Anastasis licensing information
-* Anastasis (git;//git.taler.net/anastasis): Anastasis git //git taler net/anastasis.
-* Anastasis-gtk (git;//git.taler.net/anastasis-gtk): Anastasis-gtk git //git taler net/anastasis-gtk.
-* Documentation::
+* Anastasis (git;//git.taler.net/anastasis): Anastasis git //git taler net/anastasis.
+* Anastasis-gtk (git;//git.taler.net/anastasis-gtk): Anastasis-gtk git //git taler net/anastasis-gtk.
+* Documentation::
Anastasis (git://git.taler.net/anastasis)
-* Runtime dependencies::
+* Runtime dependencies::
Anastasis-gtk (git://git.taler.net/anastasis-gtk)
-* Runtime dependencies: Runtime dependencies<2>.
+* Runtime dependencies: Runtime dependencies<2>.
Man Pages
-* anastasis-config(1): anastasis-config 1.
-* anastasis-gtk(1): anastasis-gtk 1.
-* anastasis-httpd(1): anastasis-httpd 1.
-* anastasis-reducer(1): anastasis-reducer 1.
-* anastasis.conf(5): anastasis conf 5.
+* anastasis-config(1): anastasis-config 1.
+* anastasis-gtk(1): anastasis-gtk 1.
+* anastasis-httpd(1): anastasis-httpd 1.
+* anastasis-reducer(1): anastasis-reducer 1.
+* anastasis.conf(5): anastasis conf 5.
anastasis-config(1)
-* Synopsis::
-* Description::
-* See Also::
-* Bugs::
+* Synopsis::
+* Description::
+* See Also::
+* Bugs::
anastasis-gtk(1)
-* Synopsis: Synopsis<2>.
-* Description: Description<2>.
-* See Also: See Also<2>.
-* Bugs: Bugs<2>.
+* Synopsis: Synopsis<2>.
+* Description: Description<2>.
+* See Also: See Also<2>.
+* Bugs: Bugs<2>.
anastasis-httpd(1)
-* Synopsis: Synopsis<3>.
-* Description: Description<3>.
-* Signals::
-* See also::
-* Bugs: Bugs<3>.
+* Synopsis: Synopsis<3>.
+* Description: Description<3>.
+* Signals::
+* See also::
+* Bugs: Bugs<3>.
anastasis-reducer(1)
-* Synopsis: Synopsis<4>.
-* Description: Description<4>.
-* See Also: See Also<3>.
-* Bugs: Bugs<4>.
+* Synopsis: Synopsis<4>.
+* Description: Description<4>.
+* See Also: See Also<3>.
+* Bugs: Bugs<4>.
anastasis.conf(5)
-* Description: Description<5>.
-* SEE ALSO::
-* BUGS::
+* Description: Description<5>.
+* SEE ALSO::
+* BUGS::
Description
-* GLOBAL OPTIONS::
-* Authorization options::
-* Postgres database configuration::
+* GLOBAL OPTIONS::
+* Authorization options::
+* Postgres database configuration::
GNU Free Documentation License
-* 0. PREAMBLE: 0 PREAMBLE.
-* 1. APPLICABILITY AND DEFINITIONS: 1 APPLICABILITY AND DEFINITIONS.
-* 2. VERBATIM COPYING: 2 VERBATIM COPYING.
-* 3. COPYING IN QUANTITY: 3 COPYING IN QUANTITY.
-* 4. MODIFICATIONS: 4 MODIFICATIONS.
-* 5. COMBINING DOCUMENTS: 5 COMBINING DOCUMENTS.
-* 6. COLLECTIONS OF DOCUMENTS: 6 COLLECTIONS OF DOCUMENTS.
-* 7. AGGREGATION WITH INDEPENDENT WORKS: 7 AGGREGATION WITH INDEPENDENT WORKS.
-* 8. TRANSLATION: 8 TRANSLATION.
-* 9. TERMINATION: 9 TERMINATION.
-* 10. FUTURE REVISIONS OF THIS LICENSE: 10 FUTURE REVISIONS OF THIS LICENSE.
-* 11. RELICENSING: 11 RELICENSING.
-* ADDENDUM; How to use this License for your documents: ADDENDUM How to use this License for your documents.
+* 0. PREAMBLE: 0 PREAMBLE.
+* 1. APPLICABILITY AND DEFINITIONS: 1 APPLICABILITY AND DEFINITIONS.
+* 2. VERBATIM COPYING: 2 VERBATIM COPYING.
+* 3. COPYING IN QUANTITY: 3 COPYING IN QUANTITY.
+* 4. MODIFICATIONS: 4 MODIFICATIONS.
+* 5. COMBINING DOCUMENTS: 5 COMBINING DOCUMENTS.
+* 6. COLLECTIONS OF DOCUMENTS: 6 COLLECTIONS OF DOCUMENTS.
+* 7. AGGREGATION WITH INDEPENDENT WORKS: 7 AGGREGATION WITH INDEPENDENT WORKS.
+* 8. TRANSLATION: 8 TRANSLATION.
+* 9. TERMINATION: 9 TERMINATION.
+* 10. FUTURE REVISIONS OF THIS LICENSE: 10 FUTURE REVISIONS OF THIS LICENSE.
+* 11. RELICENSING: 11 RELICENSING.
+* ADDENDUM; How to use this License for your documents: ADDENDUM How to use this License for your documents.
@end detailmenu
@end menu
@@ -343,36 +301,35 @@ GNU Free Documentation License
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@menu
-* Introduction::
-* Installation::
-* Configuration::
-* Cryptography::
-* REST API::
-* Reducer API::
-* Authentication Methods::
-* DB Schema::
-* Design Documents::
-* Anastasis licensing information::
-* Man Pages::
-* Complete Index::
-* GNU Free Documentation License::
+* Introduction::
+* Installation::
+* Configuration::
+* Cryptography::
+* REST API::
+* Reducer API::
+* Authentication Methods::
+* DB Schema::
+* Anastasis licensing information::
+* Man Pages::
+* Complete Index::
+* GNU Free Documentation License::
@end menu
@@ -386,9 +343,9 @@ concepts: user identifiers, our adversary model and the role of the
recovery document.
@menu
-* User Identifiers::
-* Adversary models::
-* The recovery document::
+* User Identifiers::
+* Adversary models::
+* The recovery document::
@end menu
@@ -424,46 +381,46 @@ to recover their core secret.
@subsection The recovery document
-A @strong{recovery document} includes all of the information a user
-needs to recover access to their core secret. It specifies a set of
-@strong{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 @strong{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 @strong{recovery document}
-also specifies @strong{policies}, which describe the combination(s) of
-the escrow methods that suffice to obtain access to the core secret.
-For example, a @strong{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
-@strong{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 @strong{recovery document}
-(except for its length, which may be exposed to an adversary which
-monitors the user’s network traffic).
+A @strong{recovery document} includes all of the information a user needs
+to recover access to their core secret. It specifies a set of
+@strong{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 @strong{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 @strong{recovery document} also
+specifies @strong{policies}, which describe the combination(s) of the
+escrow methods that suffice to obtain access to the core secret. For
+example, a @strong{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 @strong{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 @strong{recovery document} (except for its
+length, which may be exposed to an adversary which monitors the user’s
+network traffic).
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@@ -479,43 +436,43 @@ exchange compilation.
@itemize -
-@item
+@item
libsqlite3 >= 3.16.2
-@item
+@item
GNU libunistring >= 0.9.3
-@item
+@item
libcurl >= 7.26 (or libgnurl >= 7.26)
-@item
+@item
libqrencode >= 4.0.0
-@item
+@item
GNU libgcrypt >= 1.6
-@item
+@item
libsodium >= 1.0
-@item
+@item
libargon2 >= 20171227
-@item
+@item
libjansson >= 2.7
-@item
+@item
Postgres >= 9.6, including libpq
-@item
+@item
GNU libmicrohttpd >= 0.9.71
-@item
+@item
GNUnet >= 0.14.0 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/})
-@item
+@item
GNU Taler exchange
-@item
+@item
GNU Taler merchant backend
@end itemize
@@ -523,9 +480,9 @@ Except for the last two, these are available in most GNU/Linux distributions
and should just be installed using the respective package manager.
@menu
-* Installing from source::
-* Installing Anastasis binary packages on Debian::
-* Installing Anastasis binary packages on Ubuntu::
+* Installing from source::
+* Installing Anastasis binary packages on Debian::
+* Installing Anastasis binary packages on Ubuntu::
@end menu
@@ -538,12 +495,12 @@ The following instructions will show how to install libgnunetutil and
the GNU Taler exchange from source.
@menu
-* Installing GNUnet::
-* Installing the Taler Exchange::
-* Installing the Taler Merchant::
-* Installing Anastasis::
-* Installing GNUnet-gtk::
-* Installing Anastasis-gtk::
+* Installing GNUnet::
+* Installing the Taler Exchange::
+* Installing the Taler Merchant::
+* Installing Anastasis::
+* Installing GNUnet-gtk::
+* Installing Anastasis-gtk::
@end menu
@@ -606,7 +563,7 @@ GNU Taler merchant has these additional dependencies:
@itemize -
-@item
+@item
libqrencode >= 4.0.0
@end itemize
@@ -807,7 +764,7 @@ into your keyring and update the package lists:
@end example
@cartouche
-@quotation Note
+@quotation Note
You may want to verify the correctness of the Taler Systems key out-of-band.
@end quotation
@end cartouche
@@ -816,8 +773,8 @@ Now your system is ready to install the official GNU Taler binary packages
using apt.
@menu
-* Installing the graphical front-end::
-* Installing the backend::
+* Installing the graphical front-end::
+* Installing the backend::
@end menu
@@ -898,7 +855,7 @@ into your keyring and update the package lists:
@end example
@cartouche
-@quotation Note
+@quotation Note
You may want to verify the correctness of the Taler Systems key out-of-band.
@end quotation
@end cartouche
@@ -907,8 +864,8 @@ Now your system is ready to install the official GNU Taler binary packages
using apt.
@menu
-* Installing the graphical front-end: Installing the graphical front-end<2>.
-* Installing the backend: Installing the backend<2>.
+* Installing the graphical front-end: Installing the graphical front-end<2>.
+* Installing the backend: Installing the backend<2>.
@end menu
@@ -959,18 +916,18 @@ need to install a Taler merchant backend via:
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@@ -985,8 +942,8 @@ the @code{anastasis.conf(5)} chapter. This chapter only describes the
configuration format.
@menu
-* Configuration format::
-* Using anastasis-config::
+* Configuration format::
+* Using anastasis-config::
@end menu
@@ -1120,18 +1077,18 @@ option.
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@@ -1177,9 +1134,9 @@ user to recover the master key. A @strong{recovery document} contains the
encrypted @strong{core secret}, a set of escrow methods and a set of policies.
@menu
-* Key derivations::
-* Key Usage::
-* Availability Considerations::
+* Key derivations::
+* Key Usage::
+* Availability Considerations::
@end menu
@@ -1221,8 +1178,8 @@ kdf_id := Argon2( identifier, server_salt, keysize )
@strong{keysize}: The desired output size of the KDF, here 32 bytes.
@menu
-* Verification::
-* Encryption::
+* Verification::
+* Encryption::
@end menu
@@ -1310,8 +1267,8 @@ The keys we have generated are then used to encrypt the @strong{recovery documen
the @strong{key_share} of the user.
@menu
-* Encryption: Encryption<2>.
-* Signatures::
+* Encryption: Encryption<2>.
+* Signatures::
@end menu
@@ -1437,18 +1394,18 @@ capacity.
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@@ -1459,26 +1416,26 @@ capacity.
@c This file is part of Anastasis
-@c
+@c
@c Copyright (C) 2014-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@menu
-* HTTP Request and Response::
-* Protocol Version Ranges::
-* Common encodings::
+* HTTP Request and Response::
+* Protocol Version Ranges::
+* Common encodings::
@end menu
@@ -1501,22 +1458,22 @@ handle the error as if an internal error (500) had been returned.
Unless specified otherwise, HTTP requests that carry a message body must
have the content type @code{application/json}.
-@*Request Headers:
+@*Request Headers:
@itemize *
-@item
+@item
Content-Type@footnote{https://tools.ietf.org/html/rfc7231#section-3.1.1.5} – application/json
@end itemize
@strong{Response:}
-@*Response Headers:
+@*Response Headers:
@itemize *
-@item
+@item
Content-Type@footnote{https://tools.ietf.org/html/rfc7231#section-3.1.1.5} – application/json
@end itemize
@@ -1579,19 +1536,19 @@ down in the libtool version format@footnote{https://www.gnu.org/software/libtool
A protocol version is a positive, non-zero integer. A protocol version range consists of three components:
-@enumerate
+@enumerate
-@item
+@item
The @code{current} version. This is the latest version of the protocol supported by the client or service.
-@item
+@item
The @code{revision} number. This value should usually not be interpreted by the client/server, but serves
purely as a comment. Each time a service/client for a protocol is updated while supporting the same
set of protocol versions, the revision should be increased.
In rare cases, the revision number can be used to work around unintended breakage in deployed
versions of a service. This is discouraged and should only be used in exceptional situations.
-@item
+@item
The @code{age} number. This non-zero integer identifies with how many previous protocol versions this
implementation is compatible. An @code{age} of 0 implies that the implementation only supports
the @code{current} protocol version. The @code{age} must be less or equal than the @code{current} protocol version.
@@ -1610,27 +1567,27 @@ Examples:
@itemize *
-@item
+@item
“1” and “1” are compatible
-@item
+@item
“1” and “2” are @strong{incompatible}
-@item
+@item
“2:0:1” and “1:0:0” are compatible
-@item
+@item
“2:5:1” and “1:10:0” are compatible
-@item
+@item
“4:0:1” and “2:0:0” are @strong{incompatible}
-@item
+@item
“4:0:1” and “3:0:0” are compatible
@end itemize
@cartouche
-@quotation Note
+@quotation Note
Semantic versions@footnote{https://semver.org/} are not a good tool for this job, as we concisely want to express
that the client/server supports the last @code{n} versions of the protocol.
Semantic versions don’t support this, and semantic version ranges are too complex for this.
@@ -1638,14 +1595,14 @@ Semantic versions don’t support this, and semantic version ranges are too comp
@end cartouche
@cartouche
-@quotation Warning
+@quotation Warning
A client doesn’t have one single protocol version range. Instead, it has
a protocol version range for each type of service it talks to.
@end quotation
@end cartouche
@cartouche
-@quotation Warning
+@quotation Warning
For privacy reasons, the protocol version range of a client should not be
sent to the service. Instead, the client should just use the two version ranges
to decide whether it will talk to the service.
@@ -1660,22 +1617,22 @@ to decide whether it will talk to the service.
This section describes how certain types of values are represented throughout the API.
@menu
-* Binary Data::
-* Hash codes::
-* Large numbers::
-* Timestamps::
-* Integers::
-* Objects::
-* Keys::
-* Signatures: Signatures<2>.
-* Amounts::
-* Time::
-* Cryptographic primitives::
-* Signatures: Signatures<3>.
-* Receiving Configuration::
-* Receiving Terms of Service::
-* Manage policy::
-* Managing truth::
+* Binary Data::
+* Hash codes::
+* Large numbers::
+* Timestamps::
+* Integers::
+* Objects::
+* Keys::
+* Signatures: Signatures<2>.
+* Amounts::
+* Time::
+* Cryptographic primitives::
+* Signatures: Signatures<3>.
+* Receiving Configuration::
+* Receiving Terms of Service::
+* Manage policy::
+* Managing truth::
@end menu
@@ -1811,21 +1768,21 @@ this allows accurate representation of monetary amounts.
The following constrains apply for a valid amount:
-@enumerate
+@enumerate
-@item
+@item
The @code{<Currency>} part must be at most 11 characters long and may only consist
of ASCII letters (@code{a-zA-Z}).
-@item
+@item
The integer part of @code{<DecimalAmount>} may be at most 2^52.
-@item
+@item
The fractional part of @code{<DecimalAmount>} may contain at most 8 decimal digits.
@end enumerate
@cartouche
-@quotation Note
+@quotation Note
“EUR:1.50” and “EUR:10” are valid amounts. These are all invalid amounts: “A:B:1.5”, “EUR:4503599627370501.0”, “EUR:1.”, “EUR:.1”.
@end quotation
@end cartouche
@@ -2037,10 +1994,10 @@ plaintext is expected to contain:
@itemize *
-@item
+@item
the escrow policy
-@item
+@item
the separately encrypted master public key
@end itemize
@@ -2111,11 +2068,11 @@ minimum and maximum size limits.
@strong{Request}:
-@*Query Parameters:
+@*Query Parameters:
@itemize *
-@item
+@item
@code{storage_duration=YEARS} – For how many years from now would the client like us to
store the recovery document? Defaults to 0 (that is, do
not extend / prolong existing storage contract).
@@ -2127,7 +2084,7 @@ may attempt to upload the latest backup again, as this
option will be checked before the @code{304 Not modified}
case.
-@item
+@item
@code{timeout_ms=NUMBER} – @emph{Optional.} If specified, the Anastasis server will
wait up to @code{timeout_ms} milliseconds for completion of the payment before
sending the HTTP response. A client must never rely on this behavior, as the
@@ -2273,6 +2230,7 @@ interface DecryptionPolicy @{
@anchor{rest managing-truth}@anchor{51}@anchor{rest truth}@anchor{52}
@subsubsection 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
@@ -2280,8 +2238,8 @@ 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 @strong{truth} or
-request a (encrypted) @strong{key share} with the escrow provider.
+This API is used by the Anastasis client to deposit @strong{truth} or request a (encrypted) @strong{key share} with
+the escrow provider.
An @strong{escrow method} specifies an Anastasis provider and how the user should
authorize themself. The @strong{truth} API allows the user to provide the
@@ -2299,11 +2257,11 @@ If request has been seen before, the server should do nothing, and otherwise sto
@strong{Request:}
-@*Query Parameters:
+@*Query Parameters:
@itemize *
-@item
+@item
@code{timeout_ms=NUMBER} – @emph{Optional.} If specified, the Anastasis server will
wait up to @code{timeout_ms} milliseconds for completion of the payment before
sending the HTTP response. A client must never rely on this behavior, as the
@@ -2373,15 +2331,33 @@ interface TruthUploadRequest @{
@end example
@end deffn
-@anchor{rest get--truth-$UUID[?response=$H_RESPONSE]}@anchor{55}
-@deffn {HTTP Get} GET /truth/$UUID[?response=$H_RESPONSE]
+@anchor{rest get--truth-$UUID}@anchor{55}
+@deffn {HTTP Get} GET /truth/$UUID
-Get the stored encrypted key share. If @code{$H_RESPONSE} is specified by the client, the server checks
-if @code{$H_RESPONSE} matches the expected response specified before within the @ref{54,,TruthUploadRequest} (see @code{encrypted_truth}).
+Get the stored encrypted key share.
Also, the user has to provide the correct @emph{truth_encryption_key} with every get request (see below).
-When @code{$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 Parameters:
+
+@itemize *
+
+@item
+@code{response=H_RESPONSE} – @emph{Optional.} If @code{$H_RESPONSE} is specified by the client,
+the server checks if @code{$H_RESPONSE} matches the expected response. This can be the
+hash of the security question (as specified before by the client
+within the @ref{54,,TruthUploadRequest} (see @code{encrypted_truth})), or the hash of the
+PIN code sent via SMS, E-mail or postal communication channels.
+When @code{$H_RESPONSE} is correct, the server responds with the encrypted key share.
+
+@item
+@code{timeout_ms=NUMBER} – @emph{Optional.} If specified, the Anastasis server will
+wait up to @code{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.
+@end itemize
+
+
@strong{Response}:
@@ -2422,6 +2398,12 @@ The server requires a valid “response” to the challenge associated with the
The server does not know any truth under the given UUID.
+@item 408 Request Timeout@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9}:
+
+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.
+
@item 410 Gone@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11}:
The server has not (recently) issued a challenge under the given UUID,
@@ -2482,18 +2464,18 @@ interface KeyShare @{
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@@ -2572,10 +2554,10 @@ above would look like following for the transition @ref{5b,,action} @code{select
@end example
@menu
-* States::
-* Backup Reducer::
-* Recovery Reducer::
-* Reducer transitions::
+* States::
+* Backup Reducer::
+* Recovery Reducer::
+* Reducer transitions::
@end menu
@@ -2591,7 +2573,7 @@ Overall, the reducer knows the following states:
@itemize -
-@item
+@item
@table @asis
@@ -2600,7 +2582,7 @@ Overall, the reducer knows the following states:
this state, but the client may want to continue from a previous state.
@end table
-@item
+@item
@table @asis
@@ -2609,7 +2591,7 @@ this state, but the client may want to continue from a previous state.
so that we can show a list of countries to choose from.
@end table
-@item
+@item
@table @asis
@@ -2619,7 +2601,7 @@ so that we can determine appropriate attributes, currencies and Anastasis
providers.
@end table
-@item
+@item
@table @asis
@@ -2628,7 +2610,7 @@ providers.
attributes.
@end table
-@item
+@item
@table @asis
@@ -2637,13 +2619,13 @@ attributes.
during recovery.
@end table
-@item
+@item
@strong{POLICIES_REVIEWING}: The user should review the recovery policies.
-@item
+@item
@strong{SECRET_EDITING}: The user should edit the secret to be backed up.
-@item
+@item
@table @asis
@@ -2652,13 +2634,13 @@ during recovery.
with an authentication method.
@end table
-@item
+@item
@strong{POLICIES_PAYING}: The user needs to pay for storing the recovery policy document.
-@item
+@item
@strong{BACKUP_FINISHED}: A backup has been successfully generated.
-@item
+@item
@table @asis
@@ -2667,7 +2649,7 @@ with an authentication method.
the secret that is to be recovered.
@end table
-@item
+@item
@table @asis
@@ -2676,13 +2658,13 @@ the secret that is to be recovered.
proceed with recovery.
@end table
-@item
+@item
@strong{CHALLENGE_PAYING}: The user needs to pay to proceed with the authorization challenge.
-@item
+@item
@strong{CHALLENGE_SOLVING}: The user needs to solve the authorization challenge.
-@item
+@item
@strong{RECOVERY_FINISHED}: The secret of the user has been recovered.
@end itemize
@end quotation
@@ -2694,22 +2676,22 @@ State names:
@itemize -
-@item
+@item
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).
-@item
+@item
In COLLECTING-states, the user has to give certain values.
-@item
+@item
In EDITING-states, the user is free to choose which values he wants to give.
-@item
+@item
In REVEIWING-states, the user may make a few choices, but primarily is expected to affirm something.
-@item
+@item
in PAYING-states, the user must make a payment.
-@item
+@item
in FINISHED-states, the operation has definitively concluded.
@end itemize
@end quotation
@@ -2760,10 +2742,10 @@ Note that we only show fields added by the reducer, typically the previous
state is preserved to enable “back” transitions to function smoothly.
@menu
-* Initial state::
-* Common transitions::
-* Backup transitions::
-* Recovery transitions::
+* Initial state::
+* Common transitions::
+* Backup transitions::
+* Recovery transitions::
@end menu
@@ -3032,43 +3014,43 @@ that must be provided includes:
@itemize -
-@item
+@item
@strong{type}: The type of the attribute, for now only @code{string} and @code{date} are
supported.
-@item
+@item
@strong{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.
-@item
+@item
@strong{label}: A human-readable description of the attribute in English.
Translated descriptions may be provided under @strong{label_i18n}.
-@item
+@item
@strong{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 @strong{name},
only the @strong{uuid} will be identical if the semantics is identical.
-@item
+@item
@strong{widget}: An optional name of a widget that is known to nicely render
the attribute entry in user interfaces where named widgets are
supported.
-@item
+@item
@strong{validation-regex}: An optional extended POSIX regular expression
that is to be used to validate (string) inputs to ensure they are
well-formed.
-@item
+@item
@strong{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).
-@item
+@item
@strong{optional}: Optional boolean field that, if @code{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
@@ -3086,39 +3068,39 @@ information is provided if the provider was successfully contacted:
@itemize -
-@item
+@item
@strong{http_status}: HTTP status code, always @code{200} on success.
-@item
+@item
@strong{methods}: Array of authentication methods supported by this
provider. Includes the @strong{type} of the authentication method
and the @strong{usage_fee} (how much the user must pay for authorization
using this method during recovery).
-@item
+@item
@strong{annual_fee}: Fee the provider charges to store the recovery
policy for one year.
-@item
+@item
@strong{truth_upload_fee}: Fee the provider charges to store a key share.
-@item
+@item
@strong{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.
-@item
+@item
@strong{currency}: Currency in which the provider wants to be paid,
will match all of the fees.
-@item
+@item
@strong{storage_limit_in_megabytes}: Maximum size of an upload (for
both recovery document and truth data) in megabytes.
-@item
+@item
@strong{provider_name}: Human-readable name of the provider’s business.
-@item
+@item
@strong{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
@@ -3133,11 +3115,11 @@ If contacting the provider failed, the information returned is:
@itemize -
-@item
+@item
@strong{http_status}: HTTP status code (if available, possibly 0 if
we did not even obtain an HTTP response).
-@item
+@item
@strong{error_code}: Taler error code, never 0.
@end itemize
@end quotation
@@ -3838,6 +3820,16 @@ Example results are thus:
@example
@{
"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 @}
+ @}
+ @}
@}
@end example
@@ -3880,13 +3872,13 @@ Here, the fields have the following meaning:
@itemize -
-@item
+@item
@strong{http_status} is the HTTP status returned by the Anastasis provider.
-@item
+@item
@strong{upload_status} is the Taler error code return by the provider.
-@item
+@item
@strong{provider_url} is the base URL of the failing provider.
@end itemize
@end quotation
@@ -3977,21 +3969,21 @@ four mandatory fields:
@itemize -
-@item
+@item
@strong{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.
-@item
+@item
@strong{cost}: This is the amount the Anastasis provider will charge
to allow the user to pass the challenge.
-@item
+@item
@strong{type}: This is the type of the challenge, as a string.
-@item
+@item
@strong{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
@@ -4102,7 +4094,7 @@ that applications must all handle. States other than @code{solved} are:
@itemize -
-@item
+@item
@strong{payment}: Here, the user must pay for a challenge. An example would be:
@example
@@ -4126,7 +4118,7 @@ that applications must all handle. States other than @code{solved} are:
@itemize -
-@item
+@item
@strong{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
@@ -4150,7 +4142,7 @@ help parse the details.
@}
@end example
-@item
+@item
@strong{hint}: Here, the server provided human-readable hint for
how to solve the challenge. Note that the @code{hint} provided this
time is from the Anastasis provider and may differ from the @code{instructions}
@@ -4173,7 +4165,7 @@ for the challenge under @code{recovery_information}:
@}
@end example
-@item
+@item
@strong{details}: Here, the server provided a detailed JSON status response
related to solving the challenge:
@@ -4204,7 +4196,7 @@ related to solving the challenge:
@itemize -
-@item
+@item
@strong{redirect}: To solve the challenge, the user must visit the indicated
Web site at @code{redirect_url}, for example to perform video authentication:
@end itemize
@@ -4231,7 +4223,7 @@ Web site at @code{redirect_url}, for example to perform video authentication:
@itemize -
-@item
+@item
@strong{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
@@ -4259,7 +4251,7 @@ the failure. The user may try again later or continue with other challenges.
@itemize -
-@item
+@item
@strong{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.
@@ -4284,7 +4276,7 @@ interfaces should not allow users to re-try this challenge.
@itemize -
-@item
+@item
@strong{rate-limit-exceeded}:
@end itemize
@@ -4355,18 +4347,18 @@ formats are:
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
@@ -4391,11 +4383,11 @@ succeed with a 50% probability after about 200000 years of attempts at the
maximum permissible frequency.
@menu
-* SMS (sms): SMS sms.
-* Email verification (email): Email verification email.
-* Video identification (vid): Video identification vid.
-* Security question (qa): Security question qa.
-* Snail mail verification (post): Snail mail verification post.
+* SMS (sms): SMS sms.
+* Email verification (email): Email verification email.
+* Video identification (vid): Video identification vid.
+* Security question (qa): Security question qa.
+* Snail mail verification (post): Snail mail verification post.
@end menu
@@ -4475,23 +4467,23 @@ the server responds with the requested encrypted key share.
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
-@c
+@c
@c Anastasis is free software; you can redistribute it and/or modify it under the
@c terms of the GNU Affero General Public License as published by the Free Software
@c Foundation; either version 2.1, or (at your option) any later version.
-@c
+@c
@c Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
-@c
+@c
@c You should have received a copy of the GNU Affero General Public License along with
@c Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-@c
+@c
@c @author Christian Grothoff
@c @author Dominik Meister
@c @author Dennis Neufeld
-@node DB Schema,Design Documents,Authentication Methods,Documentation Overview
+@node DB Schema,Anastasis licensing information,Authentication Methods,Documentation Overview
@anchor{db doc}@anchor{6c}@anchor{db db-schema}@anchor{6d}
@section DB Schema
@@ -4506,350 +4498,8 @@ the server responds with the requested encrypted key share.
@image{anastasis-figures/anastasis_truth_payment,,,,png}
-@node Design Documents,Anastasis licensing information,DB Schema,Documentation Overview
-@anchor{design-documents/index doc}@anchor{6e}@anchor{design-documents/index design-documents}@anchor{6f}
-@section 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.
-
-@menu
-* Design Doc 001; Anastasis User Experience: Design Doc 001 Anastasis User Experience.
-* Template::
-
-@end menu
-
-@node Design Doc 001 Anastasis User Experience,Template,,Design Documents
-@anchor{design-documents/001-anastasis-ux doc}@anchor{70}@anchor{design-documents/001-anastasis-ux design-doc-001-anastasis-user-experience}@anchor{71}
-@subsection Design Doc 001: Anastasis User Experience
-
-
-@menu
-* Summary::
-* Motivation::
-* Setup Steps::
-* Show Service Status After Setup::
-* Recovery Steps::
-
-@end menu
-
-@node Summary,Motivation,,Design Doc 001 Anastasis User Experience
-@anchor{design-documents/001-anastasis-ux summary}@anchor{72}
-@subsubsection Summary
-
-
-This document describes the recommended way of implementing the user experience
-of setting up and making use of @ref{3,,Introduction} account recovery.
-
-@node Motivation,Setup Steps,Summary,Design Doc 001 Anastasis User Experience
-@anchor{design-documents/001-anastasis-ux motivation}@anchor{73}
-@subsubsection 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.
-
-@node Setup Steps,Show Service Status After Setup,Motivation,Design Doc 001 Anastasis User Experience
-@anchor{design-documents/001-anastasis-ux setup-steps}@anchor{74}
-@subsubsection Setup Steps
-
-@image{graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a,,,[graphviz],png}
-
-@menu
-* Entry point; Settings: Entry point Settings.
-* Providing Identification::
-* Add Authentication Methods::
-* Confirm/Change Service Providers::
-* Defining Recovery Options::
-* Pay for Setup::
-
-@end menu
-
-@node Entry point Settings,Providing Identification,,Setup Steps
-@anchor{design-documents/001-anastasis-ux entry-point-settings}@anchor{75}
-@subsubsection 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{anastasis-figures/menu,,,,png}
-
-@image{anastasis-figures/settings,,,,png}
-
-@image{anastasis-figures/backupsettings,,,,png}
-
-@node Providing Identification,Add Authentication Methods,Entry point Settings,Setup Steps
-@anchor{design-documents/001-anastasis-ux providing-identification}@anchor{76}
-@subsubsection 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{anastasis-figures/userid,,,,png}
-
-@node Add Authentication Methods,Confirm/Change Service Providers,Providing Identification,Setup Steps
-@anchor{design-documents/001-anastasis-ux add-authentication-methods}@anchor{77}
-@subsubsection Add Authentication Methods
-
-
-After creating a unique identifier, the user can chose one or more
-@ref{65,,Authentication 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{anastasis-figures/truth,,,,png}
-
-@image{anastasis-figures/addtruth,,,,png}
-
-@image{anastasis-figures/addtruthmail,,,,png}
-
-@node Confirm/Change Service Providers,Defining Recovery Options,Add Authentication Methods,Setup Steps
-@anchor{design-documents/001-anastasis-ux confirm-change-service-providers}@anchor{78}
-@subsubsection 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{anastasis-figures/policy,,,,png}
-
-@image{anastasis-figures/addpolicy,,,,png}
-
-@image{anastasis-figures/addpolicymethod,,,,png}
-
-@node Defining Recovery Options,Pay for Setup,Confirm/Change Service Providers,Setup Steps
-@anchor{design-documents/001-anastasis-ux defining-recovery-options}@anchor{79}
-@subsubsection 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 @code{n} the default could
-be @code{n-1} out of @code{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.
-
-@node Pay for Setup,,Defining Recovery Options,Setup Steps
-@anchor{design-documents/001-anastasis-ux pay-for-setup}@anchor{7a}
-@subsubsection 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.
-
-@node Show Service Status After Setup,Recovery Steps,Setup Steps,Design Doc 001 Anastasis User Experience
-@anchor{design-documents/001-anastasis-ux show-service-status-after-setup}@anchor{7b}
-@subsubsection Show Service Status After Setup
-
-
-TODO
-
-@node Recovery Steps,,Show Service Status After Setup,Design Doc 001 Anastasis User Experience
-@anchor{design-documents/001-anastasis-ux recovery-steps}@anchor{7c}
-@subsubsection Recovery Steps
-
-@image{graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84,,,[graphviz],png}
-
-@menu
-* Entry point; Settings: Entry point Settings<2>.
-* Providing Identification: Providing Identification<2>.
-* Select Authentication Challenge::
-* Payment::
-* Enter Challenge Response::
-* Success::
-
-@end menu
-
-@node Entry point Settings<2>,Providing Identification<2>,,Recovery Steps
-@anchor{design-documents/001-anastasis-ux id1}@anchor{7d}
-@subsubsection 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{anastasis-figures/menu,,,,png}
-
-@image{anastasis-figures/settings,,,,png}
-
-@image{anastasis-figures/backupsettings,,,,png}
-
-@node Providing Identification<2>,Select Authentication Challenge,Entry point Settings<2>,Recovery Steps
-@anchor{design-documents/001-anastasis-ux id2}@anchor{7e}
-@subsubsection 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{anastasis-figures/userid,,,,png}
-
-@node Select Authentication Challenge,Payment,Providing Identification<2>,Recovery Steps
-@anchor{design-documents/001-anastasis-ux select-authentication-challenge}@anchor{7f}
-@subsubsection 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.
-
-@node Payment,Enter Challenge Response,Select Authentication Challenge,Recovery Steps
-@anchor{design-documents/001-anastasis-ux payment}@anchor{80}
-@subsubsection 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 @code{Ok} button, text showing the amount due and @code{Pay} should be
-used – except of course if the security question challenge is free of
-charge).
-
-@node Enter Challenge Response,Success,Payment,Recovery Steps
-@anchor{design-documents/001-anastasis-ux enter-challenge-response}@anchor{81}
-@subsubsection 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 @code{A-}. However, the user should be able to enter both only the
-numeric code, or the full code with the @code{A-} prefix (or ideally, the user
-cannot delete the pre-filled @code{A-} text).
-
-@node Success,,Enter Challenge Response,Recovery Steps
-@anchor{design-documents/001-anastasis-ux success}@anchor{82}
-@subsubsection 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.
-
-@node Template,,Design Doc 001 Anastasis User Experience,Design Documents
-@anchor{design-documents/999-template doc}@anchor{83}@anchor{design-documents/999-template template}@anchor{84}
-@subsection Template
-
-
-@menu
-* Summary: Summary<2>.
-* Motivation: Motivation<2>.
-* Requirements::
-* Proposed Solution::
-* Alternatives::
-* Drawbacks::
-* Discussion / Q&A::
-
-@end menu
-
-@node Summary<2>,Motivation<2>,,Template
-@anchor{design-documents/999-template summary}@anchor{85}
-@subsubsection Summary
-
-
-@node Motivation<2>,Requirements,Summary<2>,Template
-@anchor{design-documents/999-template motivation}@anchor{86}
-@subsubsection Motivation
-
-
-@node Requirements,Proposed Solution,Motivation<2>,Template
-@anchor{design-documents/999-template requirements}@anchor{87}
-@subsubsection Requirements
-
-
-@node Proposed Solution,Alternatives,Requirements,Template
-@anchor{design-documents/999-template proposed-solution}@anchor{88}
-@subsubsection Proposed Solution
-
-
-@node Alternatives,Drawbacks,Proposed Solution,Template
-@anchor{design-documents/999-template alternatives}@anchor{89}
-@subsubsection Alternatives
-
-
-@node Drawbacks,Discussion / Q&A,Alternatives,Template
-@anchor{design-documents/999-template drawbacks}@anchor{8a}
-@subsubsection Drawbacks
-
-
-@node Discussion / Q&A,,Drawbacks,Template
-@anchor{design-documents/999-template discussion-q-a}@anchor{8b}
-@subsubsection Discussion / Q&A
-
-
-(This should be filled in with results from discussions on mailing lists / personal communication.)
-
-@node Anastasis licensing information,Man Pages,Design Documents,Documentation Overview
-@anchor{global-licensing doc}@anchor{8c}@anchor{global-licensing anastasis-licensing-information}@anchor{8d}
+@node Anastasis licensing information,Man Pages,DB Schema,Documentation Overview
+@anchor{global-licensing doc}@anchor{6e}@anchor{global-licensing anastasis-licensing-information}@anchor{6f}
@section Anastasis licensing information
@@ -4864,26 +4514,26 @@ All Anastasis components are generally released under the Affero
GPL.
@menu
-* Anastasis (git;//git.taler.net/anastasis): Anastasis git //git taler net/anastasis.
-* Anastasis-gtk (git;//git.taler.net/anastasis-gtk): Anastasis-gtk git //git taler net/anastasis-gtk.
-* Documentation::
+* Anastasis (git;//git.taler.net/anastasis): Anastasis git //git taler net/anastasis.
+* Anastasis-gtk (git;//git.taler.net/anastasis-gtk): Anastasis-gtk git //git taler net/anastasis-gtk.
+* Documentation::
@end menu
@node Anastasis git //git taler net/anastasis,Anastasis-gtk git //git taler net/anastasis-gtk,,Anastasis licensing information
-@anchor{global-licensing anastasis-git-git-taler-net-anastasis}@anchor{8e}@anchor{global-licensing exchange-repo}@anchor{8f}
+@anchor{global-licensing anastasis-git-git-taler-net-anastasis}@anchor{70}@anchor{global-licensing exchange-repo}@anchor{71}
@subsection Anastasis (git://git.taler.net/anastasis)
Anastasis core logic is under AGPL.
@menu
-* Runtime dependencies::
+* Runtime dependencies::
@end menu
@node Runtime dependencies,,,Anastasis git //git taler net/anastasis
-@anchor{global-licensing runtime-dependencies}@anchor{90}
+@anchor{global-licensing runtime-dependencies}@anchor{72}
@subsubsection Runtime dependencies
@@ -4893,39 +4543,39 @@ project, and gives the copyright holder for each of them:
@itemize *
-@item
+@item
libjansson: MIT License, AGPL- and LGPL-Compatible, owned by Petri Lehtinen and other individuals
-@item
+@item
libgcrypt: LGPL, owned by Free Software Foundation
-@item
+@item
postgresql: PostgreSQL License, AGPL- and LGPL-Compatible, owned by The PostgreSQL Global Development Group
-@item
+@item
libgnunetutil (in all of its variants): GPLv3+, owned by GNUnet e.V.
-@item
+@item
libgnunetjson: GPLv3+, GNUnet e.V.
-@item
+@item
GNU Taler: LGPLv3+ / GPLv3+ / AGPLv3+: owned by Taler Systems SA
@end itemize
@node Anastasis-gtk git //git taler net/anastasis-gtk,Documentation,Anastasis git //git taler net/anastasis,Anastasis licensing information
-@anchor{global-licensing anastasis-gtk-git-git-taler-net-anastasis-gtk}@anchor{91}
+@anchor{global-licensing anastasis-gtk-git-git-taler-net-anastasis-gtk}@anchor{73}
@subsection Anastasis-gtk (git://git.taler.net/anastasis-gtk)
Anastasis-gtk is under AGPL.
@menu
-* Runtime dependencies: Runtime dependencies<2>.
+* Runtime dependencies: Runtime dependencies<2>.
@end menu
@node Runtime dependencies<2>,,,Anastasis-gtk git //git taler net/anastasis-gtk
-@anchor{global-licensing id1}@anchor{92}
+@anchor{global-licensing id1}@anchor{74}
@subsubsection Runtime dependencies
@@ -4935,65 +4585,65 @@ project, and gives the copyright holder for each of them:
@itemize *
-@item
+@item
libjansson: MIT License, AGPL- and LGPL-Compatible, owned by Petri Lehtinen and other individuals
-@item
+@item
libgcrypt: LGPL, owned by Free Software Foundation
-@item
+@item
postgresql: PostgreSQL License, AGPL- and LGPL-Compatible, owned by The PostgreSQL Global Development Group
-@item
+@item
libgnunetutil (in all of its variants): GPLv3+, owned by GNUnet e.V.
-@item
+@item
libgnunetjson: GPLv3+, GNUnet e.V.
-@item
+@item
libgnunetgtk: GPLv3+, GNUnet e.V.
-@item
+@item
GNU Taler: LGPLv3+ / GPLv3+ / AGPLv3+: owned by Taler Systems SA
@end itemize
@node Documentation,,Anastasis-gtk git //git taler net/anastasis-gtk,Anastasis licensing information
-@anchor{global-licensing documentation}@anchor{93}
+@anchor{global-licensing documentation}@anchor{75}
@subsection Documentation
The documentation is licensed under the GNU Free Documentation License Version 1.3 or later.
@node Man Pages,Complete Index,Anastasis licensing information,Documentation Overview
-@anchor{manindex doc}@anchor{94}@anchor{manindex man-pages}@anchor{95}
+@anchor{manindex doc}@anchor{76}@anchor{manindex man-pages}@anchor{77}
@section Man Pages
@menu
-* anastasis-config(1): anastasis-config 1.
-* anastasis-gtk(1): anastasis-gtk 1.
-* anastasis-httpd(1): anastasis-httpd 1.
-* anastasis-reducer(1): anastasis-reducer 1.
-* anastasis.conf(5): anastasis conf 5.
+* anastasis-config(1): anastasis-config 1.
+* anastasis-gtk(1): anastasis-gtk 1.
+* anastasis-httpd(1): anastasis-httpd 1.
+* anastasis-reducer(1): anastasis-reducer 1.
+* anastasis.conf(5): anastasis conf 5.
@end menu
@node anastasis-config 1,anastasis-gtk 1,,Man Pages
-@anchor{manpages/anastasis-config 1 doc}@anchor{96}@anchor{manpages/anastasis-config 1 anastasis-config-1}@anchor{97}
+@anchor{manpages/anastasis-config 1 doc}@anchor{78}@anchor{manpages/anastasis-config 1 anastasis-config-1}@anchor{79}
@subsection anastasis-config(1)
@menu
-* Synopsis::
-* Description::
-* See Also::
-* Bugs::
+* Synopsis::
+* Description::
+* See Also::
+* Bugs::
@end menu
@node Synopsis,Description,,anastasis-config 1
-@anchor{manpages/anastasis-config 1 synopsis}@anchor{98}
+@anchor{manpages/anastasis-config 1 synopsis}@anchor{7a}
@subsubsection Synopsis
@@ -5013,7 +4663,7 @@ The documentation is licensed under the GNU Free Documentation License Version 1
[@strong{-v} | @strong{––version}]
@node Description,See Also,Synopsis,anastasis-config 1
-@anchor{manpages/anastasis-config 1 description}@anchor{99}
+@anchor{manpages/anastasis-config 1 description}@anchor{7b}
@subsubsection Description
@@ -5097,14 +4747,14 @@ Print Anastasis version number.
@end table
@node See Also,Bugs,Description,anastasis-config 1
-@anchor{manpages/anastasis-config 1 see-also}@anchor{9a}
+@anchor{manpages/anastasis-config 1 see-also}@anchor{7c}
@subsubsection See Also
anastasis.conf(5)
@node Bugs,,See Also,anastasis-config 1
-@anchor{manpages/anastasis-config 1 bugs}@anchor{9b}
+@anchor{manpages/anastasis-config 1 bugs}@anchor{7d}
@subsubsection Bugs
@@ -5112,21 +4762,21 @@ Report bugs by using @indicateurl{https://bugs.anastasis.lu} or by sending elect
mail to <@email{contact@@anastasis.lu}>.
@node anastasis-gtk 1,anastasis-httpd 1,anastasis-config 1,Man Pages
-@anchor{manpages/anastasis-gtk 1 doc}@anchor{9c}@anchor{manpages/anastasis-gtk 1 anastasis-gtk-1}@anchor{9d}
+@anchor{manpages/anastasis-gtk 1 doc}@anchor{7e}@anchor{manpages/anastasis-gtk 1 anastasis-gtk-1}@anchor{7f}
@subsection anastasis-gtk(1)
@menu
-* Synopsis: Synopsis<2>.
-* Description: Description<2>.
-* See Also: See Also<2>.
-* Bugs: Bugs<2>.
+* Synopsis: Synopsis<2>.
+* Description: Description<2>.
+* See Also: See Also<2>.
+* Bugs: Bugs<2>.
@end menu
@node Synopsis<2>,Description<2>,,anastasis-gtk 1
-@anchor{manpages/anastasis-gtk 1 synopsis}@anchor{9e}
+@anchor{manpages/anastasis-gtk 1 synopsis}@anchor{80}
@subsubsection Synopsis
@@ -5138,7 +4788,7 @@ mail to <@email{contact@@anastasis.lu}>.
[@strong{-v} | @strong{––version}]
@node Description<2>,See Also<2>,Synopsis<2>,anastasis-gtk 1
-@anchor{manpages/anastasis-gtk 1 description}@anchor{9f}
+@anchor{manpages/anastasis-gtk 1 description}@anchor{81}
@subsubsection Description
@@ -5171,14 +4821,14 @@ Print version information.
@end table
@node See Also<2>,Bugs<2>,Description<2>,anastasis-gtk 1
-@anchor{manpages/anastasis-gtk 1 see-also}@anchor{a0}
+@anchor{manpages/anastasis-gtk 1 see-also}@anchor{82}
@subsubsection See Also
anastasis-reducer(1), anastasis-httpd(1), anastasis.conf(5).
@node Bugs<2>,,See Also<2>,anastasis-gtk 1
-@anchor{manpages/anastasis-gtk 1 bugs}@anchor{a1}
+@anchor{manpages/anastasis-gtk 1 bugs}@anchor{83}
@subsubsection Bugs
@@ -5186,29 +4836,29 @@ Report bugs by using @indicateurl{https://bugs.anastasis.lu/} or by sending elec
mail to <@email{contact@@anastasis.lu}>.
@node anastasis-httpd 1,anastasis-reducer 1,anastasis-gtk 1,Man Pages
-@anchor{manpages/anastasis-httpd 1 doc}@anchor{a2}@anchor{manpages/anastasis-httpd 1 anastasis-httpd-1}@anchor{a3}
+@anchor{manpages/anastasis-httpd 1 doc}@anchor{84}@anchor{manpages/anastasis-httpd 1 anastasis-httpd-1}@anchor{85}
@subsection anastasis-httpd(1)
@menu
-* Synopsis: Synopsis<3>.
-* Description: Description<3>.
-* Signals::
-* See also::
-* Bugs: Bugs<3>.
+* Synopsis: Synopsis<3>.
+* Description: Description<3>.
+* Signals::
+* See also::
+* Bugs: Bugs<3>.
@end menu
@node Synopsis<3>,Description<3>,,anastasis-httpd 1
-@anchor{manpages/anastasis-httpd 1 synopsis}@anchor{a4}
+@anchor{manpages/anastasis-httpd 1 synopsis}@anchor{86}
@subsubsection Synopsis
@strong{anastasis-httpd}
@node Description<3>,Signals,Synopsis<3>,anastasis-httpd 1
-@anchor{manpages/anastasis-httpd 1 description}@anchor{a5}
+@anchor{manpages/anastasis-httpd 1 description}@anchor{87}
@subsubsection Description
@@ -5240,7 +4890,7 @@ Print version information.
@end table
@node Signals,See also,Description<3>,anastasis-httpd 1
-@anchor{manpages/anastasis-httpd 1 signals}@anchor{a6}
+@anchor{manpages/anastasis-httpd 1 signals}@anchor{88}
@subsubsection Signals
@@ -5255,14 +4905,14 @@ Sending a SIGTERM to the process will cause it to shutdown cleanly.
@end table
@node See also,Bugs<3>,Signals,anastasis-httpd 1
-@anchor{manpages/anastasis-httpd 1 see-also}@anchor{a7}
+@anchor{manpages/anastasis-httpd 1 see-also}@anchor{89}
@subsubsection See also
anastasis-dbinit(1), anastasis-config(1), anastasis-gtk(1), anastasis-reducer(1)
@node Bugs<3>,,See also,anastasis-httpd 1
-@anchor{manpages/anastasis-httpd 1 bugs}@anchor{a8}
+@anchor{manpages/anastasis-httpd 1 bugs}@anchor{8a}
@subsubsection Bugs
@@ -5270,21 +4920,21 @@ Report bugs by using @indicateurl{https://bugs.anastasis.lu} or by sending
electronic mail to <@email{contact@@anastasis.lu}>.
@node anastasis-reducer 1,anastasis conf 5,anastasis-httpd 1,Man Pages
-@anchor{manpages/anastasis-reducer 1 doc}@anchor{a9}@anchor{manpages/anastasis-reducer 1 anastasis-reducer-1}@anchor{aa}
+@anchor{manpages/anastasis-reducer 1 doc}@anchor{8b}@anchor{manpages/anastasis-reducer 1 anastasis-reducer-1}@anchor{8c}
@subsection anastasis-reducer(1)
@menu
-* Synopsis: Synopsis<4>.
-* Description: Description<4>.
-* See Also: See Also<3>.
-* Bugs: Bugs<4>.
+* Synopsis: Synopsis<4>.
+* Description: Description<4>.
+* See Also: See Also<3>.
+* Bugs: Bugs<4>.
@end menu
@node Synopsis<4>,Description<4>,,anastasis-reducer 1
-@anchor{manpages/anastasis-reducer 1 synopsis}@anchor{ab}
+@anchor{manpages/anastasis-reducer 1 synopsis}@anchor{8d}
@subsubsection Synopsis
@@ -5299,7 +4949,7 @@ electronic mail to <@email{contact@@anastasis.lu}>.
[@strong{-v} | @strong{––version}] COMMAND
@node Description<4>,See Also<3>,Synopsis<4>,anastasis-reducer 1
-@anchor{manpages/anastasis-reducer 1 description}@anchor{ac}
+@anchor{manpages/anastasis-reducer 1 description}@anchor{8e}
@subsubsection Description
@@ -5350,14 +5000,14 @@ Print version information.
@end table
@node See Also<3>,Bugs<4>,Description<4>,anastasis-reducer 1
-@anchor{manpages/anastasis-reducer 1 see-also}@anchor{ad}
+@anchor{manpages/anastasis-reducer 1 see-also}@anchor{8f}
@subsubsection See Also
anastasis-gtk(1), anastasis-httpd(1), anastasis.conf(5).
@node Bugs<4>,,See Also<3>,anastasis-reducer 1
-@anchor{manpages/anastasis-reducer 1 bugs}@anchor{ae}
+@anchor{manpages/anastasis-reducer 1 bugs}@anchor{90}
@subsubsection Bugs
@@ -5365,20 +5015,20 @@ Report bugs by using @indicateurl{https://bugs.anastasis.lu/} or by sending elec
mail to <@email{contact@@anastasis.lu}>.
@node anastasis conf 5,,anastasis-reducer 1,Man Pages
-@anchor{manpages/anastasis conf 5 doc}@anchor{af}@anchor{manpages/anastasis conf 5 anastasis-conf-5}@anchor{b0}
+@anchor{manpages/anastasis conf 5 doc}@anchor{91}@anchor{manpages/anastasis conf 5 anastasis-conf-5}@anchor{92}
@subsection anastasis.conf(5)
@menu
-* Description: Description<5>.
-* SEE ALSO::
-* BUGS::
+* Description: Description<5>.
+* SEE ALSO::
+* BUGS::
@end menu
@node Description<5>,SEE ALSO,,anastasis conf 5
-@anchor{manpages/anastasis conf 5 description}@anchor{b1}
+@anchor{manpages/anastasis conf 5 description}@anchor{93}
@subsubsection Description
@@ -5425,14 +5075,14 @@ include the entirety of @code{sub.conf} at that point in @code{main.conf}.
.. TODO: Document ‘anastasis-config -V’ in light of ‘@@INLINE@@’ in taler-config(1).
@menu
-* GLOBAL OPTIONS::
-* Authorization options::
-* Postgres database configuration::
+* GLOBAL OPTIONS::
+* Authorization options::
+* Postgres database configuration::
@end menu
@node GLOBAL OPTIONS,Authorization options,,Description<5>
-@anchor{manpages/anastasis conf 5 global-options}@anchor{b2}
+@anchor{manpages/anastasis conf 5 global-options}@anchor{94}
@subsubsection GLOBAL OPTIONS
@@ -5482,7 +5132,7 @@ TCP port on which the HTTP service should listen on.
@end table
@node Authorization options,Postgres database configuration,GLOBAL OPTIONS,Description<5>
-@anchor{manpages/anastasis conf 5 authorization-options}@anchor{b3}
+@anchor{manpages/anastasis conf 5 authorization-options}@anchor{95}
@subsubsection Authorization options
@@ -5508,7 +5158,7 @@ Helper command to run (only relevant for some plugins).
@end table
@node Postgres database configuration,,Authorization options,Description<5>
-@anchor{manpages/anastasis conf 5 postgres-database-configuration}@anchor{b4}
+@anchor{manpages/anastasis conf 5 postgres-database-configuration}@anchor{96}
@subsubsection Postgres database configuration
@@ -5526,14 +5176,14 @@ should use, i.e. @code{postgres://anastasis}.
@end table
@node SEE ALSO,BUGS,Description<5>,anastasis conf 5
-@anchor{manpages/anastasis conf 5 see-also}@anchor{b5}
+@anchor{manpages/anastasis conf 5 see-also}@anchor{97}
@subsubsection SEE ALSO
anastasis-httpd(1), anastasis-config(1)
@node BUGS,,SEE ALSO,anastasis conf 5
-@anchor{manpages/anastasis conf 5 bugs}@anchor{b6}
+@anchor{manpages/anastasis conf 5 bugs}@anchor{98}
@subsubsection BUGS
@@ -5541,12 +5191,12 @@ Report bugs by using @indicateurl{https://bugs.anastasis.lu/} or by sending elec
mail to <@email{contact@@anastasis.lu}>.
@node Complete Index,GNU Free Documentation License,Man Pages,Documentation Overview
-@anchor{genindex doc}@anchor{b7}@anchor{genindex complete-index}@anchor{b8}
+@anchor{genindex doc}@anchor{99}@anchor{genindex complete-index}@anchor{9a}
@section Complete Index
@node GNU Free Documentation License,,Complete Index,Documentation Overview
-@anchor{fdl-1 3 doc}@anchor{b9}@anchor{fdl-1 3 gnu-fdl-1-3}@anchor{ba}@anchor{fdl-1 3 gnu-free-documentation-license}@anchor{bb}
+@anchor{fdl-1 3 doc}@anchor{9b}@anchor{fdl-1 3 gnu-fdl-1-3}@anchor{9c}@anchor{fdl-1 3 gnu-free-documentation-license}@anchor{9d}
@section GNU Free Documentation License
@@ -5559,24 +5209,24 @@ Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
@menu
-* 0. PREAMBLE: 0 PREAMBLE.
-* 1. APPLICABILITY AND DEFINITIONS: 1 APPLICABILITY AND DEFINITIONS.
-* 2. VERBATIM COPYING: 2 VERBATIM COPYING.
-* 3. COPYING IN QUANTITY: 3 COPYING IN QUANTITY.
-* 4. MODIFICATIONS: 4 MODIFICATIONS.
-* 5. COMBINING DOCUMENTS: 5 COMBINING DOCUMENTS.
-* 6. COLLECTIONS OF DOCUMENTS: 6 COLLECTIONS OF DOCUMENTS.
-* 7. AGGREGATION WITH INDEPENDENT WORKS: 7 AGGREGATION WITH INDEPENDENT WORKS.
-* 8. TRANSLATION: 8 TRANSLATION.
-* 9. TERMINATION: 9 TERMINATION.
-* 10. FUTURE REVISIONS OF THIS LICENSE: 10 FUTURE REVISIONS OF THIS LICENSE.
-* 11. RELICENSING: 11 RELICENSING.
-* ADDENDUM; How to use this License for your documents: ADDENDUM How to use this License for your documents.
+* 0. PREAMBLE: 0 PREAMBLE.
+* 1. APPLICABILITY AND DEFINITIONS: 1 APPLICABILITY AND DEFINITIONS.
+* 2. VERBATIM COPYING: 2 VERBATIM COPYING.
+* 3. COPYING IN QUANTITY: 3 COPYING IN QUANTITY.
+* 4. MODIFICATIONS: 4 MODIFICATIONS.
+* 5. COMBINING DOCUMENTS: 5 COMBINING DOCUMENTS.
+* 6. COLLECTIONS OF DOCUMENTS: 6 COLLECTIONS OF DOCUMENTS.
+* 7. AGGREGATION WITH INDEPENDENT WORKS: 7 AGGREGATION WITH INDEPENDENT WORKS.
+* 8. TRANSLATION: 8 TRANSLATION.
+* 9. TERMINATION: 9 TERMINATION.
+* 10. FUTURE REVISIONS OF THIS LICENSE: 10 FUTURE REVISIONS OF THIS LICENSE.
+* 11. RELICENSING: 11 RELICENSING.
+* ADDENDUM; How to use this License for your documents: ADDENDUM How to use this License for your documents.
@end menu
@node 0 PREAMBLE,1 APPLICABILITY AND DEFINITIONS,,GNU Free Documentation License
-@anchor{fdl-1 3 preamble}@anchor{bc}
+@anchor{fdl-1 3 preamble}@anchor{9e}
@subsection 0. PREAMBLE
@@ -5602,7 +5252,7 @@ published as a printed book. We recommend this License principally for
works whose purpose is instruction or reference.
@node 1 APPLICABILITY AND DEFINITIONS,2 VERBATIM COPYING,0 PREAMBLE,GNU Free Documentation License
-@anchor{fdl-1 3 applicability-and-definitions}@anchor{bd}
+@anchor{fdl-1 3 applicability-and-definitions}@anchor{9f}
@subsection 1. APPLICABILITY AND DEFINITIONS
@@ -5692,7 +5342,7 @@ these Warranty Disclaimers may have is void and has no effect on the
meaning of this License.
@node 2 VERBATIM COPYING,3 COPYING IN QUANTITY,1 APPLICABILITY AND DEFINITIONS,GNU Free Documentation License
-@anchor{fdl-1 3 verbatim-copying}@anchor{be}
+@anchor{fdl-1 3 verbatim-copying}@anchor{a0}
@subsection 2. VERBATIM COPYING
@@ -5710,7 +5360,7 @@ You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@node 3 COPYING IN QUANTITY,4 MODIFICATIONS,2 VERBATIM COPYING,GNU Free Documentation License
-@anchor{fdl-1 3 copying-in-quantity}@anchor{bf}
+@anchor{fdl-1 3 copying-in-quantity}@anchor{a1}
@subsection 3. COPYING IN QUANTITY
@@ -5750,7 +5400,7 @@ Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@node 4 MODIFICATIONS,5 COMBINING DOCUMENTS,3 COPYING IN QUANTITY,GNU Free Documentation License
-@anchor{fdl-1 3 modifications}@anchor{c0}
+@anchor{fdl-1 3 modifications}@anchor{a2}
@subsection 4. MODIFICATIONS
@@ -5764,55 +5414,55 @@ In addition, you must do these things in the Modified Version:
@itemize -
-@item
+@item
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions (which
should, if there were any, be listed in the History section of the
Document). You may use the same title as a previous version if the
original publisher of that version gives permission.
-@item
+@item
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in the
Modified Version, together with at least five of the principal
authors of the Document (all of its principal authors, if it has
fewer than five), unless they release you from this requirement.
-@item
+@item
C. State on the Title page the name of the publisher of the Modified
Version, as the publisher.
-@item
+@item
@enumerate 4
-@item
+@item
Preserve all the copyright notices of the Document.
@end enumerate
-@item
+@item
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
-@item
+@item
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
-@item
+@item
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document’s license
notice.
-@item
+@item
@enumerate 8
-@item
+@item
Include an unaltered copy of this License.
@end enumerate
-@item
+@item
I. Preserve the section Entitled “History”, Preserve its Title, and
add to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
@@ -5821,7 +5471,7 @@ stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
-@item
+@item
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise the
network locations given in the Document for previous versions it was
@@ -5830,30 +5480,30 @@ a network location for a work that was published at least four years
before the Document itself, or if the original publisher of the
version it refers to gives permission.
-@item
+@item
K. For any section Entitled “Acknowledgements” or “Dedications”,
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
-@item
+@item
L. Preserve all the Invariant Sections of the Document, unaltered in
their text and in their titles. Section numbers or the equivalent are
not considered part of the section titles.
-@item
+@item
M. Delete any section Entitled “Endorsements”. Such a section may not
be included in the Modified Version.
-@item
+@item
N. Do not retitle any existing section to be Entitled “Endorsements”
or to conflict in title with any Invariant Section.
-@item
+@item
@enumerate 15
-@item
+@item
Preserve any Warranty Disclaimers.
@end enumerate
@end itemize
@@ -5886,7 +5536,7 @@ give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@node 5 COMBINING DOCUMENTS,6 COLLECTIONS OF DOCUMENTS,4 MODIFICATIONS,GNU Free Documentation License
-@anchor{fdl-1 3 combining-documents}@anchor{c1}
+@anchor{fdl-1 3 combining-documents}@anchor{a3}
@subsection 5. COMBINING DOCUMENTS
@@ -5913,7 +5563,7 @@ sections Entitled “Dedications”. You must delete all sections Entitled
“Endorsements”.
@node 6 COLLECTIONS OF DOCUMENTS,7 AGGREGATION WITH INDEPENDENT WORKS,5 COMBINING DOCUMENTS,GNU Free Documentation License
-@anchor{fdl-1 3 collections-of-documents}@anchor{c2}
+@anchor{fdl-1 3 collections-of-documents}@anchor{a4}
@subsection 6. COLLECTIONS OF DOCUMENTS
@@ -5929,7 +5579,7 @@ License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@node 7 AGGREGATION WITH INDEPENDENT WORKS,8 TRANSLATION,6 COLLECTIONS OF DOCUMENTS,GNU Free Documentation License
-@anchor{fdl-1 3 aggregation-with-independent-works}@anchor{c3}
+@anchor{fdl-1 3 aggregation-with-independent-works}@anchor{a5}
@subsection 7. AGGREGATION WITH INDEPENDENT WORKS
@@ -5950,7 +5600,7 @@ equivalent of covers if the Document is in electronic form. Otherwise
they must appear on printed covers that bracket the whole aggregate.
@node 8 TRANSLATION,9 TERMINATION,7 AGGREGATION WITH INDEPENDENT WORKS,GNU Free Documentation License
-@anchor{fdl-1 3 translation}@anchor{c4}
+@anchor{fdl-1 3 translation}@anchor{a6}
@subsection 8. TRANSLATION
@@ -5972,7 +5622,7 @@ If a section in the Document is Entitled “Acknowledgements”,
Title (section 1) will typically require changing the actual title.
@node 9 TERMINATION,10 FUTURE REVISIONS OF THIS LICENSE,8 TRANSLATION,GNU Free Documentation License
-@anchor{fdl-1 3 termination}@anchor{c5}
+@anchor{fdl-1 3 termination}@anchor{a7}
@subsection 9. TERMINATION
@@ -6002,7 +5652,7 @@ reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
@node 10 FUTURE REVISIONS OF THIS LICENSE,11 RELICENSING,9 TERMINATION,GNU Free Documentation License
-@anchor{fdl-1 3 future-revisions-of-this-license}@anchor{c6}
+@anchor{fdl-1 3 future-revisions-of-this-license}@anchor{a8}
@subsection 10. FUTURE REVISIONS OF THIS LICENSE
@@ -6024,7 +5674,7 @@ used, that proxy’s public statement of acceptance of a version
permanently authorizes you to choose that version for the Document.
@node 11 RELICENSING,ADDENDUM How to use this License for your documents,10 FUTURE REVISIONS OF THIS LICENSE,GNU Free Documentation License
-@anchor{fdl-1 3 relicensing}@anchor{c7}
+@anchor{fdl-1 3 relicensing}@anchor{a9}
@subsection 11. RELICENSING
@@ -6055,7 +5705,7 @@ under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
@node ADDENDUM How to use this License for your documents,,11 RELICENSING,GNU Free Documentation License
-@anchor{fdl-1 3 addendum-how-to-use-this-license-for-your-documents}@anchor{c8}
+@anchor{fdl-1 3 addendum-how-to-use-this-license-for-your-documents}@anchor{aa}
@subsection ADDENDUM: How to use this License for your documents
diff --git a/doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png b/doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png
new file mode 100644
index 0000000..4a3430b
--- /dev/null
+++ b/doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png
Binary files differ
diff --git a/doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png.map b/doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png.map
new file mode 100644
index 0000000..8be6a30
--- /dev/null
+++ b/doc/graphviz-2d8d83202d2b7835498d2a5c18fa9e3cc05c4b6a.png.map
@@ -0,0 +1,2 @@
+<map id="G" name="G">
+</map>
diff --git a/doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png b/doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png
new file mode 100644
index 0000000..124c4e3
--- /dev/null
+++ b/doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png
Binary files differ
diff --git a/doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png.map b/doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png.map
new file mode 100644
index 0000000..8be6a30
--- /dev/null
+++ b/doc/graphviz-834e5a93329dec2ccdefd2a21bdfb5a02bad1c84.png.map
@@ -0,0 +1,2 @@
+<map id="G" name="G">
+</map>
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.)