From 5dd5895e2355571d26655957b52b39f69e43c77d Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Sat, 16 Sep 2017 14:11:15 +0200 Subject: Rename "Security" to "Cryptography" --- docs/comparison.md | 2 +- docs/forward_mode_crypto.md | 76 +++++++++++++++++++++++++++++++++++++++++++++ docs/reverse_mode.md | 59 ----------------------------------- docs/reverse_mode_crypto.md | 59 +++++++++++++++++++++++++++++++++++ docs/security.md | 76 --------------------------------------------- mkdocs.yml | 4 +-- 6 files changed, 138 insertions(+), 138 deletions(-) create mode 100644 docs/forward_mode_crypto.md delete mode 100644 docs/reverse_mode.md create mode 100644 docs/reverse_mode_crypto.md delete mode 100644 docs/security.md diff --git a/docs/comparison.md b/docs/comparison.md index 8e60271..0e47ae1 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -134,7 +134,7 @@ General Security References: -[[1]](security.md) +[[1]](forward_mode_crypto.md) [[2]](https://github.com/vgough/encfs/blob/439c90e040cc04c036ee0791d830779a6d6bf10e/DESIGN.md) [[3]](https://cryptomator.org/architecture/) [[5]](https://github.com/netheril96/securefs/blob/2596467d63631aab264cf7a63de38fd69b2fda78/docs/design.md#lite-format-format-version-4) diff --git a/docs/forward_mode_crypto.md b/docs/forward_mode_crypto.md new file mode 100644 index 0000000..894f894 --- /dev/null +++ b/docs/forward_mode_crypto.md @@ -0,0 +1,76 @@ +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`. + +When mounting a filesystem, the user is prompted for the password and +the master key is decrypted: + +![](img/master-key.svg) + +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. + +![](img/file-content-encryption.svg) + +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 [github.com/rfjakob/eme](https://github.com/rfjakob/eme) for details) with the directory IV +as initialization vector. EME fixes the prefix leak that occours with CBC +encryption. + +![](img/file-name-encryption.svg) + +The Base64 encoding limits the usable filename length to 176 characters. +Filenames that are longer than that (longer than 255 characters in Base64- +encoded form) use long file name handling (since gocryptfs v0.9). + +Long File Name Handling +----------------------- + +If the Base64-encoded encrypted name is longer than 255 characters, +it cannot be used as the file name on disk, as Linux filesystems +do not allow names longer than that. + +Instead, the encrypted name is hashed, and the file content is stored in +`gocryptfs.longname.[hash]`. The long file name is stored in a support +file, `gocryptfs.longname.[hash].name`. + +![](img/longnames.svg) + +This method for storing long file names has zero performance impact +for filenames that are <= 176 characters, incurs no extra disk accesses +for opening a file with a long name, and just one extra file read for each +long-name file on readdir(1). + +Because the hash is only taken from the encrypted file name, there is no +security penalty for using long names. diff --git a/docs/reverse_mode.md b/docs/reverse_mode.md deleted file mode 100644 index b92cf40..0000000 --- a/docs/reverse_mode.md +++ /dev/null @@ -1,59 +0,0 @@ -Reverse Mode -============ - -In **reverse mode**, gocryptfs provides an encrypted view of a -plain-text directory. The primary use-case are encrypted backups. - -To make reverse mode useful, it uses deterministic encryption using -AES-SIV instead of AES-GCM. - -The differences with respect to the "normal" (forward) mode as detailed -on the [Security](security) page are listed below. - -File Contents -------------- - -File contents are encrypted using AES-SIV-512 (RFC5297). The 512-bit -AES-SIV key is derived from the 256-bit master key by hashing it with -SHA512. - -All values that are random in forward mode (File ID, Block IV) -are instead deterministically derived from the encrypted path, -essentially using a salted hash (detailed in the section "derivePathIV"). -As all derived values are explicitely stored in the ciphertext file, -decryption does not depend on knowledge of the derivation. - -The encryption process is shown in the diagram below. - -![](img/reverse-file-content-encryption.svg) - -Notes: - -1. The IV is passed to AES-SIV as described in section 3 of RFC5297 -2. The block number N is contained in the IV as well as in the AAD. - Either one or the other would suffice, but this construction simplifies - the decryption process by keeping it identical to forward mode. - The "duplication" is considered to not have - any security impact because S2V (RFC5297 section 2.4) hashes IV and - AAD independently before XORing them together. - -File Names ----------- - -File name encryption is identical to forward mode, with the exception -that the directory IV (stored in `gocryptfs.diriv`) is not random. -It is deterministically derived, using derivePathIV, from the encrypted -path to the directory. - -Because the encrypted path to the root directory is "" (the empty string), -this means that the directory IV in the root directory is always -`0xa8f7bac432ddc1cb3dc74e684d6ae48b = SHA256("\0DIRIV")`. - -derivePathIV: Derive IVs from Encrypted Paths ----------------------------------------------- - -derivePathIV concatenates the encrypted path with a null byte and a -salt string (one of "DIRIV", "FILEID", "BLOCK0IV"). This is -is hashed with SHA256 and truncated to 128 bits. - -![](img/reverse-derivePathIV.svg) diff --git a/docs/reverse_mode_crypto.md b/docs/reverse_mode_crypto.md new file mode 100644 index 0000000..b92cf40 --- /dev/null +++ b/docs/reverse_mode_crypto.md @@ -0,0 +1,59 @@ +Reverse Mode +============ + +In **reverse mode**, gocryptfs provides an encrypted view of a +plain-text directory. The primary use-case are encrypted backups. + +To make reverse mode useful, it uses deterministic encryption using +AES-SIV instead of AES-GCM. + +The differences with respect to the "normal" (forward) mode as detailed +on the [Security](security) page are listed below. + +File Contents +------------- + +File contents are encrypted using AES-SIV-512 (RFC5297). The 512-bit +AES-SIV key is derived from the 256-bit master key by hashing it with +SHA512. + +All values that are random in forward mode (File ID, Block IV) +are instead deterministically derived from the encrypted path, +essentially using a salted hash (detailed in the section "derivePathIV"). +As all derived values are explicitely stored in the ciphertext file, +decryption does not depend on knowledge of the derivation. + +The encryption process is shown in the diagram below. + +![](img/reverse-file-content-encryption.svg) + +Notes: + +1. The IV is passed to AES-SIV as described in section 3 of RFC5297 +2. The block number N is contained in the IV as well as in the AAD. + Either one or the other would suffice, but this construction simplifies + the decryption process by keeping it identical to forward mode. + The "duplication" is considered to not have + any security impact because S2V (RFC5297 section 2.4) hashes IV and + AAD independently before XORing them together. + +File Names +---------- + +File name encryption is identical to forward mode, with the exception +that the directory IV (stored in `gocryptfs.diriv`) is not random. +It is deterministically derived, using derivePathIV, from the encrypted +path to the directory. + +Because the encrypted path to the root directory is "" (the empty string), +this means that the directory IV in the root directory is always +`0xa8f7bac432ddc1cb3dc74e684d6ae48b = SHA256("\0DIRIV")`. + +derivePathIV: Derive IVs from Encrypted Paths +---------------------------------------------- + +derivePathIV concatenates the encrypted path with a null byte and a +salt string (one of "DIRIV", "FILEID", "BLOCK0IV"). This is +is hashed with SHA256 and truncated to 128 bits. + +![](img/reverse-derivePathIV.svg) diff --git a/docs/security.md b/docs/security.md deleted file mode 100644 index 894f894..0000000 --- a/docs/security.md +++ /dev/null @@ -1,76 +0,0 @@ -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`. - -When mounting a filesystem, the user is prompted for the password and -the master key is decrypted: - -![](img/master-key.svg) - -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. - -![](img/file-content-encryption.svg) - -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 [github.com/rfjakob/eme](https://github.com/rfjakob/eme) for details) with the directory IV -as initialization vector. EME fixes the prefix leak that occours with CBC -encryption. - -![](img/file-name-encryption.svg) - -The Base64 encoding limits the usable filename length to 176 characters. -Filenames that are longer than that (longer than 255 characters in Base64- -encoded form) use long file name handling (since gocryptfs v0.9). - -Long File Name Handling ------------------------ - -If the Base64-encoded encrypted name is longer than 255 characters, -it cannot be used as the file name on disk, as Linux filesystems -do not allow names longer than that. - -Instead, the encrypted name is hashed, and the file content is stored in -`gocryptfs.longname.[hash]`. The long file name is stored in a support -file, `gocryptfs.longname.[hash].name`. - -![](img/longnames.svg) - -This method for storing long file names has zero performance impact -for filenames that are <= 176 characters, incurs no extra disk accesses -for opening a file with a long name, and just one extra file read for each -long-name file on readdir(1). - -Because the hash is only taken from the encrypted file name, there is no -security penalty for using long names. diff --git a/mkdocs.yml b/mkdocs.yml index 0dc86f8..36818d6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,8 +5,8 @@ pages: - Home: index.md - Quickstart: quickstart.md - Compile from Source: compile.md -- Security: security.md -- Reverse Mode: reverse_mode.md +- Cryptography: forward_mode_crypto.md +- Reverse Mode Cryptography: reverse_mode_crypto.md - Comparison with Other Projects: comparison.md - Signed Releases: releases.md - Source Code Mirrors: mirrors.md -- cgit v1.2.3