aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJakob Unterwurzacher2015-10-06 23:20:21 +0200
committerJakob Unterwurzacher2015-10-06 23:20:21 +0200
commit31e14936be171855c49edc0922bc109b5a1e4d65 (patch)
tree10975952c8d67b3d00ae6fd36b77c63882a11e2c
parent8ec16c165d10ddce029b5016bc4a40c99bc58710 (diff)
Split off SECURITY.md
-rw-r--r--README.md99
-rw-r--r--SECURITY.md94
2 files changed, 99 insertions, 94 deletions
diff --git a/README.md b/README.md
index 91e5754..1f26cf1 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,9 @@ 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).
+For details on the security of GoCryptFS see the
+[SECURITY.md](https://github.com/rfjakob/gocryptfs/blob/master/SECURITY.md)
+document.
Current Status
--------------
@@ -20,99 +23,6 @@ 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.
-
-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 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
- ranges (1-16 bytes, 17-32 bytes etc.) can be determined from the encrypted
- files
-* For technical reasons, no IV is used
- * 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
----------
-
-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
-
-* 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.
-* Each block uses its block number as GCM *authentication data*
- * This means the position of the blocks is protected as well. The blocks
- can not be reordered without causing an decryption error.
-* 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.
-
-### File Names
-
-* File names are only weakly protected against modifications.
- * Changing a single byte causes a decode error in at least 255 of 256
- 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.
-
-### 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
-----------
@@ -121,7 +31,8 @@ Performance
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
Run `./benchmark.bash` to run the test suite and the streaming read/write
-benchmark.
+benchmark. The benchmark is run twice, first with native Go crypto and
+second using openssl.
The output should look like this:
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..dcd16c5
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,94 @@
+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 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
+ ranges (1-16 bytes, 17-32 bytes etc.) can be determined from the encrypted
+ files
+* For technical reasons, no IV is used
+ * 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
+---------
+
+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
+
+* 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.
+* Each block uses its block number as GCM *authentication data*
+ * This means the position of the blocks is protected as well. The blocks
+ can not be reordered without causing an decryption error.
+* However, proper affiliation of a block to the file is can not be verified.
+ * 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
+ always seen as a valid block that decrypts to all-zero plaintext.
+ * This means that whole blocks can be zeroed out
+
+### File Names
+
+* 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.
+
+### 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
+ as usual.
+
+Master Key Storage
+------------------
+
+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*.
+
+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.