diff options
Diffstat (limited to 'docs/security.md')
| -rw-r--r-- | docs/security.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..49bfa8a --- /dev/null +++ b/docs/security.md @@ -0,0 +1,51 @@ +gocryptfs Security +================== + +gocryptfs builts upon well-known cryptographic primitives: scrypt for +key derivation, AES-GCM for file content encryption and, as a world's +first for encrypted filesystems, EME for file name encryption. + +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 +Key Encryption Key (KEK). + +The KEK is generated from the user password using `scrypt`. + + + +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 +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 +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. + + + +To support sparse files, all-zero blocks are accepted and passed through +unchanged. + +File Names +---------- + +Every directory gets a 128-bit directory IV that is stored in each +directory as `gocryptfs.diriv`. + +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. + + + +The Base64 encoding limits the usable filename length to 176 characters. |