libgocryptfs/README.md

162 lines
5.9 KiB
Markdown
Raw Normal View History

2015-12-20 15:42:52 +01:00
![gocryptfs](Documentation/logo.svg.png) [![Build Status](https://travis-ci.org/rfjakob/gocryptfs.svg?branch=master)](https://travis-ci.org/rfjakob/gocryptfs) ![Release Status](https://img.shields.io/badge/status-beta-yellow.svg?style=flat)
2015-10-11 23:57:51 +02:00
==============
2015-11-01 12:14:59 +01:00
An encrypted overlay filesystem written in Go.
2015-09-06 12:12:14 +02:00
2015-10-06 00:31:53 +02:00
gocryptfs is built on top the excellent
[go-fuse](https://github.com/hanwen/go-fuse) FUSE library and its
LoopbackFileSystem API.
2015-09-06 12:12:14 +02:00
2015-12-08 16:41:45 +01:00
This project was inspired by EncFS and strives to fix its security
issues while providing good performance.
2015-11-01 12:14:59 +01:00
For details on the security of gocryptfs see the
2015-12-08 16:41:45 +01:00
[SECURITY.md](Documentation/SECURITY.md) design document.
2015-10-06 23:08:04 +02:00
Current Status
--------------
Beta. You are advised to keep a backup of your data outside of gocryptfs, in
addition to storing the *master key* in a safe place (the master key is printed
when mounting).
Only Linux is supported at the moment. Help wanted for a Mac OS X port.
Testing
-------
gocryptfs comes with is own test suite that is constantly expanded as features are
added. Run it using `./test.bash`. It takes about 30 seconds and requires FUSE
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
2015-12-01 18:19:24 +01:00
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.
The one exception is generic/035, see [go-fuse issue 55](https://github.com/hanwen/go-fuse/issues/55)
for details. While this is a POSIX violation, I do not see any real-world impact.
2015-10-06 23:08:04 +02:00
Install
-------
2015-10-11 19:45:03 +02:00
$ go get github.com/rfjakob/gocryptfs
2015-10-07 23:30:45 +02:00
Use
---
2015-11-11 09:19:53 +01:00
Quickstart:
2015-10-07 23:30:45 +02:00
$ mkdir cipher plain
2015-10-11 19:45:03 +02:00
$ $GOPATH/bin/gocryptfs --init cipher
2015-10-07 23:30:45 +02:00
[...]
2015-10-11 19:45:03 +02:00
$ $GOPATH/bin/gocryptfs cipher plain
2015-10-07 23:30:45 +02:00
[...]
$ echo test > plain/test.txt
$ ls -l cipher
total 8
-rw-rw-r--. 1 user user 33 7. Okt 23:23 0ao8Hyyf1A-A88sfNvkUxA==
-rw-rw-r--. 1 user user 233 7. Okt 23:23 gocryptfs.conf
2015-10-11 19:45:03 +02:00
$ fusermount -u plain
2015-10-06 23:08:04 +02:00
2015-12-01 18:19:24 +01:00
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).
2015-11-11 09:19:53 +01:00
2015-11-01 12:14:59 +01:00
Storage Overhead
----------------
* Empty files take 0 bytes on disk
* 18 byte file header for non-empty files (2 bytes version, 16 bytes random file id)
* 28 bytes of storage overhead per 4kB block (12 byte nonce, 16 bytes auth tag)
2015-10-06 23:08:04 +02:00
Performance
-----------
gocryptfs uses openssl through
[spacemonkeygo/openssl](https://github.com/spacemonkeygo/openssl)
for a 3x speedup compared to Go's builtin AES-GCM implementation (see
[go-vs-openssl.md](openssl_benchmark/go-vs-openssl.md) for details).
2015-09-06 12:16:34 +02:00
Run `./benchmark.bash` to run the benchmarks.
2015-09-06 12:12:14 +02:00
The output should look like this:
./benchmark.bash
gocryptfs v0.3.1-30-gd69e0df-dirty; on-disk format 2
PASS
BenchmarkStreamWrite-2 100 12246070 ns/op 85.63 MB/s
BenchmarkStreamRead-2 200 9125990 ns/op 114.90 MB/s
BenchmarkCreate0B-2 10000 101284 ns/op
BenchmarkCreate1B-2 10000 178356 ns/op 0.01 MB/s
BenchmarkCreate100B-2 5000 361014 ns/op 0.28 MB/s
BenchmarkCreate4kB-2 5000 375035 ns/op 10.92 MB/s
BenchmarkCreate10kB-2 3000 491071 ns/op 20.85 MB/s
ok github.com/rfjakob/gocryptfs/integration_tests 17.216s
2015-10-06 00:31:53 +02:00
Changelog
---------
2015-12-20 15:42:52 +01:00
v0.7
* **Extend GCM IV size to 128 bit from Go's default of 96 bit**
* This pushes back the birthday bound to make IV collisions virtually
impossible
* This is a forwards-compatible change. gocryptfs v0.7 can mount filesystems
created by earlier versions but not the other way round.
* New command-line option:
* `-gcmiv128`: Use 128-bit GCM IVs (default true)
2015-12-08 16:41:45 +01:00
v0.6
* **Wide-block filename encryption using EME + DirIV**
* EME (ECB-Mix-ECB) provides even better security than CBC as it fixes
the prefix leak. The used Go EME implementation is
https://github.com/rfjakob/eme which is, as far as I know, the first
implementation of EME in Go.
2015-12-08 16:44:39 +01:00
* This is a forwards-compatible change. gocryptfs v0.6 can mount filesystems
2015-12-20 15:42:52 +01:00
created by earlier versions but not the other way round.
2015-12-08 16:41:45 +01:00
* New command-line option:
* `-emenames`: Enable EME filename encryption (default true)
v0.5
2015-11-29 22:36:25 +01:00
* **Stronger filename encryption: DirIV**
* Each directory gets a random 128 bit file name IV on creation,
stored in `gocryptfs.diriv`
* This makes it impossible to identify identically-named files across
directories
* A single-entry IV cache brings the performance cost of DirIV close to
zero for common operations (see performance.txt)
* This is a forwards-compatible change. gocryptfs v0.5 can mount filesystems
2015-12-20 15:42:52 +01:00
created by earlier versions but not the other way round.
2015-11-29 22:36:25 +01:00
* New command-line option:
* `-diriv`: Use the new per-directory IV file name encryption (default true)
* `-scryptn`: allows to set the scrypt cost parameter N. This option
can be used for faster mounting at the cost of lower brute-force
resistance. It was mainly added to speed up the automated tests.
v0.4
* New command-line options:
* `-plaintextnames`: disables filename encryption, added on user request
* `-extpass`: calls an external program for prompting for the password
* `-config`: allows to specify a custom gocryptfs.conf path
* Add `FeatureFlags` gocryptfs.conf paramter
2015-11-03 22:34:03 +01:00
* This is a config format change, hence the on-disk format is incremented
* Used for ext4-style filesystem feature flags. This should help avoid future
format changes. The first user is `-plaintextnames`.
2015-11-03 00:08:31 +01:00
* On-disk format 2
2015-11-01 14:07:42 +01:00
v0.3
2015-11-29 22:36:25 +01:00
* **Add a random 128 bit file header to authenticate file->block ownership**
* This is an on-disk-format change
2015-11-01 14:07:42 +01:00
* On-disk format 1
v0.2
* Replace bash daemonization wrapper with native Go implementation
* Better user feedback on mount failures
v0.1
* First release
2015-11-01 14:07:42 +01:00
* On-disk format 0
See https://github.com/rfjakob/gocryptfs/tags for the release dates and associated
git tags.