eCryptfs: A stacked cryptographic filesystem for Linux

eCryptfs is free software. Please see the file COPYING for details.
For documentation, please see the files in the doc/ subdirectory.  For
building and installation instructions please see the INSTALL file.

Maintainer: Phillip Hellewell
Lead developer: Michael A. Halcrow <mhalcrow@us.ibm.com>
Developers: Michael C. Thompson
            Kent Yoder
            Trevor Highland
            Tyler Hicks
            Theresa Nelson
Current Release Version: 9
Web Site: http://ecryptfs.sf.net

As you should do with any filesystem, make sure to maintain a backup
copy of any data you write into eCryptfs.  In addition, you should
reliably store your secret keys in a secure location.  eCryptfs uses
industry-standard cryptographic ciphers, key generation, and
passphrase protection mechanisms; without your salt/passphrase or
private key, nobody will be able to retrieve your data.

eCryptfs requires the userspace tools downloadable from the
SourceForge site:

<http://sourceforge.net/projects/ecryptfs>

Requirements include:
 - Kernel version 2.6.19 or above
  - Build crypto API support with at least one symmetric key cipher
  - Build key retention support
  - If you have an older kernel, try the latest eCryptfs full package
    release to build a stand-alone kernel module
 - Userspace tools obtainable from the site listed above; requirements
   for the userspace tools are:
  - David Howells' userspace keyring headers and libraries (version
    1.0 or higher)
   - Finding its way into some distro's
   - Obtainable from <http://people.redhat.com/~dhowells/keyutils> 
  - libgcrypt
    - Part of most distro's; install the development package
    - If you need to build from source, you probably will want these:
     - <ftp://ftp.gnupg.org/gcrypt/libgpg-error>
     - <ftp://ftp.gnupg.org/gcrypt/libgcrypt>


KERNEL BUILD OPTIONS

Code maturity level options  --->
  [*] Prompt for development and/or incomplete code/drivers

Security options  --->
  <M> Enable access key retention support

Cryptographic options  --->
  <M>   MD5 digest algorithm
  <M>   AES cipher algorithms

File systems  --->
  Miscellaneous filesystems  --->
    <M> eCrypt filesystem layer support (EXPERIMENTAL)


NOTES

eCryptfs is still in a developmental stage. When you upgrade the
eCryptfs kernel module, it is possible that the eCryptfs file format
has been updated. For this reason you should copy your files to an
unencrypted location and then copy the files back into the new
eCryptfs mount point to migrate the files.


BUILD AND INSTALL INSTRUCTIONS

1) Consult the INSTALL file. In the majority of cases, this step
   should involve the standard procedure for Linux packages:
     % ./configure --prefix=/usr && make && make install

   If you are running a version of eCryptfs that ships as part of
   kernel version 2.6.18-rc6-mm2 or earlier, you need to pass the
   --enable-old-auth-tok option to the ./configure script.

2) Make sure that you have sysfs mounted and that a valid entry for
   the sysfs mount point is in your /etc/mtab file.


INTERACTIVE MOUNTING

Create a new directory into which eCryptfs will write its encrypted
files (i.e., /root/crypt).  Then, create the mount point directory
(i.e., /mnt/crypt).  Here is an example of how you might mount
eCryptfs:

mount -t ecryptfs /root/crypt /mnt/crypt

Note that you can also perform a layover mount (essentially,
converting an existing path into an eCryptfs mount point) to reduce
the likelihood of contention between eCryptfs and other applications
for access to the lower files; this is generally the recommended way
to mount eCryptfs:

mount -t ecryptfs /secret /secret

Navigate the menus to select your preferred mount options.


NON-INTERACTIVE MOUNTING

eCryptfs supports mounting through command-line options. You can do so
by passing groups of name=value attribute pairs as a -o option to the
mount helper.  Each key type has a set of name=value pairs associated
with it.  For instance, the ``passphrase'' key type can accept a
``passwd=XXX'' name=value pair and a ``salt=XXX'' name=value pair.
Attributes that apply to a particular key type immediately follow the
key type specifier ``key=XXX'' and are separated by colon's.
Attributes that do not apply to any specific key type (general
attributes) are separated by comma's.  The option string will take the
form:

 name1=value1,key=alias:name2=value2:name3=value3,name4=value4,name5=value5

name1=value1, name4=value4, and name5=value5 are all generic global
attributes that can apply to any key type.  name2=value2 and
name3=value3 are specific to the key type.

A BNF grammar for the option set follows:

<NULL> ::=
<letter> ::= (a | b | c | ... | z)
<letter-string> ::= <letter> (<letter-string> | <NULL>)
<character> ::= <any printable ASCII character that is not , or :>
<character-elem> ::= (<character> | <NULL>)
<character-string> ::= <character-elem> (<character-string> | <NULL>)
<name> ::= <letter-string>
<value> ::= <character-string>
<attr> ::= <name> "=" <value>
<comma-attr-list> ::= <attr> ("," <comma-attr-list> | <NULL>)
<colon-attr-list> ::= <attr> (":" <colon-attr-list> | <NULL>)
<key-attr-list> ::= "key=" <letter-string> (<colon-attr-list> | <NULL>)
<attr-list> ::= (<comma-attr-list> | <key-attr-list>)
<options-set> ::= <attr-list> (<attr-list> | <NULL>)

Values read from a file should be specified with name value pairs. For
example, a passphrase may be specified in a file by adding the following
line to the file:

passwd=<passphrase>

Currently supported aliases and attributes include:

 key alias passphrase:
     passwd=<passphrase>
     passfile=/path/to/file
     passfd=<file descriptor>
     passstdin (default)
     salt=<salt value>

 key alias openssl:
     keyfile=/path/to/key
     passwd=<passphrase>
     passfile=/path/to/file
     passfd=<file descriptor>
     passstdin (default)

Currently supported general attributes include:

 cipher=<cipher>
        Currently supported ciphers include:
         aes
         blowfish
         des3_ede
         cast5
         cast6
         twofish

 ecryptfs_key_bytes=<key bytes>
	With the exception of AES-192, eCryptfs requires that the
	keysize be a multiple of the block size.

 passthrough
	Allows for non-eCryptfs files to be read and written from within an
	eCryptfs mount. This option is disabled by default.

 verbosity=<value>
	0 eCryptfs will not prompt the user for unspecified options
	1 (default) eCryptfs will request unspecified options to be completed


If you wish to have the same passphrase used in previous passphrase
mounts and store it in a file (*not* recommended unless you can
provide sufficient protection of the file itself), you can take the
following steps:

(Previous mount; specify passphrase on command line)
mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passwd=my_password

(Next mount; have passphrase read from a passfile)
echo "passwd=my_password" > ~/my_ecryptfs_password
mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passfile=~/my_ecryptfs_password

Saving your unencrypted passphrase to a file on the same disk that
contains your encrypted files defeats the purpose of using a
cryptographic filesystem in the first place.  You should instead store
the file that contains your passphrase on a physically secure medium,
such as a USB flash drive that you keep locked in a drawer, if you
choose to store it to a file at all.

In general, it is probably best to just type in your passphrase via
stdin every time you need to perform a mount.  Future versions of
eCryptfs will allow hardware token devices, such as a TPM chip, to
protect your secret keys.


TESTING A NEW MOUNT POINT

Try writing a new file:

echo "Hello, World" > /secret/hello.txt

The operation will complete.  When you unmount eCryptfs, you will
Notice that there is a new file in /secret that is at least 12288
bytes in size (depending on your host page size).  This is the
encrypted underlying file for what you just wrote.  To test reading,
from start to finish, you need to clear the user session keyring:

keyctl clear @u

Then umount /secret and mount again per the instructions given above.

cat /secret/hello.txt


NOTES

eCryptfs shipping in kernel version 2.6.19 does not support public
key.  To determine what your current kernel supports, load the
ecryptfs module and view the contents of fs/ecryptfs/version_str under
your sysfs mount point.

eCryptfs should only be mounted on (1) empty directories or (2)
directories containing files only created by eCryptfs. If you mount a
directory that has pre-existing files not created by eCryptfs, then
behavior is undefined. Do not run eCryptfs in higher verbosity levels
unless you are doing so for the sole purpose of development, since
secret values will be written out to the system log in that case.


BUGS

Please send bug reports to the lead developer, an eCryptfs mailing
list hosted from SourceForge, or to the SourceForge bug tracker for
the eCryptfs project. For kernel bugs, please follow the procedure
detailed in the kernel documentation (Documentation/oops-tracing.txt)
to help us figure out what is happening.


Mike Halcrow
mhalcrow@us.ibm.com
