[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-anastasis] branch master updated: work on design, client architec
|
From: |
gnunet |
|
Subject: |
[taler-anastasis] branch master updated: work on design, client architecture and implementation texts |
|
Date: |
Sun, 07 Jun 2020 13:29:03 +0200 |
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 db4e6e7 work on design, client architecture and implementation texts
db4e6e7 is described below
commit db4e6e7edd5d52c0e5e000276d5a997dbf6faa13
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Jun 7 13:29:00 2020 +0200
work on design, client architecture and implementation texts
---
doc/thesis/client_architecture.tex | 67 +++++--
doc/thesis/design.tex | 97 ++++++----
doc/thesis/implementation.tex | 373 ++++++++++++++++++++++++++++++-------
3 files changed, 424 insertions(+), 113 deletions(-)
diff --git a/doc/thesis/client_architecture.tex
b/doc/thesis/client_architecture.tex
index 427d0fd..93b9629 100644
--- a/doc/thesis/client_architecture.tex
+++ b/doc/thesis/client_architecture.tex
@@ -1,20 +1,29 @@
\subsection{Client architecture}
-The Anastasis client architecture consists of two components. A client
+The Anastasis client architecture consists of two main components. A client
API which communicates with the server and a command line application
which interacts with the user. The structure of these two components
-is shown here.
+is shown in Figure~\ref{fig:anastasis:client}.
-The Anastasis Client uses three APIs. The Crypto API which provides
-the different 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.
+\begin{figure}[H]
+ \centering
+ FIXME
+ \caption{Anastasis client architecture}
+ \label{fig:anastasis:client}
+\end{figure}
+
+The Anastasis client implementation includes three distinctive APIs: a
+{\em Crypto API} which provides the different cryptographic functions,
+a {\em Service API} which sends the request to the server and the {\em
+ Client API} which manages the main data structures and provides an
+abstraction for the application.
\subsubsection{Crypto API}
-Following is a list over the most important data structures in the
-crypto API.
+The most important data structures in the crypto API are the following:
+\begin{itemize}
+ \item
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
@@ -26,6 +35,7 @@ struct kdf_id
}
\end{lstlisting}
+\item
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
@@ -34,6 +44,7 @@ struct private_key
}
\end{lstlisting}
+\item
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
@@ -42,6 +53,7 @@ struct public_key
}
\end{lstlisting}
+\item
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
@@ -50,6 +62,7 @@ struct truth_key
}
\end{lstlisting}
+\item
Anastasis needs different symmetric keys to encrypt data for example, the
recovery document. These symmetric keys are all 256-bit large hashcodes. These
symmetric keys are generated through the key routine defined in Implementation
Key usage.
\begin{lstlisting}
struct symmetric_key
@@ -58,6 +71,7 @@ struct symmetric_key
}
\end{lstlisting}
+\item
Each policy has a separate 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}
@@ -67,6 +81,7 @@ struct policy_key
}
\end{lstlisting}
+\item
Every truth object contains a key\_share. A key\_share is a 256-bit random
generated bit sequence.
\begin{lstlisting}
struct key_share
@@ -75,6 +90,7 @@ struct key_share
}
\end{lstlisting}
+\item
Before every encryption a random 256-bit large nonce is generated. This gives
the encrpytion algorithm a random factor.
\begin{lstlisting}
struct nonce
@@ -83,6 +99,7 @@ struct nonce
}
\end{lstlisting}
+\item
To use AES-256 GCM an IV must be generated. It is generated with an HKDF over
a salt the kdf\_id and a symmetric key.
\begin{lstlisting}
struct iv
@@ -91,6 +108,7 @@ struct iv
}
\end{lstlisting}
+\item
The aes\_tag is generated after each encryption, it is later used to check the
integrity of the data.
\begin{lstlisting}
struct aes_tag
@@ -98,10 +116,19 @@ struct aes_tag
hashcode; //128 bit
}
\end{lstlisting}
+\end{itemize}
+
+The functions of the crypto API basically provide the canonical set of
+cryptographic operations (hash, encrypt, decrypt, etc.) over these
+basic data structures.
\subsubsection{Client API}
-Following is a list over the most important data structures in the client API.
\\
+
+The most important data structures in the client API are the following:
+
+\begin{itemize}
+ \item
The secret share data structure is used to upload a new recovery document.
\begin{lstlisting}
struct secret_share
@@ -119,6 +146,7 @@ struct secret_share
\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}
+ \item
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
@@ -136,7 +164,7 @@ struct recovery_information
\item salt: this is the salt used for the generation of the policy keys. The
salt is a 512-bit value.
\end{itemize}
-
+\item
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 completely.
\begin{lstlisting}
@@ -159,6 +187,7 @@ struct recovery
\item recovery\_information: as previously mentioned this data structure holds
the downloaded recover document to process within the recovery
\end{itemize}
+\item
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
@@ -177,6 +206,8 @@ struct truth
\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 successful
authentication.
\end{itemize}
+
+\item
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
@@ -192,6 +223,7 @@ struct policy
\item salt: defines the salt used to create the policy\_key.
\end{itemize}
+\item
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
@@ -207,6 +239,7 @@ struct decryption_policy
\item salt: defines the salt which was used to create this policy\_key.
\end{itemize}
+\item
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.
@@ -229,9 +262,19 @@ struct challenge
\item key\_share: After each successful 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 favourite colour?” or” An SMS was sent
to the number +41...... please provide the pin”.
\end{itemize}
+\end{itemize}
+
+The functions of the client API basically provide a way to
+backup a core secret by providing user's identity attributes,
+the secret and constructing the policies, as well as a way
+to recover a core secred by providing the user's identity
+attributes and then satisfying the authentication challenges.
+
\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.
+API of the server. The client has implemented functions for every
+endpoint.
+For more details see REST API documentation in
+Section~\ref{sec:restAPI}. % FIXME: create appendix!
diff --git a/doc/thesis/design.tex b/doc/thesis/design.tex
index 208df7c..59ac7ea 100644
--- a/doc/thesis/design.tex
+++ b/doc/thesis/design.tex
@@ -113,31 +113,51 @@ details of each component are explained later.
\subsection{Client Application Command Line Interface (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.
+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}
-\textbf{Available commands: }
+The user starts the assembler by passing a JSON document with their
+unforgetable 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 the server 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. He needs to specify the method used and
the
-truth for the method, for example the phone number or the question and the
answer.
-The programm will check if the server supports the provided method before
uploading.
-\item policy add \$truth1 \$truth2... : after the user has added all the
truths he can start to create policies. He can combine the truths in any way he
wishes. 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 he 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 used server.
+\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 programm 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 flow of the application. \\
+
+Below is an example transcript of an interaction with the splitter:
+
\begin{lstlisting}
-//The user starts the programm and passes a json document
-//containing the unforgetable secret(name, social security number..)
$ anastasis-splitter --me=identity.json
anastasis-splitter> server add $URL1
version: 1.0
@@ -186,22 +206,35 @@ $
\subsubsection{Anastasis assembler}
-\textbf{Available commands:} \\
+The user starts the assembler by passing a JSON document with their
+unforgetable 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 truths in the recovery document and its
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 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 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. Everytime 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 flow of the application. \\
+
+Below is an example transcript of an interaction with the assembler:
+
\begin{lstlisting}
-//The user starts the programm and passes a json document
-//containing the unforgetable secret(name, social security number..),
-//a url to a escrow provider which stores his recovery document and
-//the requested version of the recovery document. The client will then
-//download the recovery document within the startup
$ anastasis-assembler --import https://anastasis.example.com/
--policy-version=42 --me=identity.json
anastasis-assembler> truth
diff --git a/doc/thesis/implementation.tex b/doc/thesis/implementation.tex
index e6d436d..7012449 100644
--- a/doc/thesis/implementation.tex
+++ b/doc/thesis/implementation.tex
@@ -1,22 +1,44 @@
-Argon2\section{Implementation}
-The whole Anastasis software is written in C. We decided to use C because of
the various cryptographic libraries and the available documentations.
-Additionally, GNU Taler and Sync which are working close with Anastasis are
also written in C. This makes the integration of our application much easier.\\
-The whole Anastasis application consists of multiple components. On the
following
-graphic is an overview over all the components in Anastasis. \\
+\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} gives an overview over all the
+components of Anastasis.
+
\begin{figure}[H]
\centering
\includegraphics[scale=0.5]{images/system-architecture.png}
\caption{Secret split process}
\label{fig:secret_split}
\end{figure}
-On the left are some of the planed 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 planned and not
part of this thesis. \\
-At the bottom section are the external libraries used for the project. These
libraries are presented in the section Libraries. \\
-In the centre is the core implementation of Anastasis.
+
+In the center is the core implementation of Anastasis.
+
+On the left are some of the planed 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}.
+
\subsection{Application flow}
-This section describes a happy flow of the two protocols of Anastasis, key
splitting and key recovery.
+
+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}
@@ -25,17 +47,49 @@ This section describes a happy flow of the two protocols of
Anastasis, key split
\end{figure}
\begin{enumerate}
-\item The user selects a new escrow provider on which he 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, he 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 a UUID the client generated(POST /truth/\$UUID).
-\item In this scenario the client has not jet paid for the upload. This means
the server will respond with the status code 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 he thinks that he has setup
a sufficient amount of authentication methods. The user can now combine these
providers to create policies. For example he has stored three truth objects on
different providers. This means he can now define combinations with these
providers for example A+B, A+C and B+C. This means he has three ways to recover
his secret.
-\item After the user has generated the policies the client will generate a
recovery document. The recovery document contains a list of all UUID'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
distributed and has no single point of failure.
+\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 a UUID the client
+ generated (POST /truth/\$UUID).
+\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 UUID'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}
\subsubsection{Secret recovery}
+
+Figure~\ref{fig:recovery_process} illustrates the recovery process.
\begin{figure}[H]
\centering
\includegraphics[scale=0.5]{images/recovery_process.png}
@@ -43,66 +97,196 @@ This section describes a happy flow of the two protocols
of Anastasis, key split
\label{fig:recovery_process}
\end{figure}
\begin{enumerate}
-\item The user selects a server on which he 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, he will download the recovery
document. At this point he can define if he wants a specific version or the
latest version of the recovery document. In the graphic 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 him in the
recovery document.(GET /truth/\$UUID?resonse=\$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 jet
paid. After the payment with our payment provider GNU Taler the user can resend
the request.
-After each successfuly solved challenge the client will check if one of the
policies is fulfilled. If one of the policies is finished, the client will
decrypt the core secret and provide it to the user.
+\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/\$UUID?resonse=\$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 successfuly 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}
-This graphic shows the flow for a secure question. 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/\$UUID). The
server would then notify the user that he will answer out of bounds. After that
the user would have to provide for example the pin sent to him by SMS with the
same request as before(GET /truth/\$UUID?resonse=\$RESONSE).
+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/\$UUID). 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/\$UUID?resonse=\$RESPONSE).
+
+
+\subsection{Libraries} \label{sec:libraries}
-\subsection{Libraries}
-In this section the libraries used for Anastasis are presented.
+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. This
wallet is secured with a private key. Here comes Anastasis into play, Anastasis
will secure this private 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 a core part of Anastasis.
-Additionally GNU Taler is in the GNU package, this means it will always remain
free software.\cite{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}
+
\subsubsection{PostgreSQL}
-PostgreSQL is an open source object-relational database. PostgreSQL has over
30 years of active development which makes it a very 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}
+
+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 free 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 very easy.\cite{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. Since GNU Libmicrohttpd is also part of
the GNU project it will remain free software.\cite{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.
-This library allows you to create testing instances of both the Anastasis
application and the GNU Taler payment system. We implemented unit tests for
every command in our application. A simplified test flow would be the following.
+
+To test our application, we used the GNU Taler testing library as our
+foundation. This library allows you to create testing instances of
+both the Anastasis application and the GNU Taler payment system. We
+implemented unit tests for every command in our application. A
+simplified test flow would be the following:
+
\begin{enumerate}
-\item The testing library starts an instance of the Anastasis server and a GNU
Taler merchant and exchange service.
-\item The Anastasis server will connect to a test database only used for
testing.
-\item The testing library first sets up the database and tests if it can
create records.
-\item Next we test the Anastasis crypto API, it tests all the cryptographic
functions used in the API. 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. It will check if the server responds
the intended way and if the status codes are correct.
-\item At the end the whole application flow is tested, the testing library
will first perform a secret split and then a secret recovery. It tests if the
core functionality of the application works and if the secret is recovered
correctly.
+\item The testing library starts an instance of the Anastasis server
+ and a GNU Taler merchant and exchange service.
+\item The Anastasis server will connect to a test database only used
+ for testing.
+\item The testing library first sets up the database and tests if it
+ can create records.
+\item Next we test the Anastasis crypto API, it tests all the
+ cryptographic functions used in the API. 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. It will check
+ if the server responds the intended way and if the status codes are
+ correct.
+\item At the end the whole application flow is tested, the testing
+ library will first perform a secret split and then a secret
+ recovery. It tests if the core functionality of the application
+ works and if the secret is recovered correctly.
\end{enumerate}
+% FIXME: the above does not seem accurate;
+% unit tests for crypto and simple HTTP REST
+% tests do not necessarily preceede the
+% integration tests done with the testing library!
\subsection{Cryptography}
-When a user needs to interact with Anastasis, the system first derives some
key material, but not the master secret, from the user’s identifier using
different HKDFs. These HKDFs are salted using the respective escrow provider’s
server salt, which ensures that the accounts for the same user cannot be easily
correlated across the various Anastasis servers. \\
-\\
-Each Anastasis server uses an EdDSA account key to identify the account of the
user. The account private key is derived from the user’s identifier using a
computationally expensive cryptographic hash function. Using an expensive hash
algorithm is assumed to make it infeasible for a weak adversary to determine
account keys by brute force (without knowing the user’s identifier). However,
it is assumed that a strong adversary performing a targeted attack can compute
the account key pair. \\
-\\
-The public account key is Crockford base32-encoded in the URI to identify the
account, and used to sign requests. These signatures are also provided in
base32-encoding and transmitted using the HTTP header
“Anastasis-Account-Signature”. \\
-\\
-When confidential data is uploaded to an Anastasis server, the respective
payload is encrypted using AES-GCM with a symmetric key and initialization
vector derived from the identifier and a high-entropy nonce. The nonce and the
GCM tag are prepended to the ciphertext before being uploaded to the Anastasis
server. This is done whenever confidential data is stored with the server.\\
-\\
-The core secret of the user is (AES) encrypted using a symmetric master key.
Recovering this master key requires the user to satisfy a policy. Policies
specify a set of escrow methods, each of which leads the user to a key share.
Combining those key shares (by hashing) allows the user to obtain a policy key,
which can be used to decrypt the master key. There can be many policies,
satisfying any of these will allow the user to recover the master key. A
recovery document contains the encry [...]
+
+When a user needs to interact with Anastasis, the system first derives
+some key material, but not the master secret, from the user’s
+identifier using different HKDFs. These HKDFs are salted using the
+respective escrow provider’s server salt, which ensures that the
+accounts for the same user cannot be easily correlated across the
+various Anastasis servers.
+
+Each Anastasis server uses an EdDSA account key to identify the
+account of the user. The account private key is derived from the
+user’s identifier using a computationally expensive cryptographic hash
+function. Using an expensive hash algorithm is assumed to make it
+infeasible for a weak adversary to determine account keys by brute
+force (without knowing the user’s identifier). However, it is assumed
+that a strong adversary performing a targeted attack can compute the
+account key pair.
+
+The public account key is Crockford base32-encoded in the URI to
+identify the account, and used to sign requests. These signatures are
+also provided in base32-encoding and transmitted using the HTTP header
+\texttt{Anastasis-Account-Signature}.
+
+When confidential data is uploaded to an Anastasis server, the
+respective payload is encrypted using AES-GCM with a symmetric key and
+initialization vector derived from the identifier and a high-entropy
+nonce. The nonce and the GCM tag are prepended to the ciphertext
+before being uploaded to the Anastasis server. This is done whenever
+confidential data is stored with the server.
+
+The core secret of the user is (AES) encrypted using a symmetric
+master key. Recovering this master key requires the user to satisfy a
+policy. Policies specify a set of escrow methods, each of which leads
+the user to a key share. Combining those key shares (by hashing)
+allows the user to obtain a policy key, which can be used to decrypt
+the master key. There can be many policies, satisfying any of these
+will allow the user to recover the master key. A recovery document
+contains the encrypted core secret, a set of escrow methods and a set
+of policies.
\subsection{Key Derivations}
-EdDSA and ECDHE public keys are always points on Curve25519 and represented
using the standard 256-bit Ed25519 compact format. The binary representation is
converted to Crockford Base32 when transmitted inside JSON or as part of URLs.\\
-\\
-To start, a user provides their private, unique and unforgettable identifier
as a seed to identify their account. For example, this could be a social
security number together with their full name. Specifics may depend on the
cultural context, in this document we will simply refer to this information as
the identifier.\\
-\\
-This identifier will be first hashed with Argon2, to provide a kdf\_id which
will be used to derive other keys later. The Hash must also include the
respective server\_salt. This also ensures that the kdf\_id is different on
each server. The use of Argon2 and the respective server\_salt is intended to
make it difficult to brute-force kdf\_id values and help protect user’s
privacy. Also this ensures that the kdf\_ids on every server differs. However,
we do not assume that the identifier o [...]
+
+EdDSA and ECDHE public keys are always points on Curve25519 and
+represented using the standard 256-bit Ed25519 compact format. The
+binary representation is converted to Crockford Base32 when
+transmitted inside JSON or as part of URLs.
+
+To start, a user provides their private, unique and unforgettable
+identifier as a seed to identify their account. For example, this
+could be a social security number together with their full
+name. Specifics may depend on the cultural context, in this document
+we will simply refer to this information as the identifier.
+
+This identifier will be first hashed with Argon2, to provide a kdf\_id
+which will be used to derive other keys later. The Hash must also
+include the respective server\_salt. This also ensures that the
+kdf\_id is different on each server. The use of Argon2 and the
+respective server\_salt is intended to make it difficult to
+brute-force kdf\_id values and help protect user’s privacy. Also this
+ensures that the kdf\_ids on every server differs. However, we do not
+assume that the identifier or the kdf\_id cannot be determined by an
+adversary performing a targeted attack, as a user’s identifier is
+likely to always be known to state actors and may likely also be
+available to other actors.
+
\begin{lstlisting}
user_identifier_create(identifier, server_salt, keysize)
{
@@ -118,9 +302,21 @@ user_identifier_create(identifier, server_salt, keysize)
\textbf{keysize}: The desired output size of the KDF, here 32 bytes. \\
\subsection{Verification}
-For users to authorize “policy” operations we need an EdDSA key pair. As we
cannot assure that the corresponding private key is truly secret, such policy
operations must never be destructive: Should an adversary learn the private
key, they could access (and with the kdf\_id decrypt) the user’s policy (but
not the core secret), or upload a new version of the encrypted recovery
document (but not delete an existing version). \\
-\\
-For the generation of the private key we use the kdf\_id as the entropy
source, hash it to derive a base secret which will then be processed to fit the
requirements for EdDSA private keys. From the private key we can then generate
the corresponding public key. Here, “ver” is used as a salt for the HKDF to
ensure that the result differs from other cases where we hash kdf\_id. \\
+
+For users to authorize “policy” operations we need an EdDSA key
+pair. As we cannot assure that the corresponding private key is truly
+secret, such policy operations must never be destructive: Should an
+adversary learn the private key, they could access (and with the
+kdf\_id decrypt) the user’s policy (but not the core secret), or
+upload a new version of the encrypted recovery document (but not
+delete an existing version).
+
+For the generation of the private key we use the kdf\_id as the
+entropy source, hash it to derive a base secret which will then be
+processed to fit the requirements for EdDSA private keys. From the
+private key we can then generate the corresponding public key. Here,
+“ver” is used as a salt for the HKDF to ensure that the result differs
+from other cases where we hash kdf\_id.
\begin{lstlisting}
eddsa_keys_create (kdf_id, salt, keysize)
{
@@ -154,7 +350,13 @@ digest[31] &= 0xf8;
\subsection{Encryption}
-For symmetric encryption of data, we use AES256-GCM. For this we need a
symmetric key and an initialization vector (IV). To ensure that the symmetric
key changes for each encryption operation, we compute the key material using an
HKDF over a nonce and the kdf\_id. Additionally, a salt is added so the
different encryption keys differ fundamentally. For example for the recovery
document key the salt "erd" is added. \\
+For symmetric encryption of data, we use AES256-GCM. For this we need
+a symmetric key and an initialization vector (IV). To ensure that the
+symmetric key changes for each encryption operation, we compute the
+key material using an HKDF over a nonce and the kdf\_id. Additionally,
+a salt is added so the different encryption keys differ
+fundamentally. For example for the recovery document key the salt
+"erd" is added.
\begin{lstlisting}
encryption_key_create(kdf_id, salt, nonce)
@@ -183,7 +385,13 @@ return iv,key
The keys we have generated are then used to encrypt the \textbf{recovery
document} and the \textbf{key\_share} of the user.
\subsubsection{Encryption}
-Before every encryption a 32-byte nonce is generated. From this the symmetric
key is computed as described above. We use AES256-GCM for the encryption of the
recovery document and the key\_share. To ensure that the key derivation for the
encryption of the recovery document differs fundamentally from that of an
individual key share, we use different salts (“erd” and “eks” respectively).
+
+Before every encryption a 32-byte nonce is generated. From this the
+symmetric key is computed as described above. We use AES256-GCM for
+the encryption of the recovery document and the key\_share. To ensure
+that the key derivation for the encryption of the recovery document
+differs fundamentally from that of an individual key share, we use
+different salts (“erd” and “eks” respectively).
\begin{lstlisting}
encrypt(kdf_id, data, salt)
@@ -218,7 +426,10 @@ recovery_document_encrypt(kdf_id, recovery_document)
aes\_gcm\_tag.
\subsubsection{Signatures}
-The EdDSA keys are used to sign the data sent from the client to the server.
Everything the client sends to server is signed. The following algorithm is
equivalent for Anastasis-Policy-Signature.
+
+The EdDSA keys are used to sign the data sent from the client to the
+server. Everything the client sends to server is signed. The following
+algorithm is equivalent for Anastasis-Policy-Signature.
\begin{lstlisting}
(anastasis-account-signature) = eddsa_sign(h_body, eddsa_priv)
@@ -244,5 +455,29 @@ ver_res = eddsa_verifiy(version,
anastasis-account-signature, eddsa_pub)
\textbf{ver\_res}: A Boolean value. True: Signature verification passed,
False: Signature verification failed. \\
\subsection{Availability Considerations}
-Anastasis considers two main threats against availability. First, the
Anastasis server operators must be protected against denial-of-service attacks
where an adversary attempts to exhaust operator’s resources. The API protects
against these attacks by allowing operators to set fees for all operations.
Furthermore, all data stored comes with an expiration logic, so an attacker
cannot force servers to store data indefinitely.
-A second availability issue arises from strong adversaries that may be able to
compute the account keys of some user. While we assume that such an adversary
cannot successfuly authenticate against the truth, the account key does
inherently enable these adversaries to upload a new policy for the account.
This cannot be prevented, as the legitimate user must be able to set or change
a policy using only the account key. To ensure that an adversary cannot exploit
this, policy uploads first o [...]
+
+Anastasis considers two main threats against availability. First, the
+Anastasis server operators must be protected against denial-of-service
+attacks where an adversary attempts to exhaust operator’s
+resources. The API protects against these attacks by allowing
+operators to set fees for all operations. Furthermore, all data stored
+comes with an expiration logic, so an attacker cannot force servers to
+store data indefinitely. A second availability issue arises from
+strong adversaries that may be able to compute the account keys of
+some user. While we assume that such an adversary cannot successfuly
+authenticate against the truth, the account key does inherently enable
+these adversaries to upload a new policy for the account. This cannot
+be prevented, as the legitimate user must be able to set or change a
+policy using only the account key. To ensure that an adversary cannot
+exploit this, policy uploads first of all never delete existing
+policies, but merely create another version. This way, even if an
+adversary uploads a malicious policy, a user can still retrieve an
+older version of the policy to recover access to their data. This
+append-only storage for policies still leaves a strong adversary with
+the option of uploading many policies to exhaust the Anastasis
+server’s capacity. We limit this attack by requiring a policy upload
+to include a reference to a payment identifier from a payment made by
+the user. Thus, a policy upload requires both knowledge of the
+identity and making a payment. This effectively prevents and adversary
+from using the append-only policy storage from exhausting Anastasis
+server capacity.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-anastasis] branch master updated: work on design, client architecture and implementation texts,
gnunet <=