From 71c62583d81f149cef2bdbe13870da70b50f3cbd Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sat, 14 Aug 2021 10:45:50 +0200 Subject: -improve docs on what truth is, make truth_mime optional --- doc/anastasis.texi | 65 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 31 deletions(-) (limited to 'doc') 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? -- cgit v1.2.3