aboutsummaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJakob Unterwurzacher2015-12-19 14:41:39 +0100
committerJakob Unterwurzacher2015-12-19 15:02:29 +0100
commit1caa9258685fa5fad8935d3bfcd0eac7d7f84f1e (patch)
treeabc1e46f269f9ef8f05d812e13fcdf2bae68d298 /Documentation
parent88826dc51d7919ef8b190c079955230e653323e2 (diff)
Increase GCM IV size from 96 to 128 bits
This pushes back the birthday bound for collisions to make it virtually irrelevant.
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/MANPAGE.md5
-rw-r--r--Documentation/SECURITY.md2
-rw-r--r--Documentation/file-format.md32
3 files changed, 38 insertions, 1 deletions
diff --git a/Documentation/MANPAGE.md b/Documentation/MANPAGE.md
index 446ce37..2e440b2 100644
--- a/Documentation/MANPAGE.md
+++ b/Documentation/MANPAGE.md
@@ -57,6 +57,11 @@ to mount the gocryptfs filesytem without user interaction.
**-fusedebug**
: Enable fuse library debug output
+**-gcmiv128**
+: Use an 128-bit IV for GCM encryption instead of Go's default of
+96 bits (default true). This pushes back the birthday bound for IV
+collisions far enough to make it irrelevant.
+
**-init**
: Initialize encrypted directory
diff --git a/Documentation/SECURITY.md b/Documentation/SECURITY.md
index dff2fab..a49994a 100644
--- a/Documentation/SECURITY.md
+++ b/Documentation/SECURITY.md
@@ -18,7 +18,7 @@ File Contents
All file contents are encrypted using AES-256-GCM (Galois/Counter Mode).
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)
+128 bit IV each time it is modified. A 128-bit authentication tag (GHASH)
protects each block from modifications.
Each file has a header containing a random 128-bit file ID. The
diff --git a/Documentation/file-format.md b/Documentation/file-format.md
new file mode 100644
index 0000000..b0d4b55
--- /dev/null
+++ b/Documentation/file-format.md
@@ -0,0 +1,32 @@
+File Format
+===========
+
+Header
+
+ 2 bytes header version (big endian uint16, currently 2)
+ 16 bytes file id
+
+Data block
+
+ 16 bytes GCM IV (nonce)
+ 1-4096 bytes encrypted data
+ 16 bytes GHASH
+
+
+Example: 1-byte file
+--------------------
+
+ Header 18 bytes
+ Data block 33 bytes
+
+Total: 51 bytes
+
+
+Example: 5000-byte file
+-----------------------
+
+ Header 18 bytes
+ Data block 4128 bytes
+ Data block 936 bytes
+
+Total: 5082 bytes