Cut down the text in SECURITY.md, add graphs

2 files changed, 38 insertions, 88 deletions

diff --git a/Documentation/SECURITY.md b/Documentation/SECURITY.md
index 4db4c24..e9e1015 100644
--- a/Documentation/SECURITY.md
+++ b/Documentation/SECURITY.md
@@ -1,92 +1,42 @@
 GoCryptFS Security
 ==================
 
-"Security" can be split into "Confidentiality" and "Integrity". The
-security level gocryptfs provides for each is discussed in the next
-sections.
-
-Confidentiality
----------------
-
-Confidentiality means that information cannot be extracted from the
-encrypted data unless you know the key.
-
-### File Contents
-
-* All file contents (even the last bytes) are encrypted using AES-256-GCM
- * This is unbreakable in the foreseeable future. Attacks will focus on
-   cracking the password instead (see section "Master Key Storage").
-* Files are segmented into 4096 byte blocks
-* Each block gets a fresh random 96 bit IV (none) each time it is written.
- * This means that identical blocks can not be identified
-
-### File Names
-
-* File names are encrypted using AES-256-CBC with a per-directory IV
-* Each directory get a random 128 bit IV on creation
- * Files with the same name in different directories are encrypted to
-   different filenames and can not be identified
-* File names are padded to multiples of 16 bytes
- * This means that the exact length of the name is hidden, only length
-  ranges (1-16 bytes, 17-32 bytes etc.) can be determined from the encrypted
-  files
+Master Key Storage
+------------------
 
-### Metadata
+The master key is used to perform content and file name encryption.
+It is stored in `gocryptfs.conf`, encrypted with AES-256-GCM using the
+Key Encryption Key (KEK).
 
-* The size of the file is not hidden. The exact file size can be calculated
-  from the size of the encrypted file.
-* File owner, file permissions and timestamps are not hidden.
+The KEK is generated from the user password using `scrypt`.
 
-Integrity
----------
+![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/master-key.svg)
 
-Integrity means that the data cannot be modified in a meaningful way
-unless you have the key. The opposite of integrity is *malleability*.
+File Contents
+-------------
 
-### File Contents
+All file contents are encrypted using AES-256-GCM.
 
-* The used encryption, AES-256-GCM, is a variant of
-  *authenticated encryption*. Each block gets a 128 bit authentication
-  tag (GMAC) appended.
- * This means that any modification inside a block will be detected when reading
-   the block and decryption will be aborted. The failure is logged and an
-   I/O error is returned to the user.
-* Every file has a header that contains a 16-byte random *file id*
-* Each block uses the file id and its block number as GCM *authentication data*
- * This means the position of the blocks is protected as well. The blocks
-   can not be reordered or copied between different files without
-   causing an decryption error.
-* For technical reasons (sparse files), the special "all-zero" block is
-  always seen as a valid block that decrypts to all-zero plaintext.
- * This means that whole blocks can be zeroed out
+Files are segmented into 4KB blocks. Each block gets a fresh random
+96 bit IV each time it is modified. A 128-bit authentication tag (GHASH)
+protects each block from modifications.
 
-### File Names
+Each file has a header containing a random 128-bit file ID. The
+file ID and the block number are mixed into the GHASH as
+*additional authenticated data*. The prevents blocks from being copied
+between or within files.
 
-* File names are only weakly protected against modifications.
- * Changing a single byte causes a decode error in most of the
-   cases. The failure is logged and the file is no longer visible in the
-   directory.
- * If no decode error is triggered, at least 16 bytes of the filename will
-   be corrupted (randomized).
-* However, file names can always be truncated to multiples of 16 bytes.
+![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/file-content-encryption.svg)
 
-### Metadata
+To support sparse files, all-zero blocks are accepted and passed through
+unchanged.
 
-* The file size is not protected against modifications
- * However, the block integrity protection limits modifications to block
-   size granularity.
- * This means that files can be truncated to multiples of 4096 bytes.
-* Ownership, timestamp and permissions are not protected and can be changed
-  as usual.
+File Names
+----------
 
-Master Key Storage
-------------------
+Every directory gets a 128-bit directory IV that is stored in each
+directory as `gocryptfs.diriv`.
 
-The *master key* is used to perform content and file name encryption.
-It is stored in `gocryptfs.conf`, encrypted with AES-256-GCM using the
-*unlock key*.
+File names are encrypted using AES-256-CBC with the directory IV.
 
-The unlock key is generated from a user password using `scrypt`.
-A successful decryption of the master key means that the GMAC authentication
-passed and the password is correct. The master key is then used to
-mount the filesystem.
+![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/file-name-encryption.svg)
diff --git a/Documentation/master-key.svg b/Documentation/master-key.svg
index 096e890..dff9a9a 100644
--- a/Documentation/master-key.svg
+++ b/Documentation/master-key.svg
@@ -103,8 +103,8 @@
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
      inkscape:zoom="1.4"
-     inkscape:cx="356.2081"
-     inkscape:cy="-20.641831"
+     inkscape:cx="432.9172"
+     inkscape:cy="-9.3512986"
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      showgrid="true"
@@ -123,8 +123,8 @@
        id="grid4153"
        dotted="true"
        units="mm"
-       spacingx="7.0866142"
-       spacingy="7.0866143"
+       spacingx="3.543307"
+       spacingy="3.543307"
        originx="-14.173228"
        originy="-940.93176" />
   </sodipodi:namedview>
@@ -183,14 +183,14 @@
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:90.10359192px;line-height:125%;font-family:Arial;-inkscape-font-specification:'Arial Bold';letter-spacing:67.72786713px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        x="66.150955"
-       y="98.171463"
+       y="96.744003"
        id="text4155-8"
        sodipodi:linespacing="125%"
-       transform="scale(0.99921743,1.0007832)"><tspan
+       transform="scale(0.99921742,1.0007832)"><tspan
          sodipodi:role="line"
          id="tspan4157-1"
          x="66.150955"
-         y="98.171463"
+         y="96.744003"
          style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:15.01726532px;font-family:sans-serif;-inkscape-font-specification:sans-serif;letter-spacing:0px">User password</tspan></text>
     <text
        xml:space="preserve"
@@ -221,10 +221,10 @@
     <rect
        style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
        id="rect4271"
-       width="180.77509"
-       height="21.300983"
-       x="32.295944"
-       y="82.542801" />
+       width="201.96851"
+       height="21.259884"
+       x="21.259844"
+       y="81.49601" />
     <rect
        style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
        id="rect3336-9-4-2"
@@ -254,7 +254,7 @@
        sodipodi:nodetypes="cc" />
     <path
        style="opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker-end:url(#Arrow1Mend-9)"
-       d="M 216.95674,93.498458 285.25749,80.265566"
+       d="M 226.5996,93.141315 285.25749,80.265566"
        id="path4296-9"
        inkscape:connector-curvature="0"
        sodipodi:nodetypes="cc" />