From 3cc26af6c35fb4901b60949b93f93b5934e72ed3 Mon Sep 17 00:00:00 2001
From: Jakob Unterwurzacher
Date: Sun, 30 Oct 2016 20:51:36 +0100
Subject: Add reverse mode page
---
docs/img/reverse-derivePathIV.svg | 368 ++++++++++++
docs/img/reverse-file-content-encryption.svg | 831 +++++++++++++++++++++++++++
docs/reverse_mode.md | 59 ++
mkdocs.yml | 1 +
4 files changed, 1259 insertions(+)
create mode 100644 docs/img/reverse-derivePathIV.svg
create mode 100644 docs/img/reverse-file-content-encryption.svg
create mode 100644 docs/reverse_mode.md
diff --git a/docs/img/reverse-derivePathIV.svg b/docs/img/reverse-derivePathIV.svg
new file mode 100644
index 0000000..622cec1
--- /dev/null
+++ b/docs/img/reverse-derivePathIV.svg
@@ -0,0 +1,368 @@
+
+
+
+
diff --git a/docs/img/reverse-file-content-encryption.svg b/docs/img/reverse-file-content-encryption.svg
new file mode 100644
index 0000000..20e7e39
--- /dev/null
+++ b/docs/img/reverse-file-content-encryption.svg
@@ -0,0 +1,831 @@
+
+
+
+
diff --git a/docs/reverse_mode.md b/docs/reverse_mode.md
new file mode 100644
index 0000000..3f92edb
--- /dev/null
+++ b/docs/reverse_mode.md
@@ -0,0 +1,59 @@
+Reverse Mode
+============
+
+In **reverse mode**, gocryptfs provides an encrypted view of a
+plain-text directory. The primary use-case are encrypted backups.
+
+To make reverse mode useful, it uses deterministic encryption using
+AES-SIV instead of AES-GCM.
+
+The differences with respect to the "normal" (forward) mode as detailed
+on the [Security](security) page are listed below.
+
+File Contents
+-------------
+
+File contents are encrypted using AES-SIV-512 (RFC5297). The 512-bit
+AES-SIV key is derived from the 256-bit master key by hashing it with
+SHA512.
+
+All values that are random in forward mode (File ID, Block IV)
+are instead deterministically derived from the encrypted path,
+essentially using a salted hash (detailed in the section "derivePathIV").
+As all derived values are explicitely stored in the ciphertext file,
+decryption does not depend on knowledge of the derivation.
+
+The encryption process is shown in the diagram below.
+
+
+
+Notes:
+
+1. The IV is passed to AES-SIV as described in section 3 of RFC5297
+2. The block number N is contained in the IV as well as in the AAD.
+ Either one or the other would suffice, but this construction simplifies
+ the decryption process by keeping it identical to forward mode.
+ The "duplication" is considered to not have
+ any security impact because S2V (RFC5297 section 2.4) hashes IV and
+ AAD independently before XORing them together.
+
+File Names
+----------
+
+File name encryption is identical to forward mode, with the exception
+that the directory IV (stored in `gocryptfs.diriv`) is not random.
+It is deterministically derived, using derivePathIV, from the encrypted
+path to the directory.
+
+Because the encrypted path to the root directory is "" (the empty string),
+this means that the directory IV in the root directory is always
+`0xa8f7bac432ddc1cb3dc74e684d6ae48b = SHA256("\0DIRIV")`.
+
+derivePathIV: Derive IVs from Encrypted Paths
+----------------------------------------------
+
+derivePathIV concatenates that encrypted path with a null byte and a
+salt string, one of "DIRIV", "FILEID", "BLOCK0IV". The truncated
+SHA256-hashes of each are the outputs.
+
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 455bee7..1f10dc1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -6,6 +6,7 @@ pages:
- Quickstart: quickstart.md
- Compile from Source: compile.md
- Security: security.md
+- Reverse Mode: reverse_mode.md
- Comparison with Other Projects: comparison.md
- Signed Releases: releases.md
- Source Code Mirrors: mirrors.md
--
cgit v1.2.3