anastasis

implementation.tex (18578B)

---

 \section{Implementation}
 
 The Anastasis is written in C. We decided to use C because of the
 various dependencies, including cryptographic libraries.  Especially,
 GNU Taler and Sync, which are working in concert with Anastasis, are
 also written in C. Using the same language makes integration and
 testing of Anastasis much easier.
 
 The whole Anastasis application consists of multiple components.
 Figure~\ref{fig:secret_split:overview} gives an overview over all the
 components.
 
 \begin{figure}[H]
 	\centering
 		\includegraphics[scale=0.5]{images/system-architecture.png}
 	\caption{System architecture overview}
 	\label{fig:system_arch:overview}
 \end{figure}
 
 \noindent In the center is the core implementation of Anastasis.
 On the left are some of the planned authentication methods from the
 application. On the right side of the box are the core parts which are
 necessary to operate Anastasis commercially. These parts are
 anticipated for a production deployment, but not part of the
 implementation for this thesis.
 
 At the bottom section are the external libraries used for the project.
 These libraries are presented in Section~\ref{sec:libraries}.
 \newpage
 
 
 \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 are explained later.
 
 \begin{figure}[H]
 	\centering
 		\includegraphics[scale=0.4]{images/system_design.png}
 	\caption{System design overview}
 	\label{fig:system_design}
 \end{figure}
 
 \begin{enumerate}
 \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 processes 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}
 
 
 \input{server_architecture}
 
 \input{client_architecture}
 
 \newpage
 \subsection{Application flow}
 
 This section describes a happy flow of the two protocols of Anastasis,
 secret splitting and secret recovery.
 
 \subsubsection{Secret splitting}
 
 Figure~\ref{fig:secret_split} illustrates the secret splitting
 process.
 
 \begin{figure}[H]
 	\centering
 		\includegraphics[scale=0.5]{images/secret_split.png}
 	\caption{Secret split process}
 	\label{fig:secret_split}
 \end{figure}
 \newpage
 \begin{enumerate}
 \item The user selects a new escrow provider on which per wants to
   store a truth object.
 \item The client software downloads the terms of service for this
   provider (GET /terms). This is also a check if the server is
   available if this command doesn't respond the client will abort the
   process.
 \item Next the client requests the server configuration (GET
   /configuration). The configuration lists the available
   authentication methods and the protocol version of the server.
 \item The client downloads the server salt (GET /salt). The salt is
   used to generate the server specific account public key, which
   identifies the user.
 \item After the user has generated the public key, per will create a
   truth object on the client. The truth object contains all the needed
   information for the recovery for this key share. This truth object
   is sent encrypted to the server and stored under the TRUTH\_PUB the client
   generated (POST /truth/\$TRUTH\_PUB).
 \item In this scenario the client has not jet paid for the
   upload. This means the server will respond with the HTTP status code
   \texttt{402 Payment required}. The client first must do a payment with our
   payment provider --- GNU Taler. After the successful payment the client
   will receive a payment identifier. With this payment identifier he
   can resend the previously failed request.
 \item The user will now repeat the steps 1-6 until per thinks that they
   have setup a sufficient amount of authentication methods. The user
   can now combine these providers to create policies. For example per
   may have stored three truth objects at three different providers.
   This means per can now define combinations with these providers,
   for example A+B, A+C and B+C. This means the user has three ways to
   recover their secret.
 \item After the user has generated the policies the client will
   generate a recovery document. The recovery document contains a list
   of all truth\_seed's used, a list of the policies and the encrypted core
   secret of the user. The client will now send a encrypted recovery
   document to each provider used in the recovery document (POST
   /policy/\$ACCOUNT\_PUB). Through this, the recovery document is
   replicated and recovery can proceed without a single point of
   failure.
 \end{enumerate}
 \newpage
 \subsubsection{Secret recovery}
 
 Figure~\ref{fig:recovery_process} illustrates the recovery process.
 \begin{figure}[H]
 	\centering
 		\includegraphics[scale=0.5]{images/recovery_process.png}
 	\caption{Secret recovery process}
 	\label{fig:recovery_process}
 \end{figure}
 \begin{enumerate}
 \item The user selects a server on which per previously stored a
   recovery document.
 \item Next the client downloads the server salt to compute the server
   specific account public key (GET /salt).
 \item After the user generated the public key, per will download the
   recovery document. At this point per can define a
   specific version or the latest version of the recovery document. In
   the illustration the client downloads the latest version (GET
   /policy/\$ACCOUNT\_PUB).
 \item The client will now decrypt the recovery document and list all
   policies and authentication methods. The user now has to solve these
   challenges. In this example the user has to answer a secure question
   which was sent to them in the recovery document. (GET
   /truth/\$TRUTH\_PUB?response=\$RESPONSE) \\
 \item Note the server can define that a challenge has a certain cost,
   in this scenario the server rejects the first request because the
   user has not yet paid for recovery.  After the payment the user can
   resend the request.  After each successfully solved challenge the
   client will check if one of the policies is completely satisfied.
   If all shares needed for one of the policies have been recovered,
   the client will decrypt the core secret and provide it to the user.
 \end{enumerate}
 
 Figure~\ref{fig:recovery_process} shows the flow using a secure
 question for the authentication challenge. If the user would have
 chosen a complex authentication method like SMS or E-Mail, the client
 would first need to start the challenge with the request (GET
 /truth/\$TRUTH\_PUB). The server would then notify the user that per will
 receive some token out of bounds. After that, the user would have to
 provide for example the PIN sent to them via SMS with the same request
 as before (GET /truth/\$TRUTH\_PUB?response=\$RESPONSE).
 
 
 \subsection{Client Application Command Line Interface (CLI)}
 
 There are two client applications which interact with the user. First
 the Anastasis {\em splitter} and second the Anastasis {\em
   assembler}. The splitter application is responsible for the backup
 of the core secret. The assembler is then responsible for the recovery
 of the core secret.
 
 Both commands are started with a configuration option ``--me=FILE''
 that gives the name of a file with the user's identity attributes.
 
 \subsubsection{Anastasis splitter}
 
 The user starts the assembler by passing a JSON document with their
 unforgettable identity attributes (name, social security number, ...).
 
 The following commands are available:
 
 \begin{itemize}
 \item server add \$URL: this command lets the user add escrow
   providers. The command will check if a supported escrow service is
   available under the provided URL. Afterwards it will download its
   terms and salt. The server needs to be added before the user can do
   any uploads on it.
 \item truth add \$server \$method \$truth: with this command the user
   can upload a truth on a previously added server. The user needs to
   specify the authorization method used and the truth for the
   authorization process, for example the phone number for SMS
   authentication.  The application will check if the server supports the
   provided method before uploading.
 \item policy add \$truth1 \$truth2...: after a user has added all the
   truths, per can start to create policies. Per can combine the truths
   in any way they wish. It is also possible to just store one truth in
   a policy, but this is not recommended since it defies the design of
   the application.
 \item policy: shows all created policies.
 \item truth: shows all created truths.
 \item server: shows all added servers.
 \item publish \$secret: if the user is finished per can publish the
   configuration. The application will then generate the recovery
   document with the provided information and secret. Afterwards, it
   will upload the recovery document on every server that was used. For
   recovery, the user only needs to remember any one of the servers.
 \end{itemize}
 
 Below is an example transcript of an interaction with the splitter:
 
 \begin{lstlisting}
 $ anastasis-splitter --me=identity.json
 anastasis-splitter> server add $URL1
 version: 1.0
 annual fee: 4.99 KUDOS,
 available policy methods: sms
 Server #1 available
 anastasis-splitter> server add $URL2
 version: 1.0
 annual fee: 3.99 KUDOS,
 available policy methods: sms, question
 Server #2 available
 anastasis-splitter> truth add server#1 sms +492452526
 Truth #1 added for server #1
 anastasis-splitter> truth add server#2 mail "hoehenweg 80, Biel"
 Sorry, server #2 does not support 'mail'
 anastasis-splitter> truth add question "favorite color" "red"
 Truth #2 added
 anastasis-splitter> policy add truth#1 truth#2
 Policy #1 defined
 anastasis-splitter> policy
 Policy#1: #truth#1 #truth2
 anastasis-splitter> truth
 truth#1: server#1 sms  +492452526
 truth#2: server#2 question "favorite color" <OMITTED>
 anastasis-splitter> truth --secrets
 truth#1: sms  +492452526
 truth#2: question "favorite color" "red"
 anastasis-splitter> server
 server#1: http://anastasis.example.com/ methods: sms,
 insured up to: 420 KUDOS, cost: 0.4 KUDOS
 anastasis-splitter> publish
 Server#1 failure: 402 payment required:
 payto://pay/ABALSASDFA KUDOS:0.3
 Server#2 failure: 402 payment required:
 payto://pay/ABALSAADAS KUDOS:0.5
 Total: 0.8 KUDOS
 # Here: taler-wallet-cli payto://pay/ABALASDFA used to pay!
 anastasis-splitter> publish
 Server#2 failure: 402 payment required
 # Here: taler-wallet-cli payto://pay/ABASDFASDF used to pay!
 anastasis-splitter> publish "my super secret"
 Thank you for using Anastasis.
 $
 \end{lstlisting}
 
 \subsubsection{Anastasis assembler}
 
 The user starts the assembler by passing a JSON document with their
 unforgettable identity attributes (name, social security number, ...).
 They also must pass the URL of an escrow provider which stores their
 recovery document, as well as the requested version of the recovery
 document. The assembler will then download and decrypt the recovery
 document and begin the recovery process.
 
 
 The following commands are available:
 \begin{itemize}
 \item truth: shows all available authorization challenges
   from the recovery document and their status (``(-)'' not solved, ``(+)'' solved)
 \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 an authorization process which
   needs interaction with external services like SMS or email. It shows
   the instructions to follow to authorize release of the share.
 \item answer \$truth \$answer: this command tries to answer the
   selected challenge with the provided answer. The application will
   check the answer and give a feedback to the user. Every time a
   challenge is solved, the client API will check if as a result any of
   the policies is completely satisfied.  If any policy was completely
   satisfied, the assembler will print out the recovered core secret
   and exit.
 \end{itemize}
 
 Below is an example transcript of an interaction with the assembler:
 
 \begin{lstlisting}
 $ anastasis-assembler --import https://anastasis.example.com/
 --policy-version=42 --me=identity.json
 anastasis-assembler> truth
 truth#1(-): KUDOS 0.0 question "favorite color"
 truth#2(-): KUDOS 0.4 sms
 truth#3(-): KUDOS 2.6 post
 anastasis-assembler> policies
 policy#1: KUDOS 0.4 truth#1 truth#2 missing
 policy#2: KUDOS 3.0 truth#1 truth#2 truth#3 missing
 anastasis-assembler> try truth#2
 payto://pay/BASDFASD
 # SMS arrives asynchronously
 anastasis-assembler> answer truth#2 1234
 Success truth#2
 anastasis-assembler> answer truth#1 "blue"
 Failed truth#1
 anastasis-assembler> truth
 truth#1(-): KUDOS 0.0 question "favorite color"
 truth#2(+): KUDOS 0.4 sms
 truth#3(-): KUDOS 2.6 post
 anastasis-assembler> policies
 policy#1: KUDOS 0.0 truth#1 missing
 policy#2: KUDOS 2.6 truth#1 truth#3 missing
 anastasis-assembler> answer truth#2 "red"
 Success truth#2
 //One of the policies was solved successfully and the secret is recovered.
 Secret was: "my super secret"
 $
 \end{lstlisting}
 
 
 
 \subsection{Libraries} \label{sec:libraries}
 
 In this section the libraries used by Anastasis are presented.
 
 \subsubsection{GNU Taler}
 
 GNU Taler is one of the main reasons why we started to implement
 Anastasis, since the application needs a system to back up the private
 keys of their users.  ``GNU Taler is a privacy-preserving payment
 system. Customers can stay anonymous, but merchants can not hide their
 income through payments with GNU Taler. This helps to avoid tax
 evasion and money laundering.''~\cite{gnu_taler}
 
 To operate GNU Taler the user needs to install an electronic
 wallet. Backups of the wallet are secured with a secret key. Here
 comes Anastasis into play, Anastasis will secure this secret key for
 the user.
 
 In our implementation GNU Taler is also our payment system. We decided
 to use GNU Taler because both Anastasis and GNU Taler are privacy
 preserving applications. If we for example used credit cards for
 payments the user would no longer be anonymous which is helpful for
 the security of Anastasis as it allows us to use the user's name in
 the user's identity attributes.  GNU Taler is also a GNU package
 and Free Software.~\cite{gnu_taler}
 \newpage
 \subsubsection{PostgreSQL}
 
 PostgreSQL is a Free/Libre Open Source object-relational
 database. PostgreSQL has over 30 years of active development which
 makes it a stable and reliable software.
 
 We use PostgreSQL as our database on the Anastasis server. We decided
 to use PostgreSQL because it is an open source and lightweight
 software which has a big community.  This means there are a lot of
 helpful documentations and forums.~\cite{postgresql}
 
 \subsubsection{Libcurl}
 
 Libcurl is a libre URL transfer library. Libcurl supports a wide range
 of protocols and a C API. Libcurl is also ready for IPv6 and SSL
 certificates.
 
 For Anastasis we use Libcurl to generate the client-side HTTP
 requests. We decided to use Libcurl because it is also written in C
 and free software. The software is also well supported and has a good
 documentation.  This makes the integration in our application
 easy.~\cite{libcurl}
 
 \subsubsection{GNU Libmicrohttpd}
 
 GNU libmicrottpd is a small C library which provides an easy way to
 run a HTTP server.  We use GNU Libmicrohttpd in Anastasis to provide a
 simple webserver. The main reason why we did not use apache or nginx
 is that we do not need a standalone webserver. The Anastasis webserver
 just must handle some API requests, a standalone webserver is not
 needed for that and would make the infrastructure more complex to
 maintain and develop.  GNU Libmicrohttpd is also a GNU package
 and Free Software.~\cite{libmicrohttpd}
 
 \subsection{Testing}
 
 To test our application, we used the GNU Taler testing library as our
 foundation for t of our testings.  This library allows you to create testing instances of
 both the Anastasis application and the GNU Taler payment system. We
 implemented unit tests for the crypto functions and the database operations.
 The following four tests are independently performed.
 
 \begin{itemize}
 \item The first test is the database test. The Anastasis testing library first connects to a test database, this database is only used for the testing, we never test on the live database. The test first deletes and recreates the database. After that it will perform several unit tests to check if the database queries of the application are working as intended.
 \item Next we test the Anastasis crypto API, it tests all the
 cryptographic functions used in the API with unit tests.
 The most important part is  that the recreation of the keys
 and decryption works as intended.
 \item After the basic parts of the application are tested the client
 will test every request in the Anastasis server API. For this we need the
 Taler Testing library. The Taler testing library will start an instance
 of the Anastasis webserver and a GNU Taler merchant service. The merchant
 service is needed to process the payment operations. The testing library
 will now send a request to every end point of the Anastasis REST API. It will
 check if every response of the REST API is as intended.
 \item At the end the whole application flow is tested. For this
 we need to start a Anastasis server, Taler merchant and Taler exchange instance.
 The library will now perform a full secret split and secret recovery.
 This test is successful if the provided core secret at the begin, matches the
 recovered core secret.
 \end{itemize}