summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/anastasis.texi65
1 files changed, 34 insertions, 31 deletions
diff --git a/doc/anastasis.texi b/doc/anastasis.texi
index a5d8b11..c103f7a 100644
--- a/doc/anastasis.texi
+++ b/doc/anastasis.texi
@@ -424,27 +424,31 @@ to recover their core secret.
@subsection The recovery document
-A @strong{recovery document} includes all of the information a user needs to
-recover access to their core secret. It specifies a set of @strong{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 identification or a security question. For each escrow
-method, the Anastasis server is provided with @strong{truth}, that is data the
-Anastasis operator may learn during the recovery process to authenticate the
-user. Examples for truth would be a phone number (for SMS), a picture of the
-user (for video identification), or the (hash of) a security answer. A strong
-adversary is assumed to be able to learn the truth, while weak adversaries
-must not. In addition to a set of escrow methods and associated Anastasis
-server operators, the @strong{recovery document} also specifies @strong{policies}, which
-describe the combination(s) of the escrow methods that suffice to obtain
-access to the core secret. For example, a @strong{policy} could say that the
-escrow methods (A and B) suffice, and a second policy may permit (A and C). A
-different user may choose to use the policy that (A and B and C) are all
+A @strong{recovery document} includes all of the information a user
+needs to recover access to their core secret. It specifies a set of
+@strong{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 identification or a
+security question. For each escrow method, the Anastasis server is
+provided with @strong{truth}, that is data the Anastasis operator may
+learn during the recovery process. Truth always consists of an
+encrypted key share and associated data to authenticate the user.
+Examples for truth would be a phone number (for SMS), a picture of the
+user (for video identification), or the (hash of) a security answer.
+A strong adversary is assumed to be able to learn the truth, while
+weak adversaries must not. In addition to a set of escrow methods and
+associated Anastasis server operators, the @strong{recovery document}
+also specifies @strong{policies}, which describe the combination(s) of
+the escrow methods that suffice to obtain access to the core secret.
+For example, a @strong{policy} could say that the escrow methods (A
+and B) suffice, and a second policy may permit (A and C). A different
+user may choose to use the policy that (A and B and C) are all
required. Anastasis imposes no limit on the number of policies in a
-@strong{recovery document}, or the set of providers or escrow methods involved in
-guarding a user’s secret. Weak adversaries must not be able to deduce
-information about a user’s @strong{recovery document} (except for its length, which
-may be exposed to an adversary which monitors the user’s network traffic).
+@strong{recovery document}, or the set of providers or escrow methods
+involved in guarding a user’s secret. Weak adversaries must not be
+able to deduce information about a user’s @strong{recovery document}
+(except for its length, which may be exposed to an adversary which
+monitors the user’s network traffic).
@c This file is part of Anastasis
@c Copyright (C) 2019-2021 Anastasis SARL
@@ -2269,9 +2273,15 @@ interface DecryptionPolicy @{
@anchor{rest managing-truth}@anchor{51}@anchor{rest truth}@anchor{52}
@subsubsection Managing truth
+Truth always consists of an encrypted key share and encrypted
+authentication data. The key share and the authentication data
+are encrypted using different keys. Additionally, truth includes
+the name of the authentication method, the mime-type of the
+authentication data, and an expiration time in
+cleartext.
-This API is used by the Anastasis client to deposit @strong{truth} or request a (encrypted) @strong{key share} with
-the escrow provider.
+This API is used by the Anastasis client to deposit @strong{truth} or
+request a (encrypted) @strong{key share} with the escrow provider.
An @strong{escrow method} specifies an Anastasis provider and how the user should
authorize themself. The @strong{truth} API allows the user to provide the
@@ -2343,13 +2353,6 @@ interface TruthUploadRequest @{
// Key share method, i.e. "security question", "SMS", "e-mail", ...
type: string;
- // Nonce used to compute the (iv,key) pair for encryption of the
- // encrypted_truth.
- nonce: [32]; //bytearray
-
- // Authentication tag of `@w{`}encrypted_truth`@w{`}.
- 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, ...
@@ -2357,10 +2360,10 @@ interface TruthUploadRequest @{
//
// The nonce of the HKDF for this encryption must include the
// string "ECT".
- encrypted_truth: [80]; //bytearray
+ encrypted_truth: []; //bytearray
// MIME type of truth, i.e. text/ascii, image/jpeg, etc.
- truth_mime: string;
+ truth_mime?: string;
// For how many years from now would the client like us to
// store the truth?