From accf8144ca627ffc0a282259d28b8fe6e583eed6 Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Tue, 1 Dec 2015 18:19:24 +0100 Subject: Move docs to Documentation folder --- Documentation/MANPAGE-render.bash | 7 ++ Documentation/MANPAGE.md | 79 +++++++++++++ Documentation/SECURITY.md | 92 ++++++++++++++++ Documentation/XFSTESTS.md | 225 ++++++++++++++++++++++++++++++++++++++ Documentation/performance.txt | 11 ++ MANPAGE-render.bash | 7 -- MANPAGE.md | 79 ------------- README.md | 6 +- SECURITY.md | 92 ---------------- XFSTESTS.md | 225 -------------------------------------- performance.txt | 11 -- 11 files changed, 417 insertions(+), 417 deletions(-) create mode 100755 Documentation/MANPAGE-render.bash create mode 100644 Documentation/MANPAGE.md create mode 100644 Documentation/SECURITY.md create mode 100644 Documentation/XFSTESTS.md create mode 100644 Documentation/performance.txt delete mode 100755 MANPAGE-render.bash delete mode 100644 MANPAGE.md delete mode 100644 SECURITY.md delete mode 100644 XFSTESTS.md delete mode 100644 performance.txt diff --git a/Documentation/MANPAGE-render.bash b/Documentation/MANPAGE-render.bash new file mode 100755 index 0000000..9ea268d --- /dev/null +++ b/Documentation/MANPAGE-render.bash @@ -0,0 +1,7 @@ +#!/bin/bash + +set -eux + +# Render MANPAGE.md to a proper man(1) manpage + +pandoc MANPAGE.md -s -t man -o gocryptfs.1 && man ./gocryptfs.1 diff --git a/Documentation/MANPAGE.md b/Documentation/MANPAGE.md new file mode 100644 index 0000000..517cc82 --- /dev/null +++ b/Documentation/MANPAGE.md @@ -0,0 +1,79 @@ +% GOCRYPTFS(1) +% github.com/rfjakob +% Nov 2015 + +NAME +==== + +gocryptfs - mount an encrypted directory + +SYNOPSIS +======== + +Initialize encrypted filesystem +------------------------------- + +gocryptfs -init [OPTIONS] CIPHERDIR + +Mount +----- + +gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT + +Change password +--------------- + +gocryptfs -passwd [OPTIONS] CIPHERDIR + +DESCRIPTION +=========== + +Options: + +**-config string** +: Use specified config file instead of CIPHERDIR/gocryptfs.conf + +**-cpuprofile string** +: Write cpu profile to specified file + +**-debug** +: Enable debug output + +**-extpass string** +: Use an external program (like ssh-askpass) for the password prompt. +The program should return the password on stdout, a trailing newline is +stripped by gocryptfs. + +**-f** +: Stay in the foreground + +**-fusedebug** +: Enable fuse library debug output + +**-init** +: Initialize encrypted directory + +**-masterkey string** +: Mount with explicit master key + +**-notifypid int** +: Send USR1 to the specified process after successful mount - used internally for daemonization + +**-openssl bool** +: Use OpenSSL instead of built-in Go crypto (default true) + +**-passwd** +: Change password + +**-plaintextnames** +: Do not encrypt file names + +**-q** +: Quiet - silence informational messages + +**-version** +: Print version and exit + +**-zerokey** +: Use all-zero dummy master key + diff --git a/Documentation/SECURITY.md b/Documentation/SECURITY.md new file mode 100644 index 0000000..4db4c24 --- /dev/null +++ b/Documentation/SECURITY.md @@ -0,0 +1,92 @@ +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 with a per-directory IV +* Each directory get a random 128 bit IV on creation + * Files with the same name in different directories are encrypted to + different filenames and can not be identified +* 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 + +### 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. + +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. +* Every file has a header that contains a 16-byte random *file id* +* Each block uses the file id and its block number as GCM *authentication data* + * This means the position of the blocks is protected as well. The blocks + can not be reordered or copied between different files without + causing an decryption error. +* 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. diff --git a/Documentation/XFSTESTS.md b/Documentation/XFSTESTS.md new file mode 100644 index 0000000..3223143 --- /dev/null +++ b/Documentation/XFSTESTS.md @@ -0,0 +1,225 @@ +These are the results of running [fuse-xfstests](https://github.com/rfjakob/fuse-xfstests) +against gocryptfs: + +``` +~/src/fuse-xfstests$ ./check-gocryptfs generic/??? +FSTYP -- fuse.gocryptfs +PLATFORM -- Linux/x86_64 brikett 4.1.4-200.fc22.x86_64 +MKFS_OPTIONS -- /tmp/check-gocryptfs/scratchdev +MOUNT_OPTIONS -- -o context=system_u:object_r:nfs_t:s0 /tmp/check-gocryptfs/scratchdev /tmp/check-gocryptfs/scratchdir + +generic/001 4s ... 5s +generic/002 0s ... 0s +generic/003 [not run] atime related mount options have no effect on loopback file systems +generic/004 [not run] xfs_io flink failed (old kernel/wrong fs?) +generic/005 0s ... 0s +generic/006 1s ... 2s +generic/007 3s ... 2s +generic/008 [not run] xfs_io fzero failed (old kernel/wrong fs?) +generic/009 [not run] xfs_io fzero failed (old kernel/wrong fs?) +generic/010 1s ... 2s +generic/011 2s ... 2s +generic/012 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/013 2s ... 0s +generic/014 37s ... 40s +generic/015 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/016 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/017 [not run] xfs_io fiemap failed (old kernel/wrong fs?) +generic/018 [not run] defragmentation not supported for fstype "fuse.gocryptfs" +generic/019 [not run] Not running as root, skipping test +generic/020 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/021 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/022 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/023 1s ... 1s +generic/024 [not run] fs doesn't support RENAME_NOREPLACE +generic/025 [not run] fs doesn't support RENAME_EXCHANGE +generic/026 [not run] Not running as root, skipping test +generic/027 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/028 5s ... 5s +generic/029 8s ... 0s +generic/030 9s ... 1s +generic/031 [not run] xfs_io fcollapse failed (old kernel/wrong fs?) +generic/032 [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/033 [not run] xfs_io fzero failed (old kernel/wrong fs?) +generic/034 [not run] Not running as root, skipping test +generic/035 - output mismatch (see /home/jakob/src/fuse-xfstests/results//generic/035.out.bad) + --- tests/generic/035.out 2015-09-22 23:50:31.967720246 +0200 + +++ /home/jakob/src/fuse-xfstests/results//generic/035.out.bad 2015-10-07 22:16:46.625139272 +0200 + @@ -1,3 +1,4 @@ + QA output created by 035 + overwriting regular file: + overwriting directory: + +t_rename_overwrite: fstat(3): No such file or directory + ... + (Run 'diff -u tests/generic/035.out /home/jakob/src/fuse-xfstests/results//generic/035.out.bad' to see the entire diff) +generic/036 [not run] src/aio-dio-regress/aio-dio-fcntl-race not built +generic/037 [not run] Not running as root, skipping test +generic/038 [not run] Not running as root, skipping test +generic/039 [not run] Not running as root, skipping test +generic/040 [not run] Not running as root, skipping test +generic/041 [not run] Not running as root, skipping test +generic/042 [not run] fuse.gocryptfs does not support shutdown +generic/043 [not run] fuse.gocryptfs does not support shutdown +generic/044 [not run] fuse.gocryptfs does not support shutdown +generic/045 [not run] fuse.gocryptfs does not support shutdown +generic/046 [not run] fuse.gocryptfs does not support shutdown +generic/047 [not run] fuse.gocryptfs does not support shutdown +generic/048 [not run] fuse.gocryptfs does not support shutdown +generic/049 [not run] fuse.gocryptfs does not support shutdown +generic/050 [not run] fuse.gocryptfs does not support shutdown +generic/051 [not run] fuse.gocryptfs does not support shutdown +generic/052 [not run] fuse.gocryptfs does not support shutdown +generic/053 3s ... [not run] ACLs not supported by this filesystem type: fuse.gocryptfs +generic/054 [not run] fuse.gocryptfs does not support shutdown +generic/055 [not run] fuse.gocryptfs does not support shutdown +generic/056 [not run] Not running as root, skipping test +generic/057 [not run] Not running as root, skipping test +generic/058 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/059 [not run] Not running as root, skipping test +generic/060 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/061 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/062 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/063 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/064 [not run] xfs_io fiemap failed (old kernel/wrong fs?) +generic/065 [not run] Not running as root, skipping test +generic/066 [not run] Not running as root, skipping test +generic/067 5s ... [not run] fuse overlay filesystems do not support loopback devices +generic/068 [not run] fuse.gocryptfs does not support freezing +generic/069 257s ... 298s +generic/070 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/071 [not run] Not running as root, skipping test +generic/072 [not run] xfs_io fcollapse failed (old kernel/wrong fs?) +generic/073 [not run] Not running as root, skipping test +generic/074 677s ... 777s +generic/075 4s ... 5s +generic/076 [not run] require /tmp/check-gocryptfs/scratchdev to be valid block disk +generic/077 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/078 [not run] Not running as root, skipping test +generic/079 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/080 2s ... 2s +generic/081 [not run] require /tmp/check-gocryptfs/scratchdev to be valid block disk +generic/082 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/083 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/084 8s ... 7s +generic/085 [not run] require /tmp/check-gocryptfs/scratchdev to be valid block disk +generic/086 0s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/087 [not run] Not running as root, skipping test +generic/088 [not run] Not running as root, skipping test +generic/089 30s ... 37s +generic/090 [not run] Not running as root, skipping test +generic/091 [not run] O_DIRECT is not supported +generic/092 [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/093 [not run] not suitable for this OS: Linux +generic/094 [not run] xfs_io fiemap failed (old kernel/wrong fs?) +generic/095 [not run] fio utility required, skipped this test +generic/096 [not run] xfs_io fzero failed (old kernel/wrong fs?) +generic/097 [not run] not suitable for this OS: Linux +generic/098 [not run] Not running as root, skipping test +generic/099 [not run] not suitable for this OS: Linux +generic/100 12s ... 15s +generic/101 [not run] Not running as root, skipping test +generic/102 [not run] Not running as root, skipping test +generic/103 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/104 [not run] Not running as root, skipping test +generic/105 [not run] Not running as root, skipping test +generic/106 [not run] Not running as root, skipping test +generic/112 [not run] fsx not built with AIO for this platform +generic/113 [not run] aio-stress not built for this platform +generic/117 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/120 [not run] atime related mount options have no effect on loopback file systems +generic/123 [not run] fsgqa user not defined. +generic/124 9s ... 7s +generic/125 [not run] fsgqa user not defined. +generic/126 [not run] Not running as root, skipping test +generic/127 314s ... 359s +generic/128 [not run] fsgqa user not defined. +generic/129 49s ... 59s +generic/130 [not run] O_DIRECT is not supported +generic/131 1s ... 1s +generic/132 25s ... 23s +generic/133 [not run] O_DIRECT is not supported +generic/135 [not run] O_DIRECT is not supported +generic/141 2s ... 0s +generic/169 6s ... 1s +generic/184 [not run] Not running as root, skipping test +generic/192 [not run] atime related mount options have no effect on loopback file systems +generic/193 [not run] fsgqa user not defined. +generic/198 [not run] src/aio-dio-regress/aiodio_sparse2 not built +generic/204 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/207 [not run] src/aio-dio-regress/aio-dio-extend-stat not built +generic/208 [not run] src/aio-dio-regress/aio-dio-invalidate-failure not built +generic/209 [not run] src/aio-dio-regress/aio-dio-invalidate-readahead not built +generic/210 [not run] src/aio-dio-regress/aio-dio-subblock-eof-read not built +generic/211 [not run] src/aio-dio-regress/aio-free-ring-with-bogus-nr-pages not built +generic/212 [not run] src/aio-dio-regress/aio-io-setup-with-nonwritable-context-pointer not built +generic/213 1s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/214 0s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/215 3s ... 3s +generic/219 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/221 1s ... 1s +generic/223 [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/224 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/225 [not run] xfs_io fiemap failed (old kernel/wrong fs?) +generic/226 [not run] O_DIRECT is not supported +generic/228 [not run] FSIZE is not supported on FUSE +generic/230 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/231 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/232 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/233 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/234 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/235 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/236 2s ... 1s +generic/237 [not run] Not running as root, skipping test +generic/239 [not run] src/aio-dio-regress/aio-dio-hole-filling-race not built +generic/240 [not run] src/aio-dio-regress/aiodio_sparse2 not built +generic/241 72s ... 72s +generic/245 0s ... 0s +generic/246 1s ... 1s +generic/247 25s ... 32s +generic/248 1s ... 0s +generic/249 4s ... 5s +generic/251 [not run] FITRIM not supported on /tmp/check-gocryptfs/scratchdir +generic/255 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/256 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/257 1s ... 1s +generic/258 2s ... 0s +generic/260 [not run] FITRIM not supported on /tmp/check-gocryptfs/scratchdir +generic/263 [not run] O_DIRECT is not supported +generic/269 [not run] Not running as root, skipping test +generic/270 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/273 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/274 [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/275 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/277 [not run] attrs not supported by this filesystem type: fuse.gocryptfs +generic/280 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs +generic/285 0s ... 0s +generic/286 59s ... 39s +generic/288 [not run] FITRIM not supported on /tmp/check-gocryptfs/scratchdir +generic/294 [not run] Not running as root, skipping test +generic/299 [not run] Not running as root, skipping test +generic/300 [not run] Not running as root, skipping test +generic/306 [not run] Not running as root, skipping test +generic/307 7s ... 1s +generic/308 0s ... 0s +generic/309 2s ... 1s +generic/310 64s ... 65s +generic/311 [not run] Not running as root, skipping test +generic/312 [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/313 2s ... 2s +generic/314 [not run] ACLs not supported by this filesystem type: fuse.gocryptfs +generic/315 1s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) +generic/316 [not run] xfs_io fpunch failed (old kernel/wrong fs?) +generic/317 [not run] Not running as root, skipping test +generic/318 [not run] Not running as root, skipping test +generic/319 [not run] ACLs not supported by this filesystem type: fuse.gocryptfs +generic/320 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized +generic/321 [not run] Not running as root, skipping test +generic/322 [not run] Not running as root, skipping test +generic/323 [not run] src/aio-dio-regress/aio-last-ref-held-by-io not built +generic/324 [not run] Not running as root, skipping test +generic/325 [not run] Not running as root, skipping test +Ran: generic/001 generic/002 generic/005 generic/006 generic/007 generic/010 generic/011 generic/013 generic/014 generic/023 generic/028 generic/029 generic/030 generic/035 generic/069 generic/074 generic/075 generic/080 generic/084 generic/089 generic/100 generic/124 generic/127 generic/129 generic/131 generic/132 generic/141 generic/169 generic/215 generic/221 generic/236 generic/241 generic/245 generic/246 generic/247 generic/248 generic/249 generic/257 generic/258 generic/285 generic/286 generic/307 generic/308 generic/309 generic/310 generic/313 +Not run: generic/003 generic/004 generic/008 generic/009 generic/012 generic/015 generic/016 generic/017 generic/018 generic/019 generic/020 generic/021 generic/022 generic/024 generic/025 generic/026 generic/027 generic/031 generic/032 generic/033 generic/034 generic/036 generic/037 generic/038 generic/039 generic/040 generic/041 generic/042 generic/043 generic/044 generic/045 generic/046 generic/047 generic/048 generic/049 generic/050 generic/051 generic/052 generic/053 generic/054 generic/055 generic/056 generic/057 generic/058 generic/059 generic/060 generic/061 generic/062 generic/063 generic/064 generic/065 generic/066 generic/067 generic/068 generic/070 generic/071 generic/072 generic/073 generic/076 generic/077 generic/078 generic/079 generic/081 generic/082 generic/083 generic/085 generic/086 generic/087 generic/088 generic/090 generic/091 generic/092 generic/093 generic/094 generic/095 generic/096 generic/097 generic/098 generic/099 generic/101 generic/102 generic/103 generic/104 generic/105 generic/106 generic/112 generic/113 generic/117 generic/120 generic/123 generic/125 generic/126 generic/128 generic/130 generic/133 generic/135 generic/184 generic/192 generic/193 generic/198 generic/204 generic/207 generic/208 generic/209 generic/210 generic/211 generic/212 generic/213 generic/214 generic/219 generic/223 generic/224 generic/225 generic/226 generic/228 generic/230 generic/231 generic/232 generic/233 generic/234 generic/235 generic/237 generic/239 generic/240 generic/251 generic/255 generic/256 generic/260 generic/263 generic/269 generic/270 generic/273 generic/274 generic/275 generic/277 generic/280 generic/288 generic/294 generic/299 generic/300 generic/306 generic/311 generic/312 generic/314 generic/315 generic/316 generic/317 generic/318 generic/319 generic/320 generic/321 generic/322 generic/323 generic/324 generic/325 +Failures: generic/035 +Failed 1 of 46 tests +``` diff --git a/Documentation/performance.txt b/Documentation/performance.txt new file mode 100644 index 0000000..2cd53a7 --- /dev/null +++ b/Documentation/performance.txt @@ -0,0 +1,11 @@ +All test performed on tmpfs, /tmp/a mounted on /tmp/b. + +UNTAR: tar xfz ../linux-3.0.tar.gz +LS: ls -lR > /dev/null +RM: rm -rf linux-3.0 + +VERSION UNTAR LS RM +v0.4 48 1.5 5 +v0.5-rc1 56 7 19 +v0.5-rc1-1 54 4.1 9 +v0.5-rc1-2 45 1.7 3.4 diff --git a/MANPAGE-render.bash b/MANPAGE-render.bash deleted file mode 100755 index 9ea268d..0000000 --- a/MANPAGE-render.bash +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/bash - -set -eux - -# Render MANPAGE.md to a proper man(1) manpage - -pandoc MANPAGE.md -s -t man -o gocryptfs.1 && man ./gocryptfs.1 diff --git a/MANPAGE.md b/MANPAGE.md deleted file mode 100644 index 517cc82..0000000 --- a/MANPAGE.md +++ /dev/null @@ -1,79 +0,0 @@ -% GOCRYPTFS(1) -% github.com/rfjakob -% Nov 2015 - -NAME -==== - -gocryptfs - mount an encrypted directory - -SYNOPSIS -======== - -Initialize encrypted filesystem -------------------------------- - -gocryptfs -init [OPTIONS] CIPHERDIR - -Mount ------ - -gocryptfs [OPTIONS] CIPHERDIR MOUNTPOINT - -Change password ---------------- - -gocryptfs -passwd [OPTIONS] CIPHERDIR - -DESCRIPTION -=========== - -Options: - -**-config string** -: Use specified config file instead of CIPHERDIR/gocryptfs.conf - -**-cpuprofile string** -: Write cpu profile to specified file - -**-debug** -: Enable debug output - -**-extpass string** -: Use an external program (like ssh-askpass) for the password prompt. -The program should return the password on stdout, a trailing newline is -stripped by gocryptfs. - -**-f** -: Stay in the foreground - -**-fusedebug** -: Enable fuse library debug output - -**-init** -: Initialize encrypted directory - -**-masterkey string** -: Mount with explicit master key - -**-notifypid int** -: Send USR1 to the specified process after successful mount - used internally for daemonization - -**-openssl bool** -: Use OpenSSL instead of built-in Go crypto (default true) - -**-passwd** -: Change password - -**-plaintextnames** -: Do not encrypt file names - -**-q** -: Quiet - silence informational messages - -**-version** -: Print version and exit - -**-zerokey** -: Use all-zero dummy master key - diff --git a/README.md b/README.md index fa83629..3191e6f 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ 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](SECURITY.md) document. +[SECURITY.md](Documentation/SECURITY.md) document. Current Status -------------- @@ -32,7 +32,7 @@ as it mounts several test filesystems. In addition, I have ported `xfstests` to FUSE, the result is the [fuse-xfstests](https://github.com/rfjakob/fuse-xfstests) project. gocryptfs -passes the "generic" tests with one exception, results: [XFSTESTS.md](XFSTESTS.md) +passes the "generic" tests with one exception, results: [XFSTESTS.md](Documentation/XFSTESTS.md) A lot of work has gone into this. The testing has found bugs in gocryptfs as well as in go-fuse. @@ -62,7 +62,7 @@ Quickstart: -rw-rw-r--. 1 user user 233 7. Okt 23:23 gocryptfs.conf $ fusermount -u plain -See [MANPAGE.md](MANPAGE.md) for a description of available options. If you already +See [MANPAGE.md](Documentation/MANPAGE.md) for a description of available options. If you already have gocryptfs installed, run `./MANPAGE-render.bash` to bring up the rendered manpage in the pager (requires pandoc). diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 4db4c24..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,92 +0,0 @@ -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 with a per-directory IV -* Each directory get a random 128 bit IV on creation - * Files with the same name in different directories are encrypted to - different filenames and can not be identified -* 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 - -### 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. - -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. -* Every file has a header that contains a 16-byte random *file id* -* Each block uses the file id and its block number as GCM *authentication data* - * This means the position of the blocks is protected as well. The blocks - can not be reordered or copied between different files without - causing an decryption error. -* 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. diff --git a/XFSTESTS.md b/XFSTESTS.md deleted file mode 100644 index 3223143..0000000 --- a/XFSTESTS.md +++ /dev/null @@ -1,225 +0,0 @@ -These are the results of running [fuse-xfstests](https://github.com/rfjakob/fuse-xfstests) -against gocryptfs: - -``` -~/src/fuse-xfstests$ ./check-gocryptfs generic/??? -FSTYP -- fuse.gocryptfs -PLATFORM -- Linux/x86_64 brikett 4.1.4-200.fc22.x86_64 -MKFS_OPTIONS -- /tmp/check-gocryptfs/scratchdev -MOUNT_OPTIONS -- -o context=system_u:object_r:nfs_t:s0 /tmp/check-gocryptfs/scratchdev /tmp/check-gocryptfs/scratchdir - -generic/001 4s ... 5s -generic/002 0s ... 0s -generic/003 [not run] atime related mount options have no effect on loopback file systems -generic/004 [not run] xfs_io flink failed (old kernel/wrong fs?) -generic/005 0s ... 0s -generic/006 1s ... 2s -generic/007 3s ... 2s -generic/008 [not run] xfs_io fzero failed (old kernel/wrong fs?) -generic/009 [not run] xfs_io fzero failed (old kernel/wrong fs?) -generic/010 1s ... 2s -generic/011 2s ... 2s -generic/012 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/013 2s ... 0s -generic/014 37s ... 40s -generic/015 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/016 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/017 [not run] xfs_io fiemap failed (old kernel/wrong fs?) -generic/018 [not run] defragmentation not supported for fstype "fuse.gocryptfs" -generic/019 [not run] Not running as root, skipping test -generic/020 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/021 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/022 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/023 1s ... 1s -generic/024 [not run] fs doesn't support RENAME_NOREPLACE -generic/025 [not run] fs doesn't support RENAME_EXCHANGE -generic/026 [not run] Not running as root, skipping test -generic/027 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/028 5s ... 5s -generic/029 8s ... 0s -generic/030 9s ... 1s -generic/031 [not run] xfs_io fcollapse failed (old kernel/wrong fs?) -generic/032 [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/033 [not run] xfs_io fzero failed (old kernel/wrong fs?) -generic/034 [not run] Not running as root, skipping test -generic/035 - output mismatch (see /home/jakob/src/fuse-xfstests/results//generic/035.out.bad) - --- tests/generic/035.out 2015-09-22 23:50:31.967720246 +0200 - +++ /home/jakob/src/fuse-xfstests/results//generic/035.out.bad 2015-10-07 22:16:46.625139272 +0200 - @@ -1,3 +1,4 @@ - QA output created by 035 - overwriting regular file: - overwriting directory: - +t_rename_overwrite: fstat(3): No such file or directory - ... - (Run 'diff -u tests/generic/035.out /home/jakob/src/fuse-xfstests/results//generic/035.out.bad' to see the entire diff) -generic/036 [not run] src/aio-dio-regress/aio-dio-fcntl-race not built -generic/037 [not run] Not running as root, skipping test -generic/038 [not run] Not running as root, skipping test -generic/039 [not run] Not running as root, skipping test -generic/040 [not run] Not running as root, skipping test -generic/041 [not run] Not running as root, skipping test -generic/042 [not run] fuse.gocryptfs does not support shutdown -generic/043 [not run] fuse.gocryptfs does not support shutdown -generic/044 [not run] fuse.gocryptfs does not support shutdown -generic/045 [not run] fuse.gocryptfs does not support shutdown -generic/046 [not run] fuse.gocryptfs does not support shutdown -generic/047 [not run] fuse.gocryptfs does not support shutdown -generic/048 [not run] fuse.gocryptfs does not support shutdown -generic/049 [not run] fuse.gocryptfs does not support shutdown -generic/050 [not run] fuse.gocryptfs does not support shutdown -generic/051 [not run] fuse.gocryptfs does not support shutdown -generic/052 [not run] fuse.gocryptfs does not support shutdown -generic/053 3s ... [not run] ACLs not supported by this filesystem type: fuse.gocryptfs -generic/054 [not run] fuse.gocryptfs does not support shutdown -generic/055 [not run] fuse.gocryptfs does not support shutdown -generic/056 [not run] Not running as root, skipping test -generic/057 [not run] Not running as root, skipping test -generic/058 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/059 [not run] Not running as root, skipping test -generic/060 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/061 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/062 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/063 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/064 [not run] xfs_io fiemap failed (old kernel/wrong fs?) -generic/065 [not run] Not running as root, skipping test -generic/066 [not run] Not running as root, skipping test -generic/067 5s ... [not run] fuse overlay filesystems do not support loopback devices -generic/068 [not run] fuse.gocryptfs does not support freezing -generic/069 257s ... 298s -generic/070 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/071 [not run] Not running as root, skipping test -generic/072 [not run] xfs_io fcollapse failed (old kernel/wrong fs?) -generic/073 [not run] Not running as root, skipping test -generic/074 677s ... 777s -generic/075 4s ... 5s -generic/076 [not run] require /tmp/check-gocryptfs/scratchdev to be valid block disk -generic/077 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/078 [not run] Not running as root, skipping test -generic/079 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/080 2s ... 2s -generic/081 [not run] require /tmp/check-gocryptfs/scratchdev to be valid block disk -generic/082 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/083 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/084 8s ... 7s -generic/085 [not run] require /tmp/check-gocryptfs/scratchdev to be valid block disk -generic/086 0s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/087 [not run] Not running as root, skipping test -generic/088 [not run] Not running as root, skipping test -generic/089 30s ... 37s -generic/090 [not run] Not running as root, skipping test -generic/091 [not run] O_DIRECT is not supported -generic/092 [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/093 [not run] not suitable for this OS: Linux -generic/094 [not run] xfs_io fiemap failed (old kernel/wrong fs?) -generic/095 [not run] fio utility required, skipped this test -generic/096 [not run] xfs_io fzero failed (old kernel/wrong fs?) -generic/097 [not run] not suitable for this OS: Linux -generic/098 [not run] Not running as root, skipping test -generic/099 [not run] not suitable for this OS: Linux -generic/100 12s ... 15s -generic/101 [not run] Not running as root, skipping test -generic/102 [not run] Not running as root, skipping test -generic/103 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/104 [not run] Not running as root, skipping test -generic/105 [not run] Not running as root, skipping test -generic/106 [not run] Not running as root, skipping test -generic/112 [not run] fsx not built with AIO for this platform -generic/113 [not run] aio-stress not built for this platform -generic/117 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/120 [not run] atime related mount options have no effect on loopback file systems -generic/123 [not run] fsgqa user not defined. -generic/124 9s ... 7s -generic/125 [not run] fsgqa user not defined. -generic/126 [not run] Not running as root, skipping test -generic/127 314s ... 359s -generic/128 [not run] fsgqa user not defined. -generic/129 49s ... 59s -generic/130 [not run] O_DIRECT is not supported -generic/131 1s ... 1s -generic/132 25s ... 23s -generic/133 [not run] O_DIRECT is not supported -generic/135 [not run] O_DIRECT is not supported -generic/141 2s ... 0s -generic/169 6s ... 1s -generic/184 [not run] Not running as root, skipping test -generic/192 [not run] atime related mount options have no effect on loopback file systems -generic/193 [not run] fsgqa user not defined. -generic/198 [not run] src/aio-dio-regress/aiodio_sparse2 not built -generic/204 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/207 [not run] src/aio-dio-regress/aio-dio-extend-stat not built -generic/208 [not run] src/aio-dio-regress/aio-dio-invalidate-failure not built -generic/209 [not run] src/aio-dio-regress/aio-dio-invalidate-readahead not built -generic/210 [not run] src/aio-dio-regress/aio-dio-subblock-eof-read not built -generic/211 [not run] src/aio-dio-regress/aio-free-ring-with-bogus-nr-pages not built -generic/212 [not run] src/aio-dio-regress/aio-io-setup-with-nonwritable-context-pointer not built -generic/213 1s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/214 0s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/215 3s ... 3s -generic/219 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/221 1s ... 1s -generic/223 [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/224 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/225 [not run] xfs_io fiemap failed (old kernel/wrong fs?) -generic/226 [not run] O_DIRECT is not supported -generic/228 [not run] FSIZE is not supported on FUSE -generic/230 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/231 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/232 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/233 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/234 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/235 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/236 2s ... 1s -generic/237 [not run] Not running as root, skipping test -generic/239 [not run] src/aio-dio-regress/aio-dio-hole-filling-race not built -generic/240 [not run] src/aio-dio-regress/aiodio_sparse2 not built -generic/241 72s ... 72s -generic/245 0s ... 0s -generic/246 1s ... 1s -generic/247 25s ... 32s -generic/248 1s ... 0s -generic/249 4s ... 5s -generic/251 [not run] FITRIM not supported on /tmp/check-gocryptfs/scratchdir -generic/255 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/256 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/257 1s ... 1s -generic/258 2s ... 0s -generic/260 [not run] FITRIM not supported on /tmp/check-gocryptfs/scratchdir -generic/263 [not run] O_DIRECT is not supported -generic/269 [not run] Not running as root, skipping test -generic/270 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/273 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/274 [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/275 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/277 [not run] attrs not supported by this filesystem type: fuse.gocryptfs -generic/280 [not run] disk quotas not supported by this filesystem type: fuse.gocryptfs -generic/285 0s ... 0s -generic/286 59s ... 39s -generic/288 [not run] FITRIM not supported on /tmp/check-gocryptfs/scratchdir -generic/294 [not run] Not running as root, skipping test -generic/299 [not run] Not running as root, skipping test -generic/300 [not run] Not running as root, skipping test -generic/306 [not run] Not running as root, skipping test -generic/307 7s ... 1s -generic/308 0s ... 0s -generic/309 2s ... 1s -generic/310 64s ... 65s -generic/311 [not run] Not running as root, skipping test -generic/312 [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/313 2s ... 2s -generic/314 [not run] ACLs not supported by this filesystem type: fuse.gocryptfs -generic/315 1s ... [not run] xfs_io falloc failed (old kernel/wrong fs?) -generic/316 [not run] xfs_io fpunch failed (old kernel/wrong fs?) -generic/317 [not run] Not running as root, skipping test -generic/318 [not run] Not running as root, skipping test -generic/319 [not run] ACLs not supported by this filesystem type: fuse.gocryptfs -generic/320 [not run] Filesystem fuse.gocryptfs not supported in _scratch_mkfs_sized -generic/321 [not run] Not running as root, skipping test -generic/322 [not run] Not running as root, skipping test -generic/323 [not run] src/aio-dio-regress/aio-last-ref-held-by-io not built -generic/324 [not run] Not running as root, skipping test -generic/325 [not run] Not running as root, skipping test -Ran: generic/001 generic/002 generic/005 generic/006 generic/007 generic/010 generic/011 generic/013 generic/014 generic/023 generic/028 generic/029 generic/030 generic/035 generic/069 generic/074 generic/075 generic/080 generic/084 generic/089 generic/100 generic/124 generic/127 generic/129 generic/131 generic/132 generic/141 generic/169 generic/215 generic/221 generic/236 generic/241 generic/245 generic/246 generic/247 generic/248 generic/249 generic/257 generic/258 generic/285 generic/286 generic/307 generic/308 generic/309 generic/310 generic/313 -Not run: generic/003 generic/004 generic/008 generic/009 generic/012 generic/015 generic/016 generic/017 generic/018 generic/019 generic/020 generic/021 generic/022 generic/024 generic/025 generic/026 generic/027 generic/031 generic/032 generic/033 generic/034 generic/036 generic/037 generic/038 generic/039 generic/040 generic/041 generic/042 generic/043 generic/044 generic/045 generic/046 generic/047 generic/048 generic/049 generic/050 generic/051 generic/052 generic/053 generic/054 generic/055 generic/056 generic/057 generic/058 generic/059 generic/060 generic/061 generic/062 generic/063 generic/064 generic/065 generic/066 generic/067 generic/068 generic/070 generic/071 generic/072 generic/073 generic/076 generic/077 generic/078 generic/079 generic/081 generic/082 generic/083 generic/085 generic/086 generic/087 generic/088 generic/090 generic/091 generic/092 generic/093 generic/094 generic/095 generic/096 generic/097 generic/098 generic/099 generic/101 generic/102 generic/103 generic/104 generic/105 generic/106 generic/112 generic/113 generic/117 generic/120 generic/123 generic/125 generic/126 generic/128 generic/130 generic/133 generic/135 generic/184 generic/192 generic/193 generic/198 generic/204 generic/207 generic/208 generic/209 generic/210 generic/211 generic/212 generic/213 generic/214 generic/219 generic/223 generic/224 generic/225 generic/226 generic/228 generic/230 generic/231 generic/232 generic/233 generic/234 generic/235 generic/237 generic/239 generic/240 generic/251 generic/255 generic/256 generic/260 generic/263 generic/269 generic/270 generic/273 generic/274 generic/275 generic/277 generic/280 generic/288 generic/294 generic/299 generic/300 generic/306 generic/311 generic/312 generic/314 generic/315 generic/316 generic/317 generic/318 generic/319 generic/320 generic/321 generic/322 generic/323 generic/324 generic/325 -Failures: generic/035 -Failed 1 of 46 tests -``` diff --git a/performance.txt b/performance.txt deleted file mode 100644 index 2cd53a7..0000000 --- a/performance.txt +++ /dev/null @@ -1,11 +0,0 @@ -All test performed on tmpfs, /tmp/a mounted on /tmp/b. - -UNTAR: tar xfz ../linux-3.0.tar.gz -LS: ls -lR > /dev/null -RM: rm -rf linux-3.0 - -VERSION UNTAR LS RM -v0.4 48 1.5 5 -v0.5-rc1 56 7 19 -v0.5-rc1-1 54 4.1 9 -v0.5-rc1-2 45 1.7 3.4 -- cgit v1.2.3