diff options
Diffstat (limited to 'doc/system-documentation/server_architecture.tex')
-rw-r--r-- | doc/system-documentation/server_architecture.tex | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/doc/system-documentation/server_architecture.tex b/doc/system-documentation/server_architecture.tex new file mode 100644 index 0000000..264f488 --- /dev/null +++ b/doc/system-documentation/server_architecture.tex | |||
@@ -0,0 +1,134 @@ | |||
1 | \subsection{Server architecture} \label{sec:serverarch} | ||
2 | |||
3 | The Anastasis server architecture consists of two components. A web | ||
4 | server with a REST API and a PostgreSQL database. The structure of | ||
5 | these two components is shown in Figure~\ref{fig:anastasis:server}. | ||
6 | |||
7 | \begin{figure}[H] | ||
8 | \centering | ||
9 | \includegraphics[scale=0.45]{images/server_api.png} | ||
10 | \caption{Anastasis server architecture} | ||
11 | \label{fig:anastasis:server} | ||
12 | \end{figure} | ||
13 | |||
14 | The webserver of Anastasis provides a RESTful API. For a detailed | ||
15 | documentation of the REST API, see | ||
16 | appendix ~\ref{appendix_server_api}. | ||
17 | |||
18 | \newpage | ||
19 | \subsubsection{Database} | ||
20 | |||
21 | The database schema of Anastasis is shown in | ||
22 | Figure~\ref{fig:anastasis_database}. | ||
23 | \begin{figure}[H] | ||
24 | \centering | ||
25 | \includegraphics[scale=0.5]{images/anastasis-db.png} | ||
26 | \caption{Anastasis database schema} | ||
27 | \label{fig:anastasis_database} | ||
28 | \end{figure} | ||
29 | |||
30 | The database schema consists of four main tables: | ||
31 | |||
32 | \begin{itemize} | ||
33 | \item The {\em Truth} table is responsible for storing the key shares and | ||
34 | its authentication method. The key share and the authentication data are stored | ||
35 | encrypted in the database. The authentication data is only decrypted during | ||
36 | authentication. The key share is never decrypted for the | ||
37 | server. This protects the privacy of the customer. Likewise, the | ||
38 | user data is protected after a possible theft. | ||
39 | \item The {\em User} table contains the identification of the user and an | ||
40 | expiration timestamp. This timestamp is a subscription period. This | ||
41 | timestamp is updated after each payment the user makes. Users for | ||
42 | whom the subscription has expired are periodically deleted. | ||
43 | \item The {\em Payments} table contains the details of a payment from a | ||
44 | user. The payment is used either for the post-counter or the | ||
45 | subscription. The post-counter is decremented after each upload of a | ||
46 | recovery document. The user can only upload the recovery document if | ||
47 | the provided payment contains a post-counter which is at least 1. | ||
48 | Through this measure we can prevent people from maliciously filling | ||
49 | our database. | ||
50 | \item The {\em Recoverydocument} table contains the recovery | ||
51 | information. The recovery document is stored encrypted in the | ||
52 | database. This offers better protection, as explained earlier for | ||
53 | the Truth table. Each recovery document record also contains a | ||
54 | version, a hash of the recovery document and a signature. The | ||
55 | version attribute allows the user to lookup a specific version of | ||
56 | the document. The hash is used to check if the user uploads a | ||
57 | duplicate of the document. The signature attests the | ||
58 | integrity of the recovery data. | ||
59 | \end{itemize} | ||
60 | |||
61 | |||
62 | \subsubsection{Authentication methods} | ||
63 | |||
64 | This section describes an overview over the different possible | ||
65 | authentication methods for Anastasis. In our implementation only the | ||
66 | secure question is implemented. The other methods are just explained | ||
67 | how they would be implemented. | ||
68 | |||
69 | In all cases, the authentication process begins by the user decrypting | ||
70 | their (encrypted) recovery document, which contains a list of Anastasis | ||
71 | providers, associated authentication methods, truth\_seeds and associated | ||
72 | truth encryption keys. The recovery process than varies slightly | ||
73 | depending on the authentication method. | ||
74 | |||
75 | \paragraph{SMS (sms)} | ||
76 | |||
77 | The user tells the server with a request that they wants to authorize | ||
78 | key recovery (via GET /truth/\$TRUTH\_PUB), providing a way to decrypt the | ||
79 | truth with the phone number. The server will then generate a \$PIN and | ||
80 | send it via an SMS provider to the stored number in the truth | ||
81 | object. The client then must send another request with the sent \$PIN | ||
82 | (via GET /truth/\$TRUTH\_PUB?response=\$PIN). The server can now check | ||
83 | if the two PINs match. Upon success, the server returns the encrypted | ||
84 | key share. | ||
85 | |||
86 | \paragraph{Video identification (vid)} | ||
87 | |||
88 | This method allows the user to identify via video-call. Since the | ||
89 | respective images must be passed on to the video identification | ||
90 | service in the event of password recovery, it must be ensured that no | ||
91 | further information about the user can be derived from them. Hence, | ||
92 | the user's client software must try to delete metadata that could | ||
93 | result in accidental information leakage about the user from the image | ||
94 | before encrypting and uploading it to the Anastasis provider. | ||
95 | |||
96 | For recovery, the user must first send a request to server that they | ||
97 | wants to authorize recovery (GET /truth/\$TRUTH\_PUB). The Anastasis | ||
98 | provider will then decrypt the user's image and send a request with a | ||
99 | \$TOKEN to a video authentication provider that a user wants to | ||
100 | authenticate, and respond to the user with a link to a video | ||
101 | conference. The video authentication provider then checks via video | ||
102 | conference that the user in the image is the same that they have on | ||
103 | the video link. Upon success, the video provider releases the \$TOKEN | ||
104 | to the user. The client then must send another request with the | ||
105 | \$TOKEN (via GET /truth/\$TRUTH\_PUB?response=\$TOKEN). The Anastasis | ||
106 | provider checks that the tokens match, and upon success returns the | ||
107 | encrypted key share. | ||
108 | |||
109 | \paragraph{Post identification (post)} | ||
110 | |||
111 | The user tells the Anastasis provider with a request that they want | ||
112 | to authenticate using Post identification (GET /truth/\$TRUTH\_PUB). The | ||
113 | Anastasis provider uses the request to decrypt the user's truth to | ||
114 | determine the user's postal address, and sends them letter containing | ||
115 | a \$PIN. Upon receiving the letter, the client then has to send | ||
116 | another request with the \$PIN (GET /truth/\$TRUTH\_PUB?response=\$PIN). The | ||
117 | server can now check if the two PINs match. Upon success the server | ||
118 | will release the encrypted key share. | ||
119 | |||
120 | \paragraph{Security question (qa)} | ||
121 | |||
122 | The user provided Anastasis with a secure question and a (normalized) | ||
123 | answer. The secure question becomes part of the encrypted recovery | ||
124 | document, and is never disclosed to weak adversaries, even during | ||
125 | recovery. The encrypted truth on the server only contains a (salted) | ||
126 | hash of the answer. The Anastasis provider cannot learn the plaintext | ||
127 | answer. Because of the salt, and it cannot mount a confirmation attack | ||
128 | either. | ||
129 | |||
130 | If the user wants to recover the key share from the server, they must | ||
131 | provide the (salted) hash of the answer to the security question (via | ||
132 | GET /truth/\$TRUTH\_PUB?response=\$HASH). The server then checks if the | ||
133 | stored and the provided hash match. Upon success the server responds | ||
134 | with the encrypted key share. | ||