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
---
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 ++++
8 files changed, 1575 insertions(+)
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
(limited to 'docs')
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.
+
+
+
+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`.
+
+
+
+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.
--
cgit v1.2.3