From 3bdfac5b4d4a6f3b1348b007f2bd98449b2cd86d Mon Sep 17 00:00:00 2001
From: Jakob Unterwurzacher
Date: Sat, 16 Sep 2017 16:08:12 +0200
Subject: Update forward mode crypto description for derived keys

---
 docs/forward_mode_crypto.md | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

(limited to 'docs/forward_mode_crypto.md')

diff --git a/docs/forward_mode_crypto.md b/docs/forward_mode_crypto.md
index 894f894..e9b4f47 100644
--- a/docs/forward_mode_crypto.md
+++ b/docs/forward_mode_crypto.md
@@ -1,9 +1,14 @@
-gocryptfs Security
-==================
+gocryptfs Cryptography
+======================
 
 gocryptfs builts upon well-known cryptographic primitives: scrypt for
 key derivation, AES-GCM for file content encryption and, as a world's
-first for encrypted filesystems, EME for file name encryption.
+first for encrypted filesystems,
+EME wide-block encryption for file name encryption.
+
+This page describes **forward mode**, the default mode of operation, where
+the files are stored encrypted on disk and the mounted filesystem provides
+a plaintext view.
 
 Master Key Storage
 ------------------
@@ -18,6 +23,16 @@ the master key is decrypted:
 
 ![](img/master-key.svg)
 
+Derived Keys
+------------
+
+Since gocryptfs v1.3, separate keys are derived from the master key for
+file content and file name encryption. HKDF-SHA256 is used for the
+derivation (source code: [ref1](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/cryptocore/hkdf.go)
+[ref2](https://github.com/rfjakob/gocryptfs/blob/f0e29d9b90b63d5fbe4164161ecb0e1035bb4af4/internal/cryptocore/cryptocore.go#L66)).
+
+![](img/derived-keys.svg)
+
 File Contents
 -------------
 
@@ -67,6 +82,15 @@ file, `gocryptfs.longname.[hash].name`.
 
 ![](img/longnames.svg)
 
+Example directory listing containing an 1 MiB encrypted file with a long name:
+
+```
+    Size Name
+      16 gocryptfs.diriv
+ 1056786 gocryptfs.longname.nONaEDDZOrwtQdXPH1SxSFkPtOc8srIyB82ZuduqG10
+     299 gocryptfs.longname.nONaEDDZOrwtQdXPH1SxSFkPtOc8srIyB82ZuduqG10.name
+```
+
 This method for storing long file names has zero performance impact
 for filenames that are <= 176 characters, incurs no extra disk accesses
 for opening a file with a long name, and just one extra file read for each
-- 
cgit v1.2.3