aboutsummaryrefslogtreecommitdiff
path: root/doc/sphinx/authentication.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sphinx/authentication.rst')
-rw-r--r--doc/sphinx/authentication.rst110
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----------------------
24Authentication Methods
25----------------------
26
27This section describes the supported authentication methods in detail. We
28note that the server implements rate limiting for all authentication methods
29to ensure that malicious strong attackers cannot guess the values by
30brute-force. Typically, a user is given three attempts per hour to enter the
31correct code from 2^63 possible values. Transmitted codes also come with an
32expiration date. If the user re-requests a challenge to be sent, the same
33challenge may be transmitted (with the three attempts counter not increasing!)
34for a limited period of time (depending on the authentication method) before
35the service eventually rotates to a fresh random code with a fresh retry
36counter. Given the default value range and time intervals (which providers are
37at liberty to adjust), brute-force attacks against this are expected to
38succeed with a 50% probability after about 200000 years of attempts at the
39maximum permissible frequency.
40
41
42SMS (sms)
43^^^^^^^^^
44
45Sends an SMS with a code (prefixed with ``A-``) to the user's phone, including
46a UUID which identifies the challenge the code is for. The user must send
47this code back with his request (see ``$RESPONSE`` under :ref:`Truth`).
48If the transmitted code is correct, the server responses with the requested
49encrypted key share.
50
51
52
53Email verification (email)
54^^^^^^^^^^^^^^^^^^^^^^^^^^
55
56Sends an email with a code (prefixed with ``A-``) to the user's mail address,
57including a UUID which identifies the challenge the code is for. The user
58must send this code back with his request (see ``$RESPONSE`` under :ref:`Truth`).
59If the transmitted code is correct, the server responses with the
60requested encrypted key share.
61
62
63Video identification (vid)
64^^^^^^^^^^^^^^^^^^^^^^^^^^
65
66Requires the user to identify via video-call. In the video-call, the
67user is told the code (prefixed with ``A-``) needed to authenticate.
68
69The user is expected to delete all metadata revealing personal information
70from the images before uploading them. Since the respective images must be
71passed on to the video identification service in the event of password
72recovery, it should be ensured that no further information about the user can
73be derived from them.
74
75Video identification will typically result in the Anastasis provider
76requesting the user to be redirected to a Web site (or other URL) for the
77video-call.
78
79
80
81Security question (qa)
82^^^^^^^^^^^^^^^^^^^^^^
83
84Asks the user a security question. The user sends back a **salted**
85hash over the answer. The **question-salt** is stored encrypted as
86part of the recovery document and never revealed to the providers. This
87ensures that providers cannot derive the answer from the hash value.
88Furthermore, the security question itself is also only in the recovery
89document and never given to the Anastasis provider. A moderately expensive
90hash function is used to further limit strong attackers that have obtained
91the recovery document from brute-forcing the answer.
92
93If the hash value matches with the one the server is expecting, the server
94answers with the requested encrypted key share. However, unlike other
95encrypted key shares, the encrypted key share of a security question uses a
96special variation of the Anastasis encryption: Here, a different hash function
97over the security answer is used to provide an additional **key-salt** for the
98decryption of the (encrypted) **key share**. This ensures that the key share
99remains irrecoverable without the answer even if the Anastasis provider
100storing the security question is malicious.
101
102
103Snail mail verification (post)
104^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
105
106Sends physical mail (snail mail) with a code (prefixed with ``A-``) to the
107user's mail address, including a UUID which identifies the challenge the code
108is for. The user must send this code back with their request (see
109``$RESPONSE`` under :ref:`Truth`). If the transmitted code is correct,
110the server responds with the requested encrypted key share.