[taler-anastasis] branch master updated: client architecture

[gnunet]

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

ds-meister pushed a commit to branch master
in repository anastasis.

The following commit(s) were added to refs/heads/master by this push:
     new 2dc2766  client architecture
2dc2766 is described below

commit 2dc276602e7833b1db3626cfb9cb3f7da05e651a
Author: Dominik Meister <dominiksamuel.meister@students.bfh.ch>
AuthorDate: Sat Jun 6 17:32:20 2020 +0200

    client architecture
---
 doc/thesis/client_architecture.tex | 212 ++++++++++++++++++++++++++++++++++++-
 doc/thesis/project_management.tex  |  19 ++--
 2 files changed, 217 insertions(+), 14 deletions(-)

diff --git a/doc/thesis/client_architecture.tex 
b/doc/thesis/client_architecture.tex
index 4b99ba1..986ced6 100644
--- a/doc/thesis/client_architecture.tex
+++ b/doc/thesis/client_architecture.tex
@@ -6,11 +6,221 @@ The Anastasis Client uses three APIs. The Crypto API which 
provides the differen
 cryptographic functions, a service API which sends the request to the server 
and the main client API which manages the communication between the different 
APIs.
 
 \subsubsection{Crypto API}
+Following is a list over the most important data structures in the crypto API.
+
+The kdf\_id is a hash code which was generated with Argon2. The entropy source 
is the user's unforgettable secret. The kdf\_id is used to create various 
key's, for more details see Implementation Cryptography
+\begin{lstlisting}
+struct kdf_id
+{ 
+  Hashcode; //512Bit
+} 
+\end{lstlisting}
+
+The private key is used to sign the data and check the signature later. It is 
a 256 bit eddsa private key. It is generated with the kdf\_id as entropy source.
+\begin{lstlisting}
+struct private_key
+{ 
+  eddsa_private_key;
+} 
+\end{lstlisting}
+
+The public key is used as the user identification on the different providers. 
It is generated from the private\_key.
+\begin{lstlisting}
+struct public_key
+{
+  eddsa_public_key;
+}
+\end{lstlisting}
+
+The truth\_key is a randomly generated AES-256 GCM key. It is used to encrypt 
the user specifiy data in the truth object.
+\begin{lstlisting}
+struct truth_key
+{
+  key; //256 bit
+}
+\end{lstlisting}
+
+Anastasis needs different symetric keys to encrypt data. For example the 
recovery document. These symetric keys are all 256 bit large hashcodes. These 
symetric keys are generated through the key routine defined in Implementation 
Key usage.
+\begin{lstlisting}
+struct symetric_key
+{
+  hashcode; //256 bit
+}
+\end{lstlisting}
+
+Each policy has a seperate policy\_key. The key is used to encrypt the 
master\_key.
+The policy\_key is also a AES-256 GCM key. It is generated through the 
combination of a set of key\_shares.
+\begin{lstlisting}
+struct policy_key
+{
+  hashcode; //256 bit
+}
+\end{lstlisting}
+
+Every truth object contains a key\_share. A key\_share is a 256 bit random 
generated bit sequence.
+\begin{lstlisting}
+struct key_share
+{
+  hashcode; //256 bit
+}
+\end{lstlisting}
+
+Before every encryption a random 256 bit large nonce is generated. This gives 
the encrpytion algorithm a random factor.
+\begin{lstlisting}
+struct nonce
+{
+  hashcode; //256 bit
+}
+\end{lstlisting}
+
+To use AES-256 GCM an IV must be generated. It is generated with an HKDF over 
a salt the kdf\_id and a symetric key.
+\begin{lstlisting}
+struct iv
+{
+  hashcode; //128 bit
+}
+\end{lstlisting}
+
+The aes\_tag is generated after each encryption, it is later used to check the 
integrity of the data.
+\begin{lstlisting}
+struct aes_tag
+{
+  hashcode; //128 bit
+}
+\end{lstlisting}
 
-\subsubsection{Service API}
 
 \subsubsection{Client API}
+Following is a list over the most important data structures in the client API. 
\\ 
+The secret share data structure is used to upload a new recovery document.
+\begin{lstlisting}
+struct secret_share
+{
+  kdf_id;      
+  last_etag;   
+  policies;    
+  core_secret;
+}
+\end{lstlisting}
+\begin{itemize}
+\item kdf\_id: is used to compute the account public and private key. The hash 
is 512bit large.
+\item last\_etag: this hash is sent with the recovery document. The server 
will check the hash if the document on the server is the same. This prevents 
unneccessary uploads. The hash is 512 bit large.
+\item policies: is a list of all generated policies the user wants to combine 
into a recovery document.
+\item core\_secret: is the user provided core secret. This is just a binary 
blob so Anastasis does not have a restriction for the user secret. This could 
be a for example a private key or a password the user wants to backup.
+\end{itemize}
+
+The recovery information data structure holds a recovery document. It is 
downloaded within the recovery process and stored inside a recovery data 
structure. 
+\begin{lstlisting}
+struct recovery_information
+{
+  struct decryptption_policies;
+  struct challenges;
+  version;
+  salt;
+}
+\end{lstlisting}
+\begin{itemize}
+\item decryption\_policies: holds all available policies within the downloaded 
recovery document.
+\item challenges: holds all available authentication methods within the 
recovery document.
+\item version: the version of the downloaded recovery document is stored here.
+\item salt: this is the salt used for the generation of the policy keys. The 
salt is a 512 bit value.
+\end{itemize}
+
+
+The recovery data structure is generated at the start of a secret recovery. It 
contains all available policies and lists which challenges are solved. Through 
this 
+struct the client can check if a policy was solved completly.
+\begin{lstlisting}
+struct recovery 
+{
+  kdf_id;
+  version;
+  provider_url;
+  salt;
+  solved_challenges;
+  struct recovery_information;
+}
+\end{lstlisting}
+\begin{itemize}
+\item kdf\_id: is used to compute the account public and private key. The hash 
is 512bit large.
+\item version: hold the user desired version he wishes to download. This can 
be null then the client downloads the latest version.
+\item provider\_url: the client will download the recovery document from this 
provider url.
+\item salt: this is the salt of the provider specified in provider\_url. 
+\item solved\_challenges: this is a list of all solved challenges. This list 
is updated after each successfull authentication. This allows the client to 
check if a policy is solved.
+\item recovery\_information: as previously mentioned this data structure holds 
the downloaded recover document to process within the recovery
+\end{itemize}
+
+A truth data structure is used to upload a new authentication method to a 
provider. It is identified by a UUID which the user creates. The truth data 
structure is only used for the secret share process and not for the recovery.
+\begin{lstlisting}
+struct truth
+{
+  uuid;
+  method;
+  mime_type;
+  encrypted_truth;
+  encrypted_key_share;  
+}
+\end{lstlisting}
+\begin{itemize}
+\item uuid: the uuid is the identification of the truth object. The truth 
objects are not linked to the user. A list of these uuids are stored inside the 
recovery document, with this the user data is more anonymous.
+\item method: this defines which method the user chose to configure, for 
example SMS, email, secure question.
+\item mime\_type: this defines in which format the truth was safed, for 
example jpeg, png, txt, json.
+\item encrypted\_truth: the encrypted truth holds the authentication specific 
data. It holds for example the hashed answer and the question. It is encrypted 
with the specific truth\_key which is stored inside the recovery\_document.
+\item encrypted\_key\_share: this is the key\_share protected by this truth. 
It is encrypted with a key which was derived with the kdf\_id of the user. The 
server will later send this key\_share to the user upon successfull 
authentication.
+\end{itemize}
+The policy data structure is used to create new policies to combine them into 
the recovery document. The policy data structure is only used for the secret 
share process.
+\begin{lstlisting}
+struct policy
+{
+ truths;
+ policy_key;
+ salt;
+}
+\end{lstlisting}
+\begin{itemize}
+\item truths: every policy has a set of truths which need to solved to recover 
the policy\_key
+\item policy\_key: the policy\_key is created through the combination of the 
differen key\_shares within each of the truth objects. It is later used to 
encrypt the master\_key.
+\item salt: defines the salt used to create the policy\_key.
+\end{itemize}
+
+The decryption\_policy data structure is used in the recovery process. It has 
slightly different values as the policy structure.
+\begin{lstlisting}
+struct decryption_policy
+{
+  uuids;
+  encrypted_master_key;
+  salt;  
+}
+\end{lstlisting}
+\begin{itemize}
+\item uuids: is a list of uuids which need to be solved to recreate the policy 
key. Each uuid has a coresponding challenge.
+\item encrypted\_master\_key: holds an encrypted version of the master\_key 
which was used to encrypt the core secret. In every policy lies the same 
master\_key which was encrypted by the specific policy\_key.
+\item salt: defines the salt which was used to create this policy\_key.
+\end{itemize}
 
+The challenge data structure is used for the several key\_share lookups.
+We named the process of authentication on the providers as challenges.
+It has slightly different variables as the truth data structure.
+\begin{lstlisting}
+struct challenge 
+{ 
+  uuid;
+  url;
+  truth_key;
+  method;
+  key_share;
+  instructions; 
+}
+\end{lstlisting}
+\begin{itemize}
+\item uuid: the identification of the truth on the server.
+\item url: defines the provider url on which the truth was stored.
+\item truth\_key: this key is sent to the server within the authentication 
procedure. The server can decrypt the truth with this key to start the 
authentication.
+\item method: defines the method of this challenge, for example email, SMS, 
secure question.
+\item key\_share: After each successfull authentication the key\_share which 
was sent by the server will be saved within this variable. It is later used to 
recreate a policy\_key.
+\item instructions: this contains a string with the instructions for the user. 
This could for example be: "What is your favorite color?" or "An SMS was sent 
to the number +41...... please provide the pin"
+\end{itemize}
+\subsubsection{Service API}
+The service API is responsible for sending the requests to the REST API of the 
server. The client has implemented functions for every end point. For more 
details see REST API documentation in the appendix.
 
 \subsection{Client Application CLI}
 There are two client applications which interact with the user. First the 
Anastasis splitter and second the Anastasis assembler. The splitter application 
is responsible for the backup of the core secret. The assembler is then 
responsible for the recovery of the secret. \\
diff --git a/doc/thesis/project_management.tex 
b/doc/thesis/project_management.tex
index b869c07..0e15a93 100644
--- a/doc/thesis/project_management.tex
+++ b/doc/thesis/project_management.tex
@@ -2,22 +2,15 @@
 This section describes the project planing of Anastasis. A detailed reflection 
on the work on Anastasis is in the work journal in the appendix.
 \subsection{Project plan}
 The following graphic shows our project plan how we planed to implement 
Anastasis and write our bachelor thesis.
+
 \begin{figure}[H]
-               \includegraphics[scale=0.6]{images/project_plan_anastasis.png}
+               \includegraphics[scale=0.5]{images/project_plan_anastasis.png}
        \caption{Anasasis project plan}
        \label{fig:project_plan_anastasis}
 \end{figure}
 
 \subsection{Project plan reflection}
-This table shows a comparison between the planned time to finish and the 
actual time used. \\ 
-
-insert table \\ 
-
-
-As we can see the development in general took way longer than expected. This
-was caused by several problems within the development. The biggest problem was 
that we had too many problems with the C language exspecially with pointers. 
Another very difficult part was the integration of the GNU Taler System, also 
the system is in active development which means we often had to adjust our 
system.
-Another part we underestimated was the time needed to write the funding 
proposals.
-Additionaly an unexpected offer occured within our thesis. We applied for 
funding last semester and were rejected. But we were informed that we still can 
present our work. Therefore we had to prepare a presentation for this business 
pitch, which also took some unplaned time.
-Because of these reasons we could not implement a complex authentication 
method within Anastasis.
-\subsection{Conclusion}
-As mentioned above we couldnt successfully develop all the required parts of 
the application. We think in the future we need to take our own knowledge more 
into consideration if we plan the next project. We underestimated the 
complexity of certain parts of the application. Additionaly i think we also 
need to improve on proper development and try to be more clear with our naming 
conventions.
+We were able to write our thesis nearly according to our project plan. Within 
the work we decided because of the interest of many businesses to invest more 
time in the business part than in the development. This opened up an 
oppurtunity to make an additional funding proposal. \\
+Because of this reason we could not implement a complex authentication method 
within Anastasis.
+The development of the software otherwise proceeded as planned. The 
development was overall not very fast, since we had to relearn certain aspects 
of the C language.
+Additionaly we had to learn and understand many APIs we used within the 
development. However, this was already taken into account in the planning.

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