commit 77065e31d20b680ebd7e922e4b2a1b8769b385e7
parent 92a26a59760f5289b63a68d7c6bf459be2c02705
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 29 Mar 2021 12:36:41 +0200
document security question key share encryption
Diffstat:
1 file changed, 26 insertions(+), 1 deletion(-)
diff --git a/anastasis.rst b/anastasis.rst
@@ -226,7 +226,7 @@ key material using an HKDF over a nonce and the kdf_id.
**prekey**: Original key material.
**nonce**: 32-byte nonce, must never match "ver" (which it cannot as the length is different). Of course, we must
-avoid key reuse. So, we have to use different nonces to get different keys and ivs (see below).
+avoid key reuse. So, we have to use different nonces to get different keys and IVs (see below).
**key**: Symmetric key which is later used to encrypt the documents with AES256-GCM.
@@ -273,6 +273,31 @@ at the various providers.
**nonce_i**: Nonce which is used to generate *key_i* and *iv_i* which are used for the encryption of the **key share**. **i** must be
the same number as specified above for *encrypted_key_share_i*. Nonce must contain the string "EKS" plus the according *i*.
+As a special rule, when a **security question** is used to authorize access to an
+**encrypted_key_share_i**, then the salt "eks" is replaced with an (expensive) hash
+of the answer to the security question as an additional way to make the key share
+inaccessible to those who do not have the answer:
+
+.. code-block:: none
+
+ powh = POW_HASH (qsalt, answer)
+ ekss = HKDF("Anastasis-secure-question-uuid-salting",
+ powh,
+ uuid);
+ (iv_i, key_i) = HKDF(key_id, nonce_i, ekss, [optional data], keysize + ivsize)
+
+
+**qsalt**: salt value used to hash answer to satisfy the challenge to prevent the provider from determining the answer via guessing.
+
+**answer**: answer to the security question, in UTF-8, as entered by the user.
+
+**powh**: result of the (expensive, proof-of-work) hash algorithm.
+
+**uuid**: UUID of the challenge associated with the security question and the encrypted key share.
+
+**ekss**: Replacement salt to be used instead of "eks" when deriving the key to encrypt/decrypt the key share.
+
+
Signatures
----------
