[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-anastasis] branch master updated: tables/figures business model,
|
From: |
gnunet |
|
Subject: |
[taler-anastasis] branch master updated: tables/figures business model, appendix |
|
Date: |
Fri, 29 May 2020 18:08:20 +0200 |
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 1e979a1 tables/figures business model, appendix
1e979a1 is described below
commit 1e979a14e9c4e102562e291033147ee20a9f53e7
Author: Dominik Meister <dominiksamuel.meister@students.bfh.ch>
AuthorDate: Fri May 29 18:07:41 2020 +0200
tables/figures business model, appendix
---
doc/thesis/business_model.tex | 120 +++++--
doc/thesis/design.tex | 396 ++-------------------
doc/thesis/images/project_plan.png | Bin 0 -> 50611 bytes
doc/thesis/images/recovery_process.png | Bin 0 -> 37488 bytes
doc/thesis/images/secret_split.png | Bin 0 -> 49879 bytes
doc/thesis/implementation.tex | 21 ++
...architecture.tex => rest_api_documentation.tex} | 75 ++--
doc/thesis/server_architecture.tex | 336 +----------------
doc/thesis/thesis.tex | 6 +-
9 files changed, 193 insertions(+), 761 deletions(-)
diff --git a/doc/thesis/business_model.tex b/doc/thesis/business_model.tex
index aa035a0..2b1526d 100644
--- a/doc/thesis/business_model.tex
+++ b/doc/thesis/business_model.tex
@@ -1,10 +1,20 @@
\section{Business model}
+\subsection{Introduction}
+We are currently in the process of building a start-up for the Anastasis
application. This business model shows an overview how we want to build our
start-up and how we want to continue our work on the project.
\subsection{Executive Summary}
-Project Anastasis was inspired by a discussion the GNU Taler team had with the
European Central Bank, which informed them about a requirement for electronic
wallets denominated in Euros to support password-less recovery. GNU Taler is a
privacy-preserving microtransaction and electronic payment system based on free
software. In consultation with Taler Systems SA we, Dominik Meister and Dennis
Neufeld, decided to develop such a password-less recovery system within our
bachelor thesis. We n [...]
-Having an agreement with Taler Systems SA our first customers will be the
users of GNU Taler and Taler Systems SA themselves. Later on we also want to
integrate Anastasis within other services like for example pEp which is also
interested in our service. There are many other use cases Anastasis can be used
for: Password Manager (like KeePass), electronic wallets for cryptocurrencies
etc.
-There are some solutions out there for password recovery. But none of them is
respecting privacy and enabling the users to remain in control of their data.
-Anastasis enables ordinary users to remain in control of their data, including
ensuring their data remains available to them, even if they cannot remember or
securely store any sufficient high-entropy key material to secure their access.
+Users of cryptography are frequently facing the challenge to secure their core
secrets (private keys), and the contemporary default of asking them to remember
strong passphrases is inadequate for mass adoption. The loss of such a core
secret can cause severe damage for a user. Our project was conceived as a
solution to
+similar problems several privacy enhancing software projects are facing today.
Specifically, the Swiss Pretty Easy Privacy project (https://pep.foundation),
an E-Mail encryption solution which needs an easy way for users to recover
their private keys to avoid the loss of encrypted E-Mails.
+The GNU Taler team (lead by Prof. Grothoff) is building an electronic payment
system and is facing an equivalent challenge: the European Central Bank
informed them about a requirement for electronic wallets denominated in Euros
to support password-less data recovery.
+We designed Anastasis to address this common problem of cryptographic consumer
products.
+Within our bachelor thesis we could build a working prototype of the
application.
+But this application is not a finished finished product. Within the thesis we
only could implement rudimentary authentication methods. To satisfy the
+requirements of our industry partners we need to have several different
authentication methods (SMS, Videoindent...) implemented. Additionally, the
Anastasis environment will need proper automatization. Specifically, monitoring
of the integration with external authentication providers, the correct
operation of the backup mechanism and the business logic. To make Anastasis
ready for public usage we estimate the need of an additional year of
development.
+The resulting start-up would initially receive B2B revenue from companies that
need our solution for their cryptographic consumer product. In addition to
Taler and PEP we are in discussion with developers of crypto currencies from
Zug and Lausanne. Subsequently these contacts would evolve into distribution
channels,
+and Anastasis would eventually earn money directly from its users.
+Cryptographic solutions which are not open to the public are not trustworthy.
As seen lately with the Crypto AG. Experts recommend to only use Free and Libre
Open Source Software (FLOSS) especially for cryptography. Therefore, Anastasis
is licensed under the Affero GPL which will prevent other companies
+from creating or operating proprietary forks.
+Being first to market and thus the default provider in various consumer
products will be a key business advantage.
\subsection{Market review and innovation potential}
@@ -12,35 +22,94 @@ There are already some key recovery or key splitting
solutions on the market. Fo
Today information losses from security incidents are rampant, either because
data is exposed (loss of confidentiality) or because users lose their data
because of lacking backups (loss of availability). As seen in the study of the
Global Data Protection Index 2018 \cite{global_data_index}, 76\% of those
interviewed had an availability incident. 1TB of data loss or 20 hours of
downtime reportedly costs half a million dollars. On the other hand, loss of
confidential private data can result [...]
Prominent cases in which sometimes enormous amounts of money have been gone
useless by losing the key to the digital wallet clarify the urgent need of a
key recovery system like Anastasis. For example the case QuadrigaCX exchange
was heavily discussed in the media when the chief executive, Gerald Cotton,
unexpectedly died and left £145 million in a “cold wallet”.
\cite{millions_lost} In some cases there is a workaround to recover a lost key,
provided there is a security hole in the digit [...]
+\subsection{Business model canvas}
-\subsection{Founder}
-Dominik Meister and Dennis Neufeld are students at the Berner Fachhochschule
in Biel. They will graduate their study with Bachelor of Science in Computer
Sciences in summer 2020. During his bachelor thesis Dominik Meister will found
Anastasis.
+\subsubsection{Key partners}
+Our key partners for Anastasis are 3 entities. First the business partners,
Taler Systems SA and PEP Foundation, with whom we could already make contracts
and wish to integrate our product.
+Second are the providers of Cloud Services. To operate Anastasis with minimal
cost we need the service of these providers. These providers can additionally
provide us authentication services, this also minimizes the complexity of our
solution since we do not have to implement these services by ourselves.
+Such a provider could be for example Amazon AWS, Azure, Google.
+At last we also have the BFH as a key partner. The BFH supported us with
various means during our Bachelor thesis.
+\subsubsection{Key activities}
+The main work of our start up is the completion of our software for commercial
use. This involves the integration of different authentication methods and the
integration of our application into the different consumer applications.
Another key activity is the maintenance and deployment of our service.
+\subsubsection{Key resources}
+Our developers need a device to work with, we agreed to the policy to “bring
your own device” this means the start-up does not have to invest in hardware.
To operate our application, we will need servers to provide our service, as
previously mentioned we would provide our service on a Cloud provider.
+For the further development of our service we need two fulltime employees.
These two developers would also be responsible for the maintenance and
deployment of the application. Additionally, the start-up needs a person who is
responsible for the business of Anastasis. This employee would be responsible
to find new
+business partners and present our application to investors. This employee
would only work part time. To be able to finance the start-up Anastasis needs
investors or funding until the application is finished for the market.
+\subsubsection{Value Propositions}
+As mentioned earlier there are a lot of solutions which need a key recovery
system. Anastasis is also a very privacy friendly and transparent solution.
Also, Anastasis will make sure that the application is very user friendly and
inexpensive to use.
+\subsubsection{Customer relationships}
+In the early stages of our start-up our customers are primary going to be
Business customers. Like Taler Systems SA which wants to integrate our solution
into their wallet. This means at the begin our customers are mainly the users
of already existing solutions. In later stages of our start-up we also want to
acquire business to customer clients, for example users who want to secure
their private key for their disk encryption.
+\subsubsection{Customer segments}
+As mentioned earlier our customers will be primarily other solutions which
need a way to backup their keys.
+Many applications with decentralized structures need such a solution.
+Other possible customers are users of digital currencies or users of OpenPGP
solutions.
+\subsubsection{Cost structure}
+The costs for our start-up are the cloud infrastructure, the authentication
services and the cost for the
+employees. For a detailed view see Budget.
+\subsubsection{Revenue streams}
+In the beginning, businesses like Taler Systems SA will pay us to operate an
Anastasis server and to help them integrate our protocol with their software.
+Once we have many end-users utilizing Anastasis, they will have to pay
directly for the service. The users have to pay a subscription fee and micro
payments for each transaction. For example a user has to pay 0.1 CHF per month
for the subscription and 0.01 CHF for each upload. Additionaly the user would
have to pay for expenisve authentication methods like video identification.
-\subsection{Customers segments}
-Already having an agreement with Taler Systems SA as our first customer, they
will integrate our protocol with their software and additionally pay us to
operate an Anastasis server for their users or to help integrate Anastasis with
their product. Similar discussions are ongoing with other organizations, in
particular pretty Easy privacy SA and the Web3 foundation.
-Once many users utilize Anastasis, we expect end-users will directly pay for
the service.
+\subsection{Project plan}
+Our objective for the first year is for Anastasis to implement several
authentication services, have a working cloud deployment with good monitoring,
and to be integrated with various cryptographic consumer products.
+We will hire one developer for the integration with external authentication
providers and monitoring of our cloud deployment. The other developer will
focus on the integration of Anastasis with consumer products.
+Key milestones are the various integrations of the different authentication
methods, the integration of cryptographic consumer products, and the deployment
of our application. Additionally, we would always look out for new customers
and clients who could benefit from Anastasis
-\subsection{Idea}
-Anastasis shall be the first privacy-respecting and password-less recovery
system for ordinary users. By using Anastasis the users remain in control of
their data.
-Our approach is to split the information needed to recover the data across
multiple independent operators. These providers will then use orthogonal
authentication techniques to enable users to recover their key material. For
authentication, we will plug into existing services to send SMS or snail mail,
or perform video identification. Our protocol is designed to minimize
information disclosure, ensuring that operators learn as little information as
necessary.
+\begin{figure}[H]
+ \centering
+ \includegraphics[scale=0.65]{images/project_plan.png}
+ \caption{Business project plan}
+ \label{fig:bi_project_plan}
+\end{figure}
-Anastasis will provide the service by implementing a REST API and an
associated client library as Free Software, in line with a licensing and
business strategy that was agreed with the GNU project.
+\subsection{Budget}
+FIXME
+\subsubsection{Staff and infrastructure}
+FIXME
+\begin{table}[H]
+ \centering
+ \begin{tabular}{ | l | l | l | l |}
+ \rowcolor{lightgray}
+ Expenses & Value & Earnings & Value \\ \hline
+ Dominik Meister & 54'000 & Funding & 150'000 \\ \hline
+ Dennis Neufeld & 54'000 & & \\ \hline
+ Nana Karlstetter & 10'000 & & \\ \hline
+ Travel expenses & 10'000 & & \\ \hline
+ Cloud Services & 100 & & \\ \hline
+ \rowcolor{lightgray}
+ Total & 128'100& & 150'000 \\ \hline
+ \end{tabular}
+ \caption{Staff and infrastructure budget}
+\end{table}
-Initially, few applications will support Anastasis. Hence, our business will
launch by being paid by companies that need an escrow provider to be included
in their product offering.
-\subsection{Strategy}
+FIXME TEXT
-\subsection{Marketing}
-Anastasis will be used by the users of other services or applications like GNU
Taler, OpenPGP etc. They will suggest their users to backup their private keys
with Anastasis. We just have to find and integrate Anastasis with such services
which could benefit from using Anastasis as a password backup and recovery
service.
+\subsubsection{Business}
+fixme text
-\subsection{Revenue streams}
-In the beginning, businesses like Taler Systems SA will pay us to operate an
Anastasis server and to help them integrate our protocol with their software.
-Once we have many end-users utilizing Anastasis, the will have to pay directly
for the service. At first we will start then with an annual fee at 20 cents per
user. Our goal is to optimize our service such that we only have to pay for
operations later, not for development etc. So, we will be able to offer a very
cheap service for our users.
-\subsection{Cost structure}
-In the first two years we have to develop and optimize Anastasis which will be
the biggest costs. After the two years we expect to have just costs for
operations running on Amazon AWS etc.
+\begin{table}[H]
+\centering
+ \begin{tabular}{ | l | l | l | l |}
+ \rowcolor{lightgray}
+ Expenses & Value & Earnings & Value \\ \hline
+ Share capital & 20'000 & Taler Systems SA & 5'000 \\ \hline
+ Notary & 2'000 & PEP foundation & 5'000 \\ \hline
+ Registration & 600 & & \\ \hline
+ Bank account & 400 & Equity & 20'000 \\ \hline
+ \rowcolor{lightgray}
+ Total & 23'000 & & 30'000 \\ \hline
+ \end{tabular}
+ \caption{Business budget}
+\end{table}
-\begin{center}
+fixme text
+
+\subsection{Revenue stream}
+FIXME
+\begin{table}[H]
+ \centering
\begin{tabular}{ | l | l | l | l | l | l |}
\hline
Year & Users & Clients & Sales & Profit & Employees \\ \hline
@@ -50,6 +119,5 @@ In the first two years we have to develop and optimize
Anastasis which will be t
2023 & 5000000 & 5 & 500k & 100k & 2.0 FTE \\
\hline
\end{tabular}
-\end{center}
-
-\subsection{Key Ressources}
+ \caption{Revenue stream}
+\end{table}
\ No newline at end of file
diff --git a/doc/thesis/design.tex b/doc/thesis/design.tex
index b58440d..8503925 100644
--- a/doc/thesis/design.tex
+++ b/doc/thesis/design.tex
@@ -1,383 +1,27 @@
\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 secret is lost. The
core secret itself is protected from the escrow providers by encrypting it with
a 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 sufficien [...]
-\\
+ \\
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 is able to specify a set of policies which determine which
Anastasis escrow providers would need to collude [...]
-\\
+ \\
A recovery document includes all of the information a user needs to recover
access to their core secret. It specifies a set of escrow methods, which
specify how the user should convince the Anastasis server that they are “real”.
Escrow methods can for example include SMS-based verification,
Video-identfication 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 authentica [...]
\subsection{Systemarchitecture}
-
-\subsubsection{Recovery procedure}
-
-\subsubsection{Upload procedure}
-
-
-\subsection{Server architecture}
-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.
-\subsection{Database}
-The database schema of Anastasis is structured as follows.
-\\
-\includegraphics[scale=0.50]{images/anastasis-db.png}
-\\
-The database schema consists of 4 tables. \\
-The Truth table is responsible for storing the keyshares and its
authentication method. The keyshare and the truth are stored encrypted in the
database. The truth is only decrypted during authentication. The keyshare is
never decrypted for the server. This protects the privacy of the customer.
Likewise, the user data is protected after a possible theft. \\
-The 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. \\
-The 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
atleast 1.
-Through this measure we can prevent people from maliciously filling our
database. \\
-The 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 Recoverydocument 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 dupplicate of the document.
Last the signature ensures the integ [...]
-
-\subsection{Server API}
-The server api is a RESTful API which has the following endpoints.
-
-\subsubsection{Obtain Salt}
-\textbf{GET /salt}
-\\
-Obtain the salt used by the escrow provider. Different providers will use
different high-entropy salt values. The resulting provider salt is then used in
various operations to ensure cryptographic operations differ by provider. A
provider must never change its salt value. \\
-\textbf{Response: } \\
-Returns a "SaltResponse".
-\begin{lstlisting}
-interface SaltResponse {
- // salt value, at least 128 bits of entropy
- server_salt: string;
-}
-\end{lstlisting}
-
-\subsubsection{Obatain terms of service}
-\textbf{GET /terms}
-\\
-Obtain the terms of service provided by the escrow provider.
-\\
-\textbf{Response: } \\
-Returns an EscrowTermsOfServiceResponse. \\
-
-\begin{lstlisting}
-interface EscrowTermsOfServiceResponse {
-
- // minimum supported protocol version
- min_version: number;
-
- // maximum supported protocol version
- max_version: number;
-
- // supported authentication methods
- auth_methods: AuthenticationMethod[];
-
- // Payment required to maintain an account to store
- // policy documents for a month.
- // Users can pay more, in which case the storage time
- // will go up proportionally.
- monthly_account_fee: Amount;
-
- // Amount required per policy upload. Note that the amount is NOT
- // charged additionally to the monthly_storage_fee. Instead,
- // when a payment is made, the amount is divided by the policy_upload_fee
- // (and rounded down) to determine how many uploads can be made
- // under the associated payment identifier.
- policy_upload_ratio: Amount;
-
- // maximum policy upload size supported
- policy_size_limit_in_bytes: number;
-
- // maximum truth upload size supported
- truth_size_limit_in_bytes: number;
-
- // how long until the service expires deposited truth
- // (unless refreshed via another POST)?
- truth_expiration: RelativeTime;
-
- // Payment required to upload truth. To be paid per upload.
- truth_upload_fee: Amount;
-
- // Limit on the liability that the provider is offering with
- // respect to the services provided.
- liability_limit: Amount;
-
- // HTML text describing the terms of service in legalese.
- // May include placeholders like "${truth_upload_fee}" to
- // reference entries in this response.
- tos: string;
-}
-\end{lstlisting}
-
-\begin{lstlisting}
-interface AuthenticationMethod {
- // name of the authentication method
- name: string;
-
- // Fee for accessing truth using this method
- usage_fee: Amount;
-
-}
-\end{lstlisting}
-
-\subsubsection{Manage Policy}
-This API is used by the Anastasis client to deposit or request encrypted
recovery documents with the escrow provider. Generally, a client will deposit
the same encrypted recovery document with each escrow provider, but provide
different truth to each escrow provider. \\
-\\
-Operations by the client are identified and authorized by \$ACCOUNT\_PUB,
which should be kept secret from third parties. \$ACCOUNT\_PUB should be an
account public key using the Crockford base32-encoding.\\
-\\
-In the following, UUID is always defined and used according to RFC 4122. \\
-\\
-\textbf{GET /policy/\$ACCOUNT\_PUB[?version=\$NUMBER]} \\
-\\
-Get the customer’s encrypted recovery document. If “version” is not specified,
the server returns the latest available version. If “version” is specified,
returns the policy with the respective “version”. The response must begin with
the nonce and an AES-GCM tag and continue with the ciphertext. Once decrypted,
the plaintext is expected to contain:
-\begin{itemize}
-\item the escrow policy
-\item the separately encrypted master public key
-\end{itemize}
-
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 200 OK – The escrow provider responds with an EncryptedRecoveryDocument
object.
-\item 304 Not modified – The client requested the same ressource it already
knows.
-\item 400 Bad request – The \$ACCOUNT\_PUB is not an EdDSA public key.
-\item 402 Payment Required – The account’s balance is too low for the
specified operation. See the Taler payment protocol specification for how to
pay.
-\item 403 Forbidden – The required account signature was invalid.
-\item 404 Not Found – The requested resource was not found.
-\end{itemize}
-Note that the key shares required to decrypt the master public key are not
included, as for this the client needs to obtain authorization. The policy does
provide sufficient information for the client to determine how to authorize
requests for truth. \\
- \\
-The client MAY provide an “If-None-Match” header with an Etag. In that case,
the server MUST additionally respond with an “304” status code in case the
resource matches the provided Etag.\\
- \\
-Anastasis-Version: \$NUMBER — The server must return actual version of the
encrypted recovery document via this header. If the client specified a version
number in the header of the request, the server must return that version. If
the client did not specify a version in the request, the server returns latest
version of the EncryptedRecoveryDocument.\\
- \\
-Etag: Set by the server to the Base32-encoded SHA512 hash of the body. Used
for caching and to prevent redundancies. The server MUST send the Etag if the
status code is 200 OK.\\
- \\
-If-None-Match: If this is not the very first request of the client, this
contains the Etag-value which the client has reveived before from the server.
The client SHOULD send this header with every request (except for the first
request) to avoid unnecessary downloads.\\
- \\
-Anastasis-Account-Signature: The client must provide Base-32 encoded EdDSA
signature over hash of body with \$ACCOUNT\_PRIV, affirming desire to download
the requested encrypted recovery document. The purpose used MUST be
TALER\_SIGNATURE\_ANASTASIS\_POLICY\_DOWNLOAD (1401).\\
-
-\textbf{POST /policy/\$ACCOUNT\_PUB} \\
- \\
-Upload a new version of the customer’s encrypted recovery document. While the
document’s structure is described in JSON below, the upload should just be the
bytestream of the raw data (i.e. 32 bytes nonce followed by 16 bytes tag
followed by the encrypted document). If request has been seen before, the
server should do nothing, and otherwise store the new version. The body must
begin with a nonce, an AES-GCM tag and continue with the ciphertext. The format
is the same as specified for th [...]
- \\
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 204 No Content – The encrypted recovery document was accepted and
stored. “Anastasis-Version” and “Anastasis-UUID” headers incidate what version
and UUID was assigned to this encrypted recovery document upload by the server.
-\item 304 Not modified – The same encrypted recovery document was previously
accepted and stored. “Anastasis-Version” header incidates what version was
previously assigned to this encrypted recovery document.
-\item 400 Bad request – The \$ACCOUNT\_PUB is not an EdDSA public key or
mandatory headers are missing. The response body MUST elaborate on the error
using a Taler error code in the typical JSON encoding.
-\item 402 Payment Required – The account’s balance is too low for the
specified operation. See the Taler payment protocol specification for how to
pay. The response body MAY provide alternative means for payment.
-\item 403 Forbidden – The required account signature was invalid. The response
body may elaborate on the error.
-\item 409 Conflict – The If-Match Etag does not match the latest prior version
known to the server.
-\item 413 Request Entity Too Large – The upload is too large or too small. The
response body may elaborate on the error.
-\end{itemize}
-\textit{If-Match:} Unless the client expects to upload the first encrypted
recovery document to this account, the client should provide an Etag matching
the latest version already known to the server. If this header is present, the
server MUST refuse the upload if the latest known version prior to this upload
does not match the given Etag. \\
-\textit{If-None-Match:} This header must be present and set to the SHA512 hash
(Etag) of the body by the client. The client should also set the “Expect:
100-Continue” header and wait for “100 continue” before uploading the body. The
server MUST use the Etag to check whether it already knows the encrypted
recovery document that is about to be uploaded. The server MUST refuse the
upload with a “304” status code if the Etag matches the latest version already
known to the server.
-Anastasis-Policy-Signature: The client must provide Base-32 encoded EdDSA
signature over hash of body with \$ACCOUNT\_PRIV, affirming desire to upload an
encrypted recovery document.\\
-\textit{Payment-Identifier:} Base-32 encoded 32-byte payment identifier that
was included in a previous payment (see 402 status code). Used to allow the
server to check that the client paid for the upload (to protect the server
against DoS attacks) and that the client knows a real secret of financial value
(as the kdf\_id might be known to an attacker). If this header is missing in
the client’s request (or the associated payment has exceeded the upload limit),
the server must return a 40 [...]
- \\
-\begin{lstlisting}
-interface EncryptedRecoveryDocument {
- // Nonce used to compute the (iv,key) pair for encryption
- // of the encrypted_compressed_recovery_document.
- nonce: [32]; //bytearray
-
- // Authentication tag
- aes_gcm_tag: [16]; //bytearray
-
- // Variable-size encrypted recovery document. After decryption,
- // this contains a gzip compressed JSON-encoded RecoveryDocument.
- // The nonce of the HKDF for this encryption must include the
- // string "ERD".
- // bytearray of undefined length
- encrypted_compressed_recovery_document: [];
-
-}
-\end{lstlisting}
- \\
-\begin{lstlisting}
-
-interface RecoveryDocument {
- // Account identifier at backup provider, AES-encrypted with
- // the (symmetric) master_key, i.e. an URL
- // https://sync.taler.net/$BACKUP_ID and
- // a private key to decrypt the backup. Anastasis is oblivious
- // to the details of how this is ultimately encoded.
- backup_account: []; //bytearray of undefined length
-
- // List of escrow providers and selected authentication method
- methods: EscrowMethod[];
-
- // List of possible decryption policies
- policy: DecryptionPolicy[];
-
-}
-\end{lstlisting}
-
-\begin{lstlisting}
-interface EscrowMethod {
- // URL of the escrow provider
- // (including possibly this Anastasis server)
- provider_url : string;
-
- // Name of the escrow method (e.g. security question, SMS etc.)
- escrow_method: string;
-
- // UUID of the escrow method (see /truth/ API below).
- uuid: string;
-
- // Key used to encrypt the Truth this EscrowMethod is related to.
- // Client has to provide this key to the server when using /truth/
- truth_encryption_key: [32]; //bytearray
-
- // Salt used to encrypt the truth on the Anastasis server.
- truth_salt: [32]; //bytearray
-
- // The challenge to give to the user (i.e. the security question
- // if this is challenge-response).
- // (Q: as string in base32 encoding?)
- // (Q: what is the mime-type of this value?)
- //
- // For some methods, this value may be absent.
- //
- // The plaintext challenge is not revealed to the
- // Anastasis server.
- challenge: []; //bytearray of undefined length
-}
-
-\end{lstlisting}
-
-\begin{lstlisting}
-interface DecryptionPolicy {
- // Salt included to encrypt master key share when
- // using this decryption policy.
- policy_salt: [32]; //bytearray
-
- // Master key, AES-encrypted with key derived from
- // salt and keyshares revealed by the following list of
- // escrow methods identified by UUID.
- encrypted_master_key: [32]; //bytearray
-
- // List of escrow methods identified by their uuid.
- uuid: string[];
-
-}
-\end{lstlisting}
-
-\subsubsection{Manage Truth}
-This API is used by the Anastasis client to deposit truth or request a
(encrypted) key share with the escrow provider.\\
- \\
-An escrow method specifies an Anastasis provider and how the user should
authorize themself. The truth API allows the user to provide the (encrypted)
key share to the respective escrow provider, as well as auxiliary data required
for such an respective escrow method. \\
- \\
-An Anastasis-server may store truth for free for a certain time period, or
charge per truth operation using GNU Taler.
- \\
-\textbf{POST /truth/\$UUID}
- \\
-Upload a TruthUploadRequest-Object according to the policy the client created
before (see RecoveryDocument). If request has been seen before, the server
should do nothing, and otherwise store the new object. \\
- \\
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 204 No content – Truth stored successfully.
-\item 304 Not modified – The same truth was previously accepted and stored
under this UUID. The Anastasis server must still update the expiration time for
the truth when returning this response code.
-\item 402 Payment Required – This server requires payment to store truth per
item. See the Taler payment protocol specification for how to pay. The response
body MAY provide alternative means for payment.
-\item 409 Conflict – The server already has some truth stored under this UUID.
The client should check that it is generating UUIDs with enough entropy.
-\item 412 Precondition Failed – The selected authentication method is not
supported on this provider.
-\end{itemize}
- \\
-\textbf{Details:} \\
-\begin{lstlisting}
-interface TruthUploadRequest {
- // Contains the information of an interface EncryptedKeyShare,
- // but simply as one binary block (in Crockford Base32
- // encoding for JSON).
- key_share_data: []; //bytearray
-
- // Key share method, i.e. "security question", "SMS", "e-mail", ...
- method: string;
-
- // Nonce used to compute the (iv,key) pair for encryption of the
- // encrypted_truth.
- nonce: [32]; //bytearray
-
- // Authentication tag of encrypted_truth
- aes_gcm_tag: [16]; //bytearray
-
- // Variable-size truth. After decryption,
- // this contains the ground truth, i.e. H(challenge answer),
- // phone number, e-mail address, picture, fingerprint, ...
- // **base32 encoded**.
- //
- // The nonce of the HKDF for this encryption must include the
- // string "ECT".
- encrypted_truth: [80]; //bytearray
-
- // mime type of truth, i.e. text/ascii, image/jpeg, etc.
- truth_mime: string;
-}
-\end{lstlisting}
- \\
-\textbf{GET /truth/\$UUID[?response=\$RESPONSE]} \\
- \\
-Get the stored encrypted key share. If \$RESPONSE is specified by the client,
the server checks if \$RESPONSE matches the expected response specified before
within the TruthUploadRequest (see encrypted\_truth). Also, the user has to
provide the correct truth\_encryption\_key with every get request (see below).
When \$RESPONSE is correct, the server responses with the encrypted key share.
The encrypted key share is returned simply as a byte array and not in JSON
format. \\
-
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 200 OK – EncryptedKeyShare is returned in body (in binary).
-\item 202 Accepted – The escrow provider will respond out-of-band (i.e. SMS).
The body may contain human-readable instructions on next steps.
-\item 303 See Other – The provider redirects for authentication (i.e. video
identification/WebRTC). If the client is not a browser, it should launch a
browser at the URL given in the “Location” header and allow the user to re-try
the operation after successful authorization.
-\item 402 Payment Required – The service requires payment for access to truth.
See the Taler payment protocol specification for how to pay. The response body
MAY provide alternative means for payment.
-\item 403 Forbidden – The server requires a valid “response” to the challenge
associated with the UUID.
-\item 404 Not Found – The server does not know any truth under the given UUID.
-\item 503 Service Unavailable – Server is out of Service.
-\end{itemize}
- \\
-\textbf{Truth-Decryption-Key:} Key used to encrypt the truth (see
encrypted\_truth within TruthUploadRequest) and which has to provided by the
user. The key is stored with the according EscrowMethod. The server needs this
key to get the info out of TruthUploadRequest needed to verify the \$RESPONSE.
- \\
-\textbf{Details:}
-\begin{lstlisting}
-interface EncryptedKeyShare {
- // Nonce used to compute the decryption (iv,key) pair.
- nonce_i: [32]; //bytearray
-
- // Authentication tag
- aes_gcm_tag_i: [16]; //bytearray
-
- // Encrypted key-share in base32 encoding.
- // After decryption, this yields a KeyShare. Note that
- // the KeyShare MUST be encoded as a fixed-size binary
- // block (instead of in JSON encoding).
- //
- // HKDF for the key generation must include the
- // string "eks" as salt. Depending on the method,
- // the HKDF may additionally include
- // bits from the response (i.e. some hash over the
- // answer to the security question)
- encrypted_key_share_i: [32]; //bytearray
-}
-\end{lstlisting}
- \\
-\begin{lstlisting}
-interface KeyShare {
- // Key material to concatenate with policy_salt
- // and KDF to derive the key to decrypt the master key.
- key_share: [32]; //bytearray
-
- // Signature over method, uuid, and key_share.
- account_sig: EddsaSignature;
-}
-\end{lstlisting}
-
-\subsection{Authentication Methods}
-This section describes the supported authentication methods in detail.
-
-\subsubsection{SMS (sms)}
-Sends an SMS with a code to the users phone. The must send this code back with
his request (see \$RESPONSE under ‘Manage truth’). If the transmitted code is
correct, the server responses with the requested encrypted key share. FIXME:
details!
-
-\subsubsection{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. FIXME:
details!
-
-\subsubsection{Security question (qa)}
-Asks the user a security question. The user sends back a hash over the answer.
If the hash value matches with the one the server is expecting, the server
answers with the requested encrypted key share. A different hash function over
the same security answer is used to provide optional data for the decryption of
the (encrypted) key share.
-
-\subsubsection{Post-Indent (post)}
-Physical address verification via snail mail. FIXME: details!
-
-\subsection{Client architecture}
-
-\subsection{Client API}
-
-\subsection{Client Application CLI}
-
-
-
+This graphic shows the basic construct of the Anastasis application. It shows
a simplified flow of the application. The details of each component is shown
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 the communication with the user. The anastasis\_api also
handles the communication between the other client components.
+\item After the user provided their unforgetable 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.
+\end{enumerate}
\ No newline at end of file
diff --git a/doc/thesis/images/project_plan.png
b/doc/thesis/images/project_plan.png
new file mode 100644
index 0000000..3ede596
Binary files /dev/null and b/doc/thesis/images/project_plan.png differ
diff --git a/doc/thesis/images/recovery_process.png
b/doc/thesis/images/recovery_process.png
new file mode 100644
index 0000000..3ad0c10
Binary files /dev/null and b/doc/thesis/images/recovery_process.png differ
diff --git a/doc/thesis/images/secret_split.png
b/doc/thesis/images/secret_split.png
new file mode 100644
index 0000000..3288f6f
Binary files /dev/null and b/doc/thesis/images/secret_split.png differ
diff --git a/doc/thesis/implementation.tex b/doc/thesis/implementation.tex
index 70cd883..aa5255d 100644
--- a/doc/thesis/implementation.tex
+++ b/doc/thesis/implementation.tex
@@ -1,4 +1,25 @@
\section{Implementation}
+
+\subsection{Application flow}
+This section describes a happy flow between the Anastasis server and the
client.
+
+\subsubsection{Secret splitting}
+\begin{figure}[H]
+ \centering
+ \includegraphics[scale=0.5]{images/secret_split.png}
+ \caption{Secret split process}
+ \label{fig:secret_split}
+\end{figure}
+
+\subsubsection{Secret recovery}
+
+\begin{figure}[H]
+ \centering
+ \includegraphics[scale=0.5]{images/recovery_process.png}
+ \caption{Secret recovery process}
+ \label{fig:recovery_process}
+\end{figure}
+
\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. \\
\\
diff --git a/doc/thesis/server_architecture.tex
b/doc/thesis/rest_api_documentation.tex
similarity index 84%
copy from doc/thesis/server_architecture.tex
copy to doc/thesis/rest_api_documentation.tex
index 7670af9..f24ad9a 100644
--- a/doc/thesis/server_architecture.tex
+++ b/doc/thesis/rest_api_documentation.tex
@@ -1,21 +1,46 @@
-\section{Server architecture}
-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.
-\subsection{Database}
-The database schema of Anastasis is structured as follows.
-\\
-\includegraphics[scale=0.50]{images/anastasis-db.png}
-\\
-The database schema consists of 4 tables. \\
-The Truth table is responsible for storing the keyshares and its
authentication method. The keyshare and the truth are stored encrypted in the
database. The truth is only decrypted during authentication. The keyshare is
never decrypted for the server. This protects the privacy of the customer.
Likewise, the user data is protected after a possible theft. \\
-The 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. \\
-The 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
atleast 1.
-Through this measure we can prevent people from maliciously filling our
database. \\
-The 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 Recoverydocument 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 dupplicate of the document.
Last the signature ensures the integ [...]
-
-\subsection{Server API}
+\documentclass{scrartcl}
+\usepackage{lipsum}
+%%\usepackage[french]{babel}
+%%\usepackage[ngerman]{babel}
+
+%% Choose default font for the document
+%% Warning : only ONE of the following should be enabled
+\usepackage{kpfonts}
+%%\usepackage{libertine}
+\usepackage[table]{xcolor}
+%% The following chose the default language for the document and
+%% use the default typography rules for the choosen language.
+\usepackage{polyglossia}
+\setdefaultlanguage{english}
+%% \setdefaultlanguage{german}
+%%\setdefaultlanguage{french}
+
+\usepackage[backend=biber, style=ieee]{biblatex}
+\addbibresource{bibliothek.bib}
+
+\usepackage{abstract}
+\usepackage{graphicx}
+\usepackage{listings}
+\lstset{language=C,
+ basicstyle=\ttfamily,
+ keywordstyle=\bfseries,
+ showstringspaces=false,
+ morekeywords={include, printf, interface}
+}
+
+\begin{document}
+\title{Anastasis REST API}
+\date{\today} %% or \date{01 november 2018}
+\author{Dominik Meister (\texttt{dominiksamuel.meister@students.bfh.ch}) \\
+ Dennis Neufeld (\texttt{dennis.neufeld@students.bfh.ch })}
+\maketitle
+\tableofcontents
+\clearpage
+
+\section{Server API}
The server api is a RESTful API which has the following endpoints.
-\subsubsection{Obtain Salt}
+\subsection{Obtain Salt}
\textbf{GET /salt}
\\
Obtain the salt used by the escrow provider. Different providers will use
different high-entropy salt values. The resulting provider salt is then used in
various operations to ensure cryptographic operations differ by provider. A
provider must never change its salt value. \\
@@ -28,7 +53,7 @@ interface SaltResponse {
}
\end{lstlisting}
-\subsubsection{Obatain terms of service}
+\subsection{Obatain terms of service}
\textbf{GET /terms}
\\
Obtain the terms of service provided by the escrow provider.
@@ -96,7 +121,7 @@ interface AuthenticationMethod {
}
\end{lstlisting}
-\subsubsection{Manage Policy}
+\subsection{Manage Policy}
This API is used by the Anastasis client to deposit or request encrypted
recovery documents with the escrow provider. Generally, a client will deposit
the same encrypted recovery document with each escrow provider, but provide
different truth to each escrow provider. \\
\\
Operations by the client are identified and authorized by \$ACCOUNT\_PUB,
which should be kept secret from third parties. \$ACCOUNT\_PUB should be an
account public key using the Crockford base32-encoding.\\
@@ -238,7 +263,7 @@ interface DecryptionPolicy {
}
\end{lstlisting}
-\subsubsection{Manage Truth}
+\subsection{Manage Truth}
This API is used by the Anastasis client to deposit truth or request a
(encrypted) key share with the escrow provider.\\
\\
An escrow method specifies an Anastasis provider and how the user should
authorize themself. The truth API allows the user to provide the (encrypted)
key share to the respective escrow provider, as well as auxiliary data required
for such an respective escrow method. \\
@@ -338,14 +363,4 @@ interface KeyShare {
}
\end{lstlisting}
-\subsection{Authentication Methods}
-This section describes the supported authentication methods in detail.
-
-\subsubsection{SMS (sms)}
-Sends an SMS with a code to the users phone. The must send this code back with
his request (see \$RESPONSE under ‘Manage truth’). If the transmitted code is
correct, the server responses with the requested encrypted key share. FIXME:
details!
-
-\subsubsection{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. FIXME:
details!
-
-\subsubsection{Security question (qa)}
-Asks the user a security question. The user sends back a hash over the answer.
If the hash value matches with the one the server is expecting, the server
answers with the requested encrypted key share. A different hash function over
the same security answer is used to provide optional data for the decryption of
the (encrypted) key share.
+\end{document}
\ No newline at end of file
diff --git a/doc/thesis/server_architecture.tex
b/doc/thesis/server_architecture.tex
index 7670af9..4bde737 100644
--- a/doc/thesis/server_architecture.tex
+++ b/doc/thesis/server_architecture.tex
@@ -2,9 +2,13 @@
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.
\subsection{Database}
The database schema of Anastasis is structured as follows.
-\\
-\includegraphics[scale=0.50]{images/anastasis-db.png}
-\\
+\begin{figure}[H]
+ \centering
+ \includegraphics[scale=0.5]{images/anastasis-db.png}
+ \caption{Anastasis database}
+ \label{fig:anastasis_database}
+\end{figure}
+
The database schema consists of 4 tables. \\
The Truth table is responsible for storing the keyshares and its
authentication method. The keyshare and the truth are stored encrypted in the
database. The truth is only decrypted during authentication. The keyshare is
never decrypted for the server. This protects the privacy of the customer.
Likewise, the user data is protected after a possible theft. \\
The 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. \\
@@ -13,330 +17,8 @@ Through this measure we can prevent people from maliciously
filling our database
The 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 Recoverydocument 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 dupplicate of the document.
Last the signature ensures the integ [...]
\subsection{Server API}
-The server api is a RESTful API which has the following endpoints.
-
-\subsubsection{Obtain Salt}
-\textbf{GET /salt}
-\\
-Obtain the salt used by the escrow provider. Different providers will use
different high-entropy salt values. The resulting provider salt is then used in
various operations to ensure cryptographic operations differ by provider. A
provider must never change its salt value. \\
-\textbf{Response: } \\
-Returns a "SaltResponse".
-\begin{lstlisting}
-interface SaltResponse {
- // salt value, at least 128 bits of entropy
- server_salt: string;
-}
-\end{lstlisting}
-
-\subsubsection{Obatain terms of service}
-\textbf{GET /terms}
-\\
-Obtain the terms of service provided by the escrow provider.
-\\
-\textbf{Response: } \\
-Returns an EscrowTermsOfServiceResponse. \\
-
-\begin{lstlisting}
-interface EscrowTermsOfServiceResponse {
-
- // minimum supported protocol version
- min_version: number;
-
- // maximum supported protocol version
- max_version: number;
-
- // supported authentication methods
- auth_methods: AuthenticationMethod[];
-
- // Payment required to maintain an account to store
- // policy documents for a month.
- // Users can pay more, in which case the storage time
- // will go up proportionally.
- monthly_account_fee: Amount;
-
- // Amount required per policy upload. Note that the amount is NOT
- // charged additionally to the monthly_storage_fee. Instead,
- // when a payment is made, the amount is divided by the policy_upload_fee
- // (and rounded down) to determine how many uploads can be made
- // under the associated payment identifier.
- policy_upload_ratio: Amount;
-
- // maximum policy upload size supported
- policy_size_limit_in_bytes: number;
-
- // maximum truth upload size supported
- truth_size_limit_in_bytes: number;
-
- // how long until the service expires deposited truth
- // (unless refreshed via another POST)?
- truth_expiration: RelativeTime;
-
- // Payment required to upload truth. To be paid per upload.
- truth_upload_fee: Amount;
-
- // Limit on the liability that the provider is offering with
- // respect to the services provided.
- liability_limit: Amount;
-
- // HTML text describing the terms of service in legalese.
- // May include placeholders like "${truth_upload_fee}" to
- // reference entries in this response.
- tos: string;
-}
-\end{lstlisting}
-
-\begin{lstlisting}
-interface AuthenticationMethod {
- // name of the authentication method
- name: string;
-
- // Fee for accessing truth using this method
- usage_fee: Amount;
-
-}
-\end{lstlisting}
-
-\subsubsection{Manage Policy}
-This API is used by the Anastasis client to deposit or request encrypted
recovery documents with the escrow provider. Generally, a client will deposit
the same encrypted recovery document with each escrow provider, but provide
different truth to each escrow provider. \\
-\\
-Operations by the client are identified and authorized by \$ACCOUNT\_PUB,
which should be kept secret from third parties. \$ACCOUNT\_PUB should be an
account public key using the Crockford base32-encoding.\\
-\\
-In the following, UUID is always defined and used according to RFC 4122. \\
-\\
-\textbf{GET /policy/\$ACCOUNT\_PUB[?version=\$NUMBER]} \\
-\\
-Get the customer’s encrypted recovery document. If “version” is not specified,
the server returns the latest available version. If “version” is specified,
returns the policy with the respective “version”. The response must begin with
the nonce and an AES-GCM tag and continue with the ciphertext. Once decrypted,
the plaintext is expected to contain:
-\begin{itemize}
-\item the escrow policy
-\item the separately encrypted master public key
-\end{itemize}
-
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 200 OK – The escrow provider responds with an EncryptedRecoveryDocument
object.
-\item 304 Not modified – The client requested the same ressource it already
knows.
-\item 400 Bad request – The \$ACCOUNT\_PUB is not an EdDSA public key.
-\item 402 Payment Required – The account’s balance is too low for the
specified operation. See the Taler payment protocol specification for how to
pay.
-\item 403 Forbidden – The required account signature was invalid.
-\item 404 Not Found – The requested resource was not found.
-\end{itemize}
-Note that the key shares required to decrypt the master public key are not
included, as for this the client needs to obtain authorization. The policy does
provide sufficient information for the client to determine how to authorize
requests for truth. \\
- \\
-The client MAY provide an “If-None-Match” header with an Etag. In that case,
the server MUST additionally respond with an “304” status code in case the
resource matches the provided Etag.\\
- \\
-Anastasis-Version: \$NUMBER — The server must return actual version of the
encrypted recovery document via this header. If the client specified a version
number in the header of the request, the server must return that version. If
the client did not specify a version in the request, the server returns latest
version of the EncryptedRecoveryDocument.\\
- \\
-Etag: Set by the server to the Base32-encoded SHA512 hash of the body. Used
for caching and to prevent redundancies. The server MUST send the Etag if the
status code is 200 OK.\\
- \\
-If-None-Match: If this is not the very first request of the client, this
contains the Etag-value which the client has reveived before from the server.
The client SHOULD send this header with every request (except for the first
request) to avoid unnecessary downloads.\\
- \\
-Anastasis-Account-Signature: The client must provide Base-32 encoded EdDSA
signature over hash of body with \$ACCOUNT\_PRIV, affirming desire to download
the requested encrypted recovery document. The purpose used MUST be
TALER\_SIGNATURE\_ANASTASIS\_POLICY\_DOWNLOAD (1401).\\
-
-\textbf{POST /policy/\$ACCOUNT\_PUB} \\
- \\
-Upload a new version of the customer’s encrypted recovery document. While the
document’s structure is described in JSON below, the upload should just be the
bytestream of the raw data (i.e. 32 bytes nonce followed by 16 bytes tag
followed by the encrypted document). If request has been seen before, the
server should do nothing, and otherwise store the new version. The body must
begin with a nonce, an AES-GCM tag and continue with the ciphertext. The format
is the same as specified for th [...]
- \\
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 204 No Content – The encrypted recovery document was accepted and
stored. “Anastasis-Version” and “Anastasis-UUID” headers incidate what version
and UUID was assigned to this encrypted recovery document upload by the server.
-\item 304 Not modified – The same encrypted recovery document was previously
accepted and stored. “Anastasis-Version” header incidates what version was
previously assigned to this encrypted recovery document.
-\item 400 Bad request – The \$ACCOUNT\_PUB is not an EdDSA public key or
mandatory headers are missing. The response body MUST elaborate on the error
using a Taler error code in the typical JSON encoding.
-\item 402 Payment Required – The account’s balance is too low for the
specified operation. See the Taler payment protocol specification for how to
pay. The response body MAY provide alternative means for payment.
-\item 403 Forbidden – The required account signature was invalid. The response
body may elaborate on the error.
-\item 409 Conflict – The If-Match Etag does not match the latest prior version
known to the server.
-\item 413 Request Entity Too Large – The upload is too large or too small. The
response body may elaborate on the error.
-\end{itemize}
-\textit{If-Match:} Unless the client expects to upload the first encrypted
recovery document to this account, the client should provide an Etag matching
the latest version already known to the server. If this header is present, the
server MUST refuse the upload if the latest known version prior to this upload
does not match the given Etag. \\
-\textit{If-None-Match:} This header must be present and set to the SHA512 hash
(Etag) of the body by the client. The client should also set the “Expect:
100-Continue” header and wait for “100 continue” before uploading the body. The
server MUST use the Etag to check whether it already knows the encrypted
recovery document that is about to be uploaded. The server MUST refuse the
upload with a “304” status code if the Etag matches the latest version already
known to the server.
-Anastasis-Policy-Signature: The client must provide Base-32 encoded EdDSA
signature over hash of body with \$ACCOUNT\_PRIV, affirming desire to upload an
encrypted recovery document.\\
-\textit{Payment-Identifier:} Base-32 encoded 32-byte payment identifier that
was included in a previous payment (see 402 status code). Used to allow the
server to check that the client paid for the upload (to protect the server
against DoS attacks) and that the client knows a real secret of financial value
(as the kdf\_id might be known to an attacker). If this header is missing in
the client’s request (or the associated payment has exceeded the upload limit),
the server must return a 40 [...]
- \\
-\begin{lstlisting}
-interface EncryptedRecoveryDocument {
- // Nonce used to compute the (iv,key) pair for encryption
- // of the encrypted_compressed_recovery_document.
- nonce: [32]; //bytearray
-
- // Authentication tag
- aes_gcm_tag: [16]; //bytearray
-
- // Variable-size encrypted recovery document. After decryption,
- // this contains a gzip compressed JSON-encoded RecoveryDocument.
- // The nonce of the HKDF for this encryption must include the
- // string "ERD".
- // bytearray of undefined length
- encrypted_compressed_recovery_document: [];
-
-}
-\end{lstlisting}
-\begin{lstlisting}
-
-interface RecoveryDocument {
- // Account identifier at backup provider, AES-encrypted with
- // the (symmetric) master_key, i.e. an URL
- // https://sync.taler.net/$BACKUP_ID and
- // a private key to decrypt the backup. Anastasis is oblivious
- // to the details of how this is ultimately encoded.
- backup_account: []; //bytearray of undefined length
-
- // List of escrow providers and selected authentication method
- methods: EscrowMethod[];
-
- // List of possible decryption policies
- policy: DecryptionPolicy[];
-
-}
-\end{lstlisting}
-
-\begin{lstlisting}
-interface EscrowMethod {
- // URL of the escrow provider
- // (including possibly this Anastasis server)
- provider_url : string;
-
- // Name of the escrow method (e.g. security question, SMS etc.)
- escrow_method: string;
-
- // UUID of the escrow method (see /truth/ API below).
- uuid: string;
-
- // Key used to encrypt the Truth this EscrowMethod is related to.
- // Client has to provide this key to the server when using /truth/
- truth_encryption_key: [32]; //bytearray
-
- // Salt used to encrypt the truth on the Anastasis server.
- truth_salt: [32]; //bytearray
-
- // The challenge to give to the user (i.e. the security question
- // if this is challenge-response).
- // (Q: as string in base32 encoding?)
- // (Q: what is the mime-type of this value?)
- //
- // For some methods, this value may be absent.
- //
- // The plaintext challenge is not revealed to the
- // Anastasis server.
- challenge: []; //bytearray of undefined length
-}
-
-\end{lstlisting}
-
-\begin{lstlisting}
-interface DecryptionPolicy {
- // Salt included to encrypt master key share when
- // using this decryption policy.
- policy_salt: [32]; //bytearray
-
- // Master key, AES-encrypted with key derived from
- // salt and keyshares revealed by the following list of
- // escrow methods identified by UUID.
- encrypted_master_key: [32]; //bytearray
-
- // List of escrow methods identified by their uuid.
- uuid: string[];
-
-}
-\end{lstlisting}
-
-\subsubsection{Manage Truth}
-This API is used by the Anastasis client to deposit truth or request a
(encrypted) key share with the escrow provider.\\
- \\
-An escrow method specifies an Anastasis provider and how the user should
authorize themself. The truth API allows the user to provide the (encrypted)
key share to the respective escrow provider, as well as auxiliary data required
for such an respective escrow method. \\
- \\
-An Anastasis-server may store truth for free for a certain time period, or
charge per truth operation using GNU Taler.
- \\
-\textbf{POST /truth/\$UUID}
- \\
-Upload a TruthUploadRequest-Object according to the policy the client created
before (see RecoveryDocument). If request has been seen before, the server
should do nothing, and otherwise store the new object. \\
- \\
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 204 No content – Truth stored successfully.
-\item 304 Not modified – The same truth was previously accepted and stored
under this UUID. The Anastasis server must still update the expiration time for
the truth when returning this response code.
-\item 402 Payment Required – This server requires payment to store truth per
item. See the Taler payment protocol specification for how to pay. The response
body MAY provide alternative means for payment.
-\item 409 Conflict – The server already has some truth stored under this UUID.
The client should check that it is generating UUIDs with enough entropy.
-\item 412 Precondition Failed – The selected authentication method is not
supported on this provider.
-\end{itemize}
-\textbf{Details:}
-\begin{lstlisting}
-interface TruthUploadRequest {
- // Contains the information of an interface EncryptedKeyShare,
- // but simply as one binary block (in Crockford Base32
- // encoding for JSON).
- key_share_data: []; //bytearray
-
- // Key share method, i.e. "security question", "SMS", "e-mail", ...
- method: string;
-
- // Nonce used to compute the (iv,key) pair for encryption of the
- // encrypted_truth.
- nonce: [32]; //bytearray
-
- // Authentication tag of encrypted_truth
- aes_gcm_tag: [16]; //bytearray
-
- // Variable-size truth. After decryption,
- // this contains the ground truth, i.e. H(challenge answer),
- // phone number, e-mail address, picture, fingerprint, ...
- // **base32 encoded**.
- //
- // The nonce of the HKDF for this encryption must include the
- // string "ECT".
- encrypted_truth: [80]; //bytearray
-
- // mime type of truth, i.e. text/ascii, image/jpeg, etc.
- truth_mime: string;
-}
-\end{lstlisting}
-\textbf{GET /truth/\$UUID[?response=\$RESPONSE]} \\
- \\
-Get the stored encrypted key share. If \$RESPONSE is specified by the client,
the server checks if \$RESPONSE matches the expected response specified before
within the TruthUploadRequest (see encrypted\_truth). Also, the user has to
provide the correct truth\_encryption\_key with every get request (see below).
When \$RESPONSE is correct, the server responses with the encrypted key share.
The encrypted key share is returned simply as a byte array and not in JSON
format. \\
-
-\textbf{Status Codes: } \\
-\begin{itemize}
-\item 200 OK – EncryptedKeyShare is returned in body (in binary).
-\item 202 Accepted – The escrow provider will respond out-of-band (i.e. SMS).
The body may contain human-readable instructions on next steps.
-\item 303 See Other – The provider redirects for authentication (i.e. video
identification/WebRTC). If the client is not a browser, it should launch a
browser at the URL given in the “Location” header and allow the user to re-try
the operation after successful authorization.
-\item 402 Payment Required – The service requires payment for access to truth.
See the Taler payment protocol specification for how to pay. The response body
MAY provide alternative means for payment.
-\item 403 Forbidden – The server requires a valid “response” to the challenge
associated with the UUID.
-\item 404 Not Found – The server does not know any truth under the given UUID.
-\item 503 Service Unavailable – Server is out of Service.
-\end{itemize}
-
-\textbf{Truth-Decryption-Key:} Key used to encrypt the truth (see
encrypted\_truth within TruthUploadRequest) and which has to provided by the
user. The key is stored with the according EscrowMethod. The server needs this
key to get the info out of TruthUploadRequest needed to verify the \$RESPONSE.
- \\
-\textbf{Details:}
-\begin{lstlisting}
-interface EncryptedKeyShare {
- // Nonce used to compute the decryption (iv,key) pair.
- nonce_i: [32]; //bytearray
-
- // Authentication tag
- aes_gcm_tag_i: [16]; //bytearray
-
- // Encrypted key-share in base32 encoding.
- // After decryption, this yields a KeyShare. Note that
- // the KeyShare MUST be encoded as a fixed-size binary
- // block (instead of in JSON encoding).
- //
- // HKDF for the key generation must include the
- // string "eks" as salt. Depending on the method,
- // the HKDF may additionally include
- // bits from the response (i.e. some hash over the
- // answer to the security question)
- encrypted_key_share_i: [32]; //bytearray
-}
-\end{lstlisting}
-\begin{lstlisting}
-interface KeyShare {
- // Key material to concatenate with policy_salt
- // and KDF to derive the key to decrypt the master key.
- key_share: [32]; //bytearray
-
- // Signature over method, uuid, and key_share.
- account_sig: EddsaSignature;
-}
-\end{lstlisting}
+The webserver of Anastasis runs a RESTful API. For a detailed documentation of
the
+REST API see the rest\_api\_documentation in the appendix.
\subsection{Authentication Methods}
This section describes the supported authentication methods in detail.
diff --git a/doc/thesis/thesis.tex b/doc/thesis/thesis.tex
index 50bc228..08612b1 100644
--- a/doc/thesis/thesis.tex
+++ b/doc/thesis/thesis.tex
@@ -7,13 +7,14 @@
%% Warning : only ONE of the following should be enabled
\usepackage{kpfonts}
%%\usepackage{libertine}
-
+\usepackage[table]{xcolor}
%% The following chose the default language for the document and
%% use the default typography rules for the choosen language.
\usepackage{polyglossia}
\setdefaultlanguage{english}
%% \setdefaultlanguage{german}
%%\setdefaultlanguage{french}
+\usepackage{float}
\usepackage[backend=biber, style=ieee]{biblatex}
\addbibresource{bibliothek.bib}
@@ -60,5 +61,6 @@
%% Print the bibibliography and add the section to th table of content
\printbibliography[heading=bibintoc]
-
+\listoffigures
+\listoftables
\end{document}
--
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: tables/figures business model, appendix,
gnunet <=