Update README.md

README.md

@@ -9,6 +9,20 @@ LoopbackFileSystem API.
 This project was inspired by [EncFS](https://github.com/vgough/encfs)
 and strives to fix its security issues (see EncFS tickets 9, 13, 14, 16).
 
+Current Status
+--------------
+* First public release
+* Feature-Complete
+* Passes the xfstests "generic" tests
+
+Install
+-------
+
+	go get github.com/rfjakob/gocryptfs
+
+Security
+--------
+
 "Security" can be split into "Confidentiality" and "Integrity". The
 security level gocryptfs provides for each is discussed in the next
 sections.
@@ -21,16 +35,16 @@ encrypted data unless you know the key.
 
 ### File Contents
 
-* File contents are encrypted using AES-128-GCM
+* 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
-* The size of the file is not hidden. The exact file size can be calculated
-  from the size of the encrypted file.
 
 ### File Names
 
-* File names are encrypted using AES-128-CBC because it is robust even
+* File names are encrypted using AES-256-CBC because it is robust even
   without using an IV
 * The file names are padded to multiples of 16 bytes
  * This means that the exact length of the name is hidden, only length
@@ -40,6 +54,12 @@ encrypted data unless you know the key.
  * This means that files with the same name within one gocryptfs filesystem
    always get the same encrypted name
 
+### Metadata
+
+* 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 either
+
 Integrity
 ---------
 
@@ -48,53 +68,58 @@ unless you have the key. The opposite of integrity is *malleability*.
 
 ### File Contents
 
-* The used encryption, AES-128-GCM, is a variant of
+* 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 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.
-* However, blocks can be copied around in the encrypted data.
+* Each block uses its block number as GCM *authentication data*
-  The block authentication tag only protects each individual block. It
+ * This means the position of the blocks is protected as well. The blocks
-  does not protect the ordering of blocks.
+   can not be reordered without causing an decryption error.
-* For technical reasons (file holes), the special "all-zero" block is
+* However, proper affiliation of a block to the file is not checked.
+ * This means that blocks can be copied between different files provided
+   that they stay at the same position. 
+* For technical reasons (sparse files), the special "all-zero" block is
   seen as a valid block that decrypts to an all-zero block.
 
-Design
+### File Names
-------
+
-* Authenticated encryption of file contents using AES-GCM-128
+* File names are only weakly protected against modifications.
- * Because GCM handles blocks of arbitrary size, there is no special handling for the last file block
+ * Changing a single byte causes a decode error in at least 255 of 256
- * 4096 byte blocks per default
+   cases. The failure is logged and the file is no longer visible in the
- * 28 bytes of overhead per block (16 bytes auth tag, 12 byte nonce)
+   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.
+
+### Metadata
+
+* 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
+
+Master Key Storage
+------------------
+
+The *master key* is used to perform file decryption and encryption.
+It is stored in `gocryptfs.conf` encrypted with AES-256-GCM using the
+*unlock key*.
+
+The unlock key is generated from a user password using `scrypt`.
+A sucessful decryption of the master key means that the authentication
+passed and the password is correct. The master key is then used to
+mount the filesystem.
+
+Performance
+-----------
+
+ * 28 bytes of storage overhead per block (16 bytes auth tag, 12 byte nonce)
  * uses openssl through [spacemonkeygo/openssl](https://github.com/spacemonkeygo/openssl)
    for a 3x speedup compared to `crypto/cipher` (see [go-vs-openssl.md](https://github.com/rfjakob/gocryptfs/blob/master/openssl_benchmark/go-vs-openssl.md)) for details
-* Per-write unique 96 bit nonces
- * starts from a random value (generated at mount time) and counts up
-* Flename encryption using AES-CBC-128
- * Padded to 16-byte blocks acc. to [RFC5652 section 6.3](https://tools.ietf.org/html/rfc5652#section-6.3)
- * base64 encoded acc. to [RFC4648 section 5](https://tools.ietf.org/html/rfc4648#section-5)
 
-Current Status
---------------
-Not ready for anything but testing and debugging
-
-* File and directory creation and deletion works
-* Thread-safe nonce generation works
-* Filename and content encryption works
- * Key is set to static all-zero
-* Reading and writing works
-* Streaming performance is already reasonable
- * But we should be able to get another 50% speedup
-* Symlinks and hard links not yet implemented
-* Memory usage is insane
-
-Install
--------
-
-	go get github.com/rfjakob/gocryptfs
-
-Testing
--------
 Run `./benchmark.bash` to run the test suite and the streaming read/write
 benchmark.