1.. SPDX-License-Identifier: GPL-2.0
2
3======================================================
4eCryptfs: A stacked cryptographic filesystem for Linux
5======================================================
6
7eCryptfs is free software. Please see the file COPYING for details.
8For documentation, please see the files in the doc/ subdirectory.  For
9building and installation instructions please see the INSTALL file.
10
11:Maintainer: Phillip Hellewell
12:Lead developer: Michael A. Halcrow <mhalcrow@us.ibm.com>
13:Developers: Michael C. Thompson
14             Kent Yoder
15:Web Site: http://ecryptfs.sf.net
16
17This software is currently undergoing development. Make sure to
18maintain a backup copy of any data you write into eCryptfs.
19
20eCryptfs requires the userspace tools downloadable from the
21SourceForge site:
22
23http://sourceforge.net/projects/ecryptfs/
24
25Userspace requirements include:
26
27- David Howells' userspace keyring headers and libraries (version
28  1.0 or higher), obtainable from
29  http://people.redhat.com/~dhowells/keyutils/
30- Libgcrypt
31
32
33.. note::
34
35   In the beta/experimental releases of eCryptfs, when you upgrade
36   eCryptfs, you should copy the files to an unencrypted location and
37   then copy the files back into the new eCryptfs mount to migrate the
38   files.
39
40
41Mount-wide Passphrase
42=====================
43
44Create a new directory into which eCryptfs will write its encrypted
45files (i.e., /root/crypt).  Then, create the mount point directory
46(i.e., /mnt/crypt).  Now it's time to mount eCryptfs::
47
48    mount -t ecryptfs /root/crypt /mnt/crypt
49
50You should be prompted for a passphrase and a salt (the salt may be
51blank).
52
53Try writing a new file::
54
55    echo "Hello, World" > /mnt/crypt/hello.txt
56
57The operation will complete.  Notice that there is a new file in
58/root/crypt that is at least 12288 bytes in size (depending on your
59host page size).  This is the encrypted underlying file for what you
60just wrote.  To test reading, from start to finish, you need to clear
61the user session keyring:
62
63keyctl clear @u
64
65Then umount /mnt/crypt and mount again per the instructions given
66above.
67
68::
69
70    cat /mnt/crypt/hello.txt
71
72
73Notes
74=====
75
76eCryptfs version 0.1 should only be mounted on (1) empty directories
77or (2) directories containing files only created by eCryptfs. If you
78mount a directory that has pre-existing files not created by eCryptfs,
79then behavior is undefined. Do not run eCryptfs in higher verbosity
80levels unless you are doing so for the sole purpose of debugging or
81development, since secret values will be written out to the system log
82in that case.
83
84
85Mike Halcrow
86mhalcrow@us.ibm.com
87