[taler-anastasis] branch master updated: revise server architecture text

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository anastasis.

The following commit(s) were added to refs/heads/master by this push:
     new 932993d  revise server architecture text
932993d is described below

commit 932993dbdb9722f54bede407d5f53fa3e1e70874
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Jun 7 10:58:40 2020 +0200

    revise server architecture text
---
 doc/thesis/design.tex              | 125 +++++++++++++++++++++++--------------
 doc/thesis/server_architecture.tex | 124 ++++++++++++++++++++++--------------
 2 files changed, 154 insertions(+), 95 deletions(-)

diff --git a/doc/thesis/design.tex b/doc/thesis/design.tex
index 7b8e679..208df7c 100644
--- a/doc/thesis/design.tex
+++ b/doc/thesis/design.tex
@@ -1,63 +1,75 @@
 \section{Design}
 
-Anastasis is a service that allows the user to securely deposit a core
-secret with an open set of escrow providers and recover it if the
+Anastasis is a service that allows the user to securely deposit a {\em core
+secret} with an open set of escrow providers and recover it if the
 secret is lost. The core secret itself is protected from the escrow
-providers by encrypting it with a master key. The main objective of
+providers by encrypting it with a {\em master key}. The main objective of
 Anastasis is to ensure that the user can reliably recover the core
 secret, while making this difficult for everyone else. Furthermore, it
 is assumed that the user is unable to reliably remember any secret
 with sufficiently high entropy, so we cannot simply encrypt using some
 other key material in possession of the user.
 
-To uniquely identify users, an “unforgettable” identifier is
-used. This identifier should be difficult to guess for anybody but the
-user. However, the identifier is not expected to have sufficient
-entropy or secrecy to be cryptographically secure. Examples for such
-identifier would be a concatenation of the full name of the user and
-their social security or passport number(s). For Swiss citizens, the
-AHV number could also be used.
-
-The adversary model of Anastasis has two types of adversaries: weak
-adversaries which do not know the user’s identifier, and strong
-adversaries which somehow do know a user’s identifier. For weak
-adversaries, the system guarantees full confidentiality. For strong
-adversaries, breaking confidentiality additionally requires that
-Anastasis escrow providers must have colluded. The user can specify a
-set of policies which determine which Anastasis escrow providers would
-need to collude to break confidentiality. These policies also set the
-bar for the user to recover their core secret.
-
-A recovery document includes all 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
+To uniquely identify users and to provide a first layer of protection,
+an “unforgettable” identifier is used. This identifier should be
+difficult to guess for anybody but the user. However, the identifier
+is not expected to have sufficient entropy or secrecy to be
+cryptographically secure. Examples for such an identifier would be a
+concatenation of the full name of the user and their social security
+or passport number(s). For Swiss citizens, the AHV number could also
+be used.
+
+The adversary model of Anastasis has two types of adversaries: {\em
+  weak adversaries} which do not know the user’s identifier, and {\em
+  strong adversaries} which somehow do know a user’s
+identifier. Against weak adversaries, the system guarantees full
+confidentiality, except for the information disclosed to the providers
+when authorizing key recovery. Weak adversaries cannot break
+confidentiality even if all escrow providers are part of a conspiracy
+of weak adversaries.  For strong adversaries, breaking confidentiality
+additionally requires that Anastasis escrow providers must have
+colluded. The user can specify a set of policies which determine which
+Anastasis escrow providers would need to collude to break
+confidentiality. These policies also set the bar for the user to
+recover their core secret.
+
+A {\em recovery document} includes all the information a user needs to
+recover access to their core secret. It specifies a set of {\em 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
+with (initially encrypted) {\em 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 (except if they are the provider and
+then they may learn it only during key recovery).
+
+In addition to a set of escrow methods and associated Anastasis server
+operators, the recovery document also specifies {\em 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).
+recovery document (except for meta data such as its length or
+approximate creation time, which may be exposed to an adversary which
+monitors the user’s network traffic or operates an escrow provider).
+
 
 \subsection{System architecture}
 
 This graphic shows the basic architecture of the Anastasis
 application. It shows a simplified flow of the application. The
-details of each component is shown later.
+details of each component are explained later.
+
 \begin{figure}[H]
+  % FIXME: _handle => handler (!)
        \centering
                \includegraphics[scale=0.4]{images/system_design.png}
        \caption{System design overview}
@@ -65,13 +77,30 @@ details of each component is shown later.
 \end{figure}
 
 \begin{enumerate}
-\item The Anastasis CLI interacts with the Anastasis API. The Anastasis\_API 
is responsible for the communication with the user. The Anastasis\_API also 
handles the communication between the other client components.
-\item After the user provided their unforgettable secret, the Crypto\_API 
derives the needed key material for the further communication. This is 
simplified, in reality the client would first need to download the server salt 
to generate the user keys.
-The crypto\_api is later also responsible for the decryption and encryption of 
the data, sent or received from the server.
-\item The Service\_API is responsible for the communication with the Anastasis 
server. The Anastasis\_API sends the previously generated data and the user 
selected request to the service.
-\item The Service\_API generates the requested HTTP request and sends it to 
the webserver. The Service\_API is also responsible to handle the server answer 
to the request.
-\item The webserver handles the requests sent to him by the clients. It will 
then send the request to the according handle. The webserver will later send 
back the requested data or the status code of the operation back to the client 
application.
-\item Each operation has a different handle. The handle will then process the 
request. It will either store or lookup the requested data on the database. 
When the request is finished, the handle will send back the data or the status 
code to the webserver and afterwards to the client.
+\item The Anastasis CLI interacts with the Anastasis API. The
+  Anastasis API is responsible for triggering interactions with the
+  user, and also manages the interactions between the
+  various client-side components.
+\item After the user provided their unforgettable secret, the
+  Crypto API derives the needed key material for the further
+  communication. This is simplified, in reality the client would first
+  need to download the server salt to generate the user keys.  The
+  crypto API is later also responsible for the decryption and
+  encryption of the data, sent or received from the server.
+\item The Service API is responsible for the communication with the
+  Anastasis server. The Anastasis API sends the previously generated
+  data and the user selected request to the service.
+  The Service API is also responsible to handle
+  the server's response to the request.
+\item The central webserver logic handles HTTP requests sent to it by the
+  clients. It will dispatch requests to the corresponding handler. The
+  webserver's core logic also returns the response and the status code
+  of the operation to the client application.
+\item Each REST endpoint of the Anastasis server is implemented by
+  a specific handler. The handler prcesses the requests, typically
+  by storing or looking up the requested
+  data with the database. When the request is finished, the handler will
+  send back the data or the status code to the webserver's core logic.
 \end{enumerate}
 
 
@@ -164,7 +193,7 @@ $
 \item policies : shows all available policies in the recovery document and
 the respective status of the truths used in each policy.
 \item try \$truth : this command starts a truth which needs interaction with 
external services like sms or e-mail. It also shows the instructions to solve a 
truth.
-\item answer \$truth \$answer : this command tries to answer the selected 
truth with the provided answer. The application will check the answer and give 
a feedback to the user. Everytime a truth is solved, the client\_api will check 
if a policy is solved, if a policy was solved successfully the application will 
print out the recovered core secret.
+\item answer \$truth \$answer : this command tries to answer the selected 
truth with the provided answer. The application will check the answer and give 
a feedback to the user. Everytime a truth is solved, the client API will check 
if a policy is solved, if a policy was solved successfully the application will 
print out the recovered core secret.
 \end{itemize}
 Below is an example flow of the application. \\
 \begin{lstlisting}
diff --git a/doc/thesis/server_architecture.tex 
b/doc/thesis/server_architecture.tex
index 602542a..38eda25 100644
--- a/doc/thesis/server_architecture.tex
+++ b/doc/thesis/server_architecture.tex
@@ -2,7 +2,19 @@
 
 The Anastasis server architecture consists of two components. A web
 server with a REST API and a PostgreSQL database. The structure of
-these two components is shown here.
+these two components is shown in Figure~\ref{fig:anastasis:server}.
+
+\begin{figure}[H]
+       \centering
+       FIXME
+       \caption{Anastasis server architecture}
+       \label{fig:anastasis:server}
+\end{figure}
+
+The webserver of Anastasis provides a RESTful API. For a detailed
+documentation of the REST API, see
+Section~\ref{appendix:rest_api_documentation}.
+
 
 \subsubsection{Database}
 
@@ -10,46 +22,44 @@ The database schema of Anastasis is shown in
 Figure~\ref{fig:anastasis_database}.
 \begin{figure}[H]
        \centering
-               \includegraphics[scale=0.5]{images/anastasis-db.png}
-       \caption{Anastasis database}
+       \includegraphics[scale=0.5]{images/anastasis-db.png}
+        % FIXME: consider truth_method => authentication_method rename
+        % FIXME: 'amount_val' should NOT just be an 'INT', but an 'INT8'
+       \caption{Anastasis database schema}
        \label{fig:anastasis_database}
 \end{figure}
 
-The database schema consists of 4 tables:
+The database schema consists of four main tables:
 
 \begin{itemize}
-\item The Truth table is responsible for storing the key shares and
+\item The {\em Truth} table is responsible for storing the key shares and
   its authentication method. The key share and the truth are stored
   encrypted in the database. The truth is only decrypted during
   authentication. The key share is never decrypted for the
   server. This protects the privacy of the customer. Likewise, the
   user data is protected after a possible theft.
-\item The User table contains the identification of the user and an
+\item The {\em User} table contains the identification of the user and an
   expiration timestamp. This timestamp is a subscription period. This
   timestamp is updated after each payment the user makes. Users for
   whom the subscription has expired are periodically deleted.
-\item The Payments table contains the details of a payment from a
+\item The {\em Payments} table contains the details of a payment from a
   user. The payment is used either for the post-counter or the
   subscription. The post-counter is decremented after each upload of a
   recovery document. The user can only upload the recovery document if
   the provided payment contains a post-counter which is at least 1.
   Through this measure we can prevent people from maliciously filling
   our database.
-\item The Recoverydocument table contains the recovery
+\item The {\em Recoverydocument} table contains the recovery
   information. The recovery document is stored encrypted in the
   database. This offers better protection, as explained earlier for
   the Truth table. Each recovery document record also contains a
   version, a hash of the recovery document and a signature. The
   version attribute allows the user to lookup a specific version of
   the document. The hash is used to check if the user uploads a
-  duplicate of the document. Last the signature ensures the integrity
-  of the data.
+  duplicate of the document. The signature attests the
+  integrity of the recovery data.
 \end{itemize}
 
-\subsubsection{Server API}
-
-The webserver of Anastasis runs a RESTful API. For a detailed documentation of 
the
-REST API see the rest\_api\_documentation in the appendix.
 
 \subsubsection{Authentication Methods}
 
@@ -58,49 +68,69 @@ authentication methods for Anastasis. In our implementation 
only the
 secure question is implemented. The other methods are just explained
 how they would be implemented.
 
+In all cases, the authentication process begins by the user decrypting
+their (encrypted) recovery document, which contains a list of Anastasis
+providers, associated authentication methods, \$UUIDs and associated
+truth encryption keys.  The recovery process than varies slightly
+depending on the authentication method.
+
 \paragraph{SMS (sms)}
 
-The user tells the server with a request that he wants to authenticate
-with him (GET /truth/\$UUID. The server will then generate a pin and
-send it with an SMS provider to the stored number in the truth
-object. The client then must send another request with the sent pin
-(GET /truth/\$UUID?resonse=\$RESPONSE). The server can now check if
-the two pins match. Upon success the server will release the encrypted
+The user tells the server with a request that they wants to authorize
+key recovery (via GET /truth/\$UUID), providing a way to decrypt the
+truth with the phone number. The server will then generate a \$PIN and
+send it via an SMS provider to the stored number in the truth
+object. The client then must send another request with the sent \$PIN
+(via GET /truth/\$UUID?resonse=\$PIN). The server can now check
+if the two PINs match. Upon success, the server returns the encrypted
 key share.
 
 \paragraph{Video identification (vid)}
 
-Requires the user to identify via video-call. The user is expected to
-delete all metadata revealing information about him/her from the
-images before uploading them. Since the respective images must be
-passed on to the video identification service in the event of password
-recovery, it must be ensured that no further information about the
-user can be derived from them.
-
-The user first must send a request to server that he wants to
-authenticate(GET /truth/\$UUID).  The server will then send a request
-to the video authentication provider that a user wants to
-authenticate. The provider will generate a link to a video conference
-which is sent to the user. The authentication provider then checks
-with image if the user is legitimate. Upon success the video provider
-sends an ok to the server and the server will release the key share.
+This method allows the user to identify via video-call.  Since the
+respective images must be passed on to the video identification
+service in the event of password recovery, it must be ensured that no
+further information about the user can be derived from them.  Hence,
+the user's client software must try to delete metadata that could
+result in accidental information leakage about the user from the image
+before encrypting and uploading it to the Anastasis provider.
+
+For recovery, the user must first send a request to server that they
+wants to authorize recovery (GET /truth/\$UUID).  The Anastassis
+provider will then decrypt the user's image and send a request with a
+\$TOKEN to a video authentication provider that a user wants to
+authenticate, and respond to the user with a link to a video
+conference.  The video authentication provider then checks via video
+conference that the user in the image is the same that they have on
+the video link. Upon success, the video provider releases the \$TOKEN
+to the user.  The client then must send another request with the
+\$TOKEN (via GET /truth/\$UUID?resonse=\$TOKEN). The Anastasis
+provider checks that the tokens match, and upon success returns the
+encrypted key share.
 
 \paragraph{Post identification (post)}
 
-The user tells the server with a request that he wants to authenticate
-with him (GET /truth/\$UUID). The server will then send a letter
-containing a pin with a post-service to the users address which is
-stored in the truth object. The client then has to send another
-request with the sent pin (GET /truth/\$UUID?resonse=\$RESPONSE). The
-server can now check if the two pins match. Upon success the server
+The user tells the Anastasis provider with a request that they want
+to authenticate using Post identification (GET /truth/\$UUID).  The
+Anastasis provider uses the request to decrypt the user's truth to
+determine the user's postal address, and sends them letter containing
+a \$PIN.  Upon receiving the letter, the client then has to send
+another request with the \$PIN (GET /truth/\$UUID?resonse=\$PIN). The
+server can now check if the two PINs match. Upon success the server
 will release the encrypted key share.
 
 \paragraph{Security question (qa)}
 
-The user defines a secure question and answer and stores it on a
-server. The server stores the instructions, here the question,
-encrypted. The answer is stored hashed on the server, the server will
-never learn the plaintext answer. If the user wants to release the key
-share from the server he must provide the hashed answer. The server
-then checks if the stored and the provided hash match. Upon success
-the server will send the encrypted key share.
+The user provided Anastasis with a secure question and a (normalized)
+answer.  The secure question becomes part of the encrypted recovery
+document, and is never disclosed to weak adversaries, even during
+recovery.  The encrypted truth on the server only contains a (salted)
+hash of the answer. The Anastasis provider cannot learn the plaintext
+answer. Because of the salt, and it cannot mount a confirmation attack
+either.
+
+If the user wants to recover the key share from the server, they must
+provide the (salted) hash of the answer to the security question (via
+GET /truth/\$UUID?response=\$HASH). The server then checks if the
+stored and the provided hash match. Upon success the server responds
+with the encrypted key share.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.