libgocryptfs/Documentation/SECURITY.md

48 lines
1.5 KiB
Markdown
Raw Normal View History

2015-10-06 23:20:21 +02:00
GoCryptFS Security
==================
Master Key Storage
------------------
2015-10-06 23:20:21 +02:00
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).
2015-10-06 23:20:21 +02:00
The KEK is generated from the user password using `scrypt`.
2015-10-06 23:20:21 +02:00
![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/master-key.svg)
2015-10-06 23:20:21 +02:00
File Contents
-------------
2015-10-06 23:20:21 +02:00
2015-12-08 16:41:45 +01:00
All file contents are encrypted using AES-256-GCM (Galois/Counter Mode).
2015-10-06 23:20:21 +02:00
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.
2015-10-06 23:20:21 +02:00
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.
2015-10-06 23:20:21 +02:00
![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/file-content-encryption.svg)
2015-10-06 23:20:21 +02:00
To support sparse files, all-zero blocks are accepted and passed through
unchanged.
2015-10-06 23:20:21 +02:00
File Names
----------
2015-10-06 23:20:21 +02:00
Every directory gets a 128-bit directory IV that is stored in each
directory as `gocryptfs.diriv`.
2015-10-06 23:20:21 +02:00
2015-12-08 16:41:45 +01:00
File names are encrypted using AES-256-EME (ECB-Mix-ECB wide-block encryption,
see https://github.com/rfjakob/eme for details) with the directory IV
as initialization vector. EME fixes the prefix leak that occours with CBC
encryption.
2015-10-06 23:20:21 +02:00
![](https://rawgit.com/rfjakob/gocryptfs/master/Documentation/file-name-encryption.svg)
2015-12-08 16:41:45 +01:00
The Base64 encoding limits the usable filename length to 176 characters.