From 0ebc0b7412d811b0865080573555100649a068fc Mon Sep 17 00:00:00 2001 From: Jakob Unterwurzacher Date: Sun, 20 Dec 2015 18:17:06 +0100 Subject: Add content, customize theme --- README.md | 3 + docs/img/file-content-encryption.svg | 516 +++++++++++++++++++++++++++++++++++ docs/img/file-name-encryption.svg | 400 +++++++++++++++++++++++++++ docs/img/folders-side-by-side.png | Bin 0 -> 143506 bytes docs/img/master-key.svg | 434 +++++++++++++++++++++++++++++ docs/index.md | 32 +++ docs/manpage.md | 101 +++++++ docs/quickstart.md | 41 +++ docs/security.md | 51 ++++ mkdocs.yml | 7 + xreadthedocs/base.html | 24 +- xreadthedocs/css/theme_extra.css | 55 ++++ xreadthedocs/footer.html | 5 +- xreadthedocs/toc.html | 2 + xreadthedocs/versions.html | 10 +- 15 files changed, 1658 insertions(+), 23 deletions(-) create mode 100644 README.md create mode 100644 docs/img/file-content-encryption.svg create mode 100644 docs/img/file-name-encryption.svg create mode 100644 docs/img/folders-side-by-side.png create mode 100644 docs/img/master-key.svg create mode 100644 docs/index.md create mode 100644 docs/manpage.md create mode 100644 docs/quickstart.md create mode 100644 docs/security.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md new file mode 100644 index 0000000..5646cf4 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +This repostitory contains the gocryptfs website + +https://nuetzlich.net/gocryptfs diff --git a/docs/img/file-content-encryption.svg b/docs/img/file-content-encryption.svg new file mode 100644 index 0000000..38a6f6b --- /dev/null +++ b/docs/img/file-content-encryption.svg @@ -0,0 +1,516 @@ + + + + diff --git a/docs/img/file-name-encryption.svg b/docs/img/file-name-encryption.svg new file mode 100644 index 0000000..45222e2 --- /dev/null +++ b/docs/img/file-name-encryption.svg @@ -0,0 +1,400 @@ + + + + diff --git a/docs/img/folders-side-by-side.png b/docs/img/folders-side-by-side.png new file mode 100644 index 0000000..92119f8 Binary files /dev/null and b/docs/img/folders-side-by-side.png differ diff --git a/docs/img/master-key.svg b/docs/img/master-key.svg new file mode 100644 index 0000000..bfc404a --- /dev/null +++ b/docs/img/master-key.svg @@ -0,0 +1,434 @@ + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..755f510 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,32 @@ +gocryptfs - An encrypted filesystem written in Go +================================================= + +gocryptfs uses file-based encryption that is implemented as a mountable +FUSE filesystem. +Each file in gocryptfs is stored one corresponding encrypted files on the hard disk. The +screenshot below shows a mounted gocryptfs filesystem (left) and the +encrypted files (right). + +The encrypted files can be stored in any folder on your hard disk, a USB +stick or even inside the Dropbox folder. One advantage of file-based +encryption as opposed to disk encryption is that encrypted files can +be synchronised efficiently using standard tools like Dropbox or rsync. +Also, the size of the encrypted filesystem is dynamic and only limited +by the available disk space. + +![](img/folders-side-by-side.png) + +This project was inspired by EncFS and strives to fix its security +issues while providing good performance. +See the [Security](security) page for details on gocryptfs's cryptographic +design. + +gocryptfs is a young project. While bugs in any software can cause issues, +bugs in encryption software can cause catastrophic data loss. Keep a backup +of your gocryptfs filesystem *and* store a copy of your master key (printed +on mount) in a safe place. + +Only Linux is supported at the moment. Help is wanted for a Mac OS X port. +Please contact me by filing an issue on the +[github project](https://github.com/rfjakob/gocryptfs). + diff --git a/docs/manpage.md b/docs/manpage.md new file mode 100644 index 0000000..2e440b2 --- /dev/null +++ b/docs/manpage.md @@ -0,0 +1,101 @@ +% 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 + +**-diriv** +: Use per-directory file name IV (default true) + +**-emenames** +: Use EME filename encryption (default true). This option implies diriv. + +**-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. Using something like "cat /mypassword.txt" allows +to mount the gocryptfs filesytem without user interaction. + +**-f** +: Stay in the foreground instead of forking away. + +**-fusedebug** +: Enable fuse library debug output + +**-gcmiv128** +: Use an 128-bit IV for GCM encryption instead of Go's default of +96 bits (default true). This pushes back the birthday bound for IV +collisions far enough to make it irrelevant. + +**-init** +: Initialize encrypted directory + +**-masterkey string** +: Mount with explicit master key specified on the command line. This +option can be used to mount a gocryptfs filesystem without a config file. +Note that the command line, and with it the master key, is visible to +anybody on the machine who can execute "ps -auxwww". + +**-notifypid int** +: Send USR1 to the specified process after successful mount. This is +used internally for daemonization. + +**-openssl bool** +: Use OpenSSL instead of built-in Go crypto (default true). Using +built-in crypto is 4x slower. + +**-passwd** +: Change password + +**-plaintextnames** +: Do not encrypt file names + +**-q** +: Quiet - silence informational messages + +**-scryptn int** +: scrypt cost parameter logN. Setting this to a lower value speeds up +mounting but makes the password susceptible to brute-force attacks (default 16) + +**-version** +: Print version and exit + +**-zerokey** +: Use all-zero dummy master key. This options is only intended for +automated testing as it does not provide any security. + diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..a5dd19f --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,41 @@ +gocryptfs Quickstart +==================== + +You need to have the Go runtime and the OpenSSL headers installed to +compile gocryptfs. + +On Fedora, + + $ sudo dnf install golang openssl-devel + +On Debian and Ubuntu, + + $ sudo apt-get install golang libssl-dev + +Also, GOPATH must be set. Usually it is simply set to the home directory: + + $ export GOPATH=$HOME + +Download +------- + + $ go get -d github.com/rfjakob/gocryptfs + +Compile +------- + + $ ~/src/github.com/rfjakob/gocryptfs/build.bash + $ mkdir -p ~/bin && cp ~/src/github.com/rfjakob/gocryptfs/gocryptfs ~/bin + +Create and Mount Filesystem +--------------------------- + + $ mkdir cipher plain + $ ~/bin/gocryptfs -init cipher + [...] + $ ~/bin/gocryptfs cipher plain + [...] + $ echo test > plain/test.txt + $ ls cipher + gocryptfs.conf gocryptfs.diriv ZSuIZVzYDy5-TbhWKY-ciA== + 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`. + +![](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 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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..e44072a --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,7 @@ +site_name: gocryptfs +theme: readthedocs +theme_dir: xreadthedocs +pages: +- Home: index.md +- Quickstart: quickstart.md +- Security: security.md diff --git a/xreadthedocs/base.html b/xreadthedocs/base.html index 042b00a..82e9d49 100644 --- a/xreadthedocs/base.html +++ b/xreadthedocs/base.html @@ -12,7 +12,6 @@ {% else %}{% endif %} {# CSS #} - @@ -38,17 +37,6 @@ {%- endfor %} - {% if google_analytics %} - - {% endif %} @@ -58,8 +46,9 @@ {# SIDE NAV, TOGGLES ON MOBILE #}

- {{ site_name }} - {% include "searchbox.html" %} + + gocryptfs +

@@ -77,13 +68,14 @@ {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #} {# PAGE CONTENT #}

- {% include "breadcrumbs.html" %}

{% block content %} diff --git a/xreadthedocs/css/theme_extra.css b/xreadthedocs/css/theme_extra.css index ccb384e..046cf33 100644 --- a/xreadthedocs/css/theme_extra.css +++ b/xreadthedocs/css/theme_extra.css @@ -124,3 +124,58 @@ code.cs, code.c { .wy-menu-vertical li ul.subnav ul.subnav{ padding-left: 1em; } + + +.wy-side-nav-search { + background-color: #343131 !important; +} + +.wy-nav-top { + background-color: #343131 !important; +} + +.wy-side-nav-search a { + margin-bottom: 0; +} + +a.site-title { + font-size: 200%; +} +/* Base16 Eighties Colorscheme by Chris Kempson (http://chriskempson.com) */ +/* CSS from https://github.com/htdvisser/hugo-base16-theme */ +.base00 { color: #2d2d2d; } +.base01 { color: #393939; } +.base02 { color: #515151; } +.base03 { color: #747369; } +.base04 { color: #a09f93; } +.base05 { color: #d3d0c8; } +.base06 { color: #e8e6df; } +.base07 { color: #f2f0ec; } +.base08 { color: #f2777a; } +.base09 { color: #f99157; } +.base0a { color: #ffcc66; } +.base0b { color: #99cc99; } +.base0c { color: #66cccc; } +.base0d { color: #6699cc; } +.base0e { color: #cc99cc; } +.base0f { color: #d27b53; } + + +div.builtwith a { + color: #aaa; +} + +.rst-versions .rst-current-version { + text-align: center; + padding-top: 0; +} + +.rst-versions .rst-current-version a { + margin-right: 10px; +} +.fa-github:before, .icon-github:before { + font-size: 30px; + position: relative; + bottom: -6px; + margin-right: 8px; +} diff --git a/xreadthedocs/footer.html b/xreadthedocs/footer.html index 9f707cd..45f1987 100644 --- a/xreadthedocs/footer.html +++ b/xreadthedocs/footer.html @@ -18,6 +18,7 @@

{% endif %}

- - Built with MkDocs using a theme provided by Read the Docs. +

+ Built with MkDocs using a theme provided by Read the Docs. +

diff --git a/xreadthedocs/toc.html b/xreadthedocs/toc.html index 6cd2fc9..4accc1b 100644 --- a/xreadthedocs/toc.html +++ b/xreadthedocs/toc.html @@ -10,6 +10,7 @@

{{ nav_item.title }} {% if nav_item == current_page %} + {% endif %}

{% endif %} diff --git a/xreadthedocs/versions.html b/xreadthedocs/versions.html index 4e23b49..6a34ee8 100644 --- a/xreadthedocs/versions.html +++ b/xreadthedocs/versions.html @@ -1,15 +1,15 @@

- {% if repo_name == 'GitHub' %} - GitHub - {% elif repo_name == 'Bitbucket' %} - BitBucket - {% endif %} + gocryptfs + gocryptfs-website + +

-- cgit v1.2.3