diff options
Diffstat (limited to 'doc/sphinx/authentication.rst')
-rw-r--r-- | doc/sphinx/authentication.rst | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/doc/sphinx/authentication.rst b/doc/sphinx/authentication.rst new file mode 100644 index 0000000..fc516fc --- /dev/null +++ b/doc/sphinx/authentication.rst | |||
@@ -0,0 +1,110 @@ | |||
1 | .. | ||
2 | This file is part of Anastasis | ||
3 | Copyright (C) 2019-2021 Anastasis SARL | ||
4 | |||
5 | Anastasis is free software; you can redistribute it and/or modify it under the | ||
6 | terms of the GNU Affero General Public License as published by the Free Software | ||
7 | Foundation; either version 2.1, or (at your option) any later version. | ||
8 | |||
9 | Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY | ||
10 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR | ||
11 | A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. | ||
12 | |||
13 | You should have received a copy of the GNU Affero General Public License along with | ||
14 | Anastasis; see the file COPYING. If not, see <http://www.gnu.org/licenses/> | ||
15 | |||
16 | @author Christian Grothoff | ||
17 | @author Dominik Meister | ||
18 | @author Dennis Neufeld | ||
19 | |||
20 | |||
21 | .. _anastasis-auth-methods: | ||
22 | |||
23 | ---------------------- | ||
24 | Authentication Methods | ||
25 | ---------------------- | ||
26 | |||
27 | This section describes the supported authentication methods in detail. We | ||
28 | note that the server implements rate limiting for all authentication methods | ||
29 | to ensure that malicious strong attackers cannot guess the values by | ||
30 | brute-force. Typically, a user is given three attempts per hour to enter the | ||
31 | correct code from 2^63 possible values. Transmitted codes also come with an | ||
32 | expiration date. If the user re-requests a challenge to be sent, the same | ||
33 | challenge may be transmitted (with the three attempts counter not increasing!) | ||
34 | for a limited period of time (depending on the authentication method) before | ||
35 | the service eventually rotates to a fresh random code with a fresh retry | ||
36 | counter. Given the default value range and time intervals (which providers are | ||
37 | at liberty to adjust), brute-force attacks against this are expected to | ||
38 | succeed with a 50% probability after about 200000 years of attempts at the | ||
39 | maximum permissible frequency. | ||
40 | |||
41 | |||
42 | SMS (sms) | ||
43 | ^^^^^^^^^ | ||
44 | |||
45 | Sends an SMS with a code (prefixed with ``A-``) to the user's phone, including | ||
46 | a UUID which identifies the challenge the code is for. The user must send | ||
47 | this code back with his request (see ``$RESPONSE`` under :ref:`Truth`). | ||
48 | If the transmitted code is correct, the server responses with the requested | ||
49 | encrypted key share. | ||
50 | |||
51 | |||
52 | |||
53 | Email verification (email) | ||
54 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
55 | |||
56 | Sends an email with a code (prefixed with ``A-``) to the user's mail address, | ||
57 | including a UUID which identifies the challenge the code is for. The user | ||
58 | must send this code back with his request (see ``$RESPONSE`` under :ref:`Truth`). | ||
59 | If the transmitted code is correct, the server responses with the | ||
60 | requested encrypted key share. | ||
61 | |||
62 | |||
63 | Video identification (vid) | ||
64 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
65 | |||
66 | Requires the user to identify via video-call. In the video-call, the | ||
67 | user is told the code (prefixed with ``A-``) needed to authenticate. | ||
68 | |||
69 | The user is expected to delete all metadata revealing personal information | ||
70 | from the images before uploading them. Since the respective images must be | ||
71 | passed on to the video identification service in the event of password | ||
72 | recovery, it should be ensured that no further information about the user can | ||
73 | be derived from them. | ||
74 | |||
75 | Video identification will typically result in the Anastasis provider | ||
76 | requesting the user to be redirected to a Web site (or other URL) for the | ||
77 | video-call. | ||
78 | |||
79 | |||
80 | |||
81 | Security question (qa) | ||
82 | ^^^^^^^^^^^^^^^^^^^^^^ | ||
83 | |||
84 | Asks the user a security question. The user sends back a **salted** | ||
85 | hash over the answer. The **question-salt** is stored encrypted as | ||
86 | part of the recovery document and never revealed to the providers. This | ||
87 | ensures that providers cannot derive the answer from the hash value. | ||
88 | Furthermore, the security question itself is also only in the recovery | ||
89 | document and never given to the Anastasis provider. A moderately expensive | ||
90 | hash function is used to further limit strong attackers that have obtained | ||
91 | the recovery document from brute-forcing the answer. | ||
92 | |||
93 | If the hash value matches with the one the server is expecting, the server | ||
94 | answers with the requested encrypted key share. However, unlike other | ||
95 | encrypted key shares, the encrypted key share of a security question uses a | ||
96 | special variation of the Anastasis encryption: Here, a different hash function | ||
97 | over the security answer is used to provide an additional **key-salt** for the | ||
98 | decryption of the (encrypted) **key share**. This ensures that the key share | ||
99 | remains irrecoverable without the answer even if the Anastasis provider | ||
100 | storing the security question is malicious. | ||
101 | |||
102 | |||
103 | Snail mail verification (post) | ||
104 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
105 | |||
106 | Sends physical mail (snail mail) with a code (prefixed with ``A-``) to the | ||
107 | user's mail address, including a UUID which identifies the challenge the code | ||
108 | is for. The user must send this code back with their request (see | ||
109 | ``$RESPONSE`` under :ref:`Truth`). If the transmitted code is correct, | ||
110 | the server responds with the requested encrypted key share. | ||