1
eCryptfs: A stacked cryptographic filesystem for Linux
3
eCryptfs is free software. Please see the file COPYING for details.
4
For documentation, please see the files in the doc/ subdirectory. For
5
building and installation instructions please see the INSTALL file.
7
Maintainer: Phillip Hellewell
8
Lead developer: Michael A. Halcrow <mhalcrow@us.ibm.com>
9
Developers: Michael C. Thompson
14
Current Release Version: 13
15
Web Site: http://ecryptfs.sf.net
17
As you should do with any filesystem, make sure to maintain a backup
18
copy of any data you write into eCryptfs. In addition, you should
19
reliably store your secret keys in a secure location. eCryptfs uses
20
industry-standard cryptographic ciphers, key generation, and
21
passphrase protection mechanisms; without your salt/passphrase or
22
private key, nobody will be able to retrieve your data.
24
eCryptfs requires the userspace tools downloadable from the
27
<http://sourceforge.net/projects/ecryptfs>
30
- Kernel version 2.6.19 or above
31
- Build crypto API support with at least one symmetric key cipher
32
- Build key retention support
33
- If you have an older kernel, try the latest eCryptfs full package
34
release to build a stand-alone kernel module
35
- Userspace tools obtainable from the site listed above; requirements
36
for the userspace tools are:
37
- David Howells' userspace keyring headers and libraries (version
39
- Finding its way into some distro's
40
- Obtainable from <http://people.redhat.com/~dhowells/keyutils>
42
- Part of most distro's; install the development package
43
- If you need to build from source, you probably will want these:
44
- <ftp://ftp.gnupg.org/gcrypt/libgpg-error>
45
- <ftp://ftp.gnupg.org/gcrypt/libgcrypt>
50
Code maturity level options --->
51
[*] Prompt for development and/or incomplete code/drivers
54
<M> Enable access key retention support
56
Cryptographic options --->
57
<M> MD5 digest algorithm
58
<M> AES cipher algorithms
61
Miscellaneous filesystems --->
62
<M> eCrypt filesystem layer support (EXPERIMENTAL)
67
eCryptfs is still in a developmental stage. When you upgrade the
68
eCryptfs kernel module, it is possible that the eCryptfs file format
69
has been updated. For this reason you should copy your files to an
70
unencrypted location and then copy the files back into the new
71
eCryptfs mount point to migrate the files.
74
BUILD AND INSTALL INSTRUCTIONS
76
1) Consult the INSTALL file. In the majority of cases, this step
77
should involve the standard procedure for Linux packages:
78
% ./configure --prefix=/usr && make && make install
80
If you are running a version of eCryptfs that ships as part of
81
kernel version 2.6.18-rc6-mm2 or earlier, you need to pass the
82
--enable-old-auth-tok option to the ./configure script.
84
2) Make sure that you have sysfs mounted and that a valid entry for
85
the sysfs mount point is in your /etc/mtab file.
90
Create a new directory into which eCryptfs will write its encrypted
91
files (i.e., /root/crypt). Then, create the mount point directory
92
(i.e., /mnt/crypt). Here is an example of how you might mount
95
mount -t ecryptfs /root/crypt /mnt/crypt
97
Note that you can also perform a layover mount (essentially,
98
converting an existing path into an eCryptfs mount point) to reduce
99
the likelihood of contention between eCryptfs and other applications
100
for access to the lower files; this is generally the recommended way
103
mount -t ecryptfs /secret /secret
105
Navigate the menus to select your preferred mount options.
108
NON-INTERACTIVE MOUNTING
110
eCryptfs supports mounting through command-line options. You can do so
111
by passing groups of name=value attribute pairs as a -o option to the
112
mount helper. Each key type has a set of name=value pairs associated
113
with it. For instance, the ``passphrase'' key type can accept a
114
``passwd=XXX'' name=value pair and a ``salt=XXX'' name=value pair.
115
Attributes that apply to a particular key type immediately follow the
116
key type specifier ``key=XXX'' and are separated by colon's.
117
Attributes that do not apply to any specific key type (general
118
attributes) are separated by comma's. The option string will take the
121
name1=value1,key=alias:name2=value2:name3=value3,name4=value4,name5=value5
123
name1=value1, name4=value4, and name5=value5 are all generic global
124
attributes that can apply to any key type. name2=value2 and
125
name3=value3 are specific to the key type.
127
A BNF grammar for the option set follows:
130
<letter> ::= (a | b | c | ... | z)
131
<letter-string> ::= <letter> (<letter-string> | <NULL>)
132
<character> ::= <any printable ASCII character that is not , or :>
133
<character-elem> ::= (<character> | <NULL>)
134
<character-string> ::= <character-elem> (<character-string> | <NULL>)
135
<name> ::= <letter-string>
136
<value> ::= <character-string>
137
<attr> ::= <name> "=" <value>
138
<comma-attr-list> ::= <attr> ("," <comma-attr-list> | <NULL>)
139
<colon-attr-list> ::= <attr> (":" <colon-attr-list> | <NULL>)
140
<key-attr-list> ::= "key=" <letter-string> (<colon-attr-list> | <NULL>)
141
<attr-list> ::= (<comma-attr-list> | <key-attr-list>)
142
<options-set> ::= <attr-list> (<attr-list> | <NULL>)
144
Values read from a file should be specified with name value pairs. For
145
example, a passphrase may be specified in a file by adding the following
150
Currently supported aliases and attributes include:
152
key alias passphrase:
154
passfile=/path/to/file
155
passfd=<file descriptor>
162
passfile=/path/to/file
163
passfd=<file descriptor>
166
Currently supported general attributes include:
169
Currently supported ciphers include:
177
ecryptfs_key_bytes=<key bytes>
178
With the exception of AES-192, eCryptfs requires that the
179
keysize be a multiple of the block size.
182
Allows for non-eCryptfs files to be read and written from within an
183
eCryptfs mount. This option is disabled by default.
186
0 eCryptfs will not prompt the user for unspecified options
187
1 (default) eCryptfs will request unspecified options to be completed
190
If you wish to have the same passphrase used in previous passphrase
191
mounts and store it in a file (*not* recommended unless you can
192
provide sufficient protection of the file itself), you can take the
195
(Previous mount; specify passphrase on command line)
196
mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passwd=my_password
198
(Next mount; have passphrase read from a passfile)
199
echo "passwd=my_password" > ~/my_ecryptfs_password
200
mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passfile=~/my_ecryptfs_password
202
Saving your unencrypted passphrase to a file on the same disk that
203
contains your encrypted files defeats the purpose of using a
204
cryptographic filesystem in the first place. You should instead store
205
the file that contains your passphrase on a physically secure medium,
206
such as a USB flash drive that you keep locked in a drawer, if you
207
choose to store it to a file at all.
209
In general, it is probably best to just type in your passphrase via
210
stdin every time you need to perform a mount. Future versions of
211
eCryptfs will allow hardware token devices, such as a TPM chip, to
212
protect your secret keys.
215
TESTING A NEW MOUNT POINT
217
Try writing a new file:
219
echo "Hello, World" > /secret/hello.txt
221
The operation will complete. When you unmount eCryptfs, you will
222
Notice that there is a new file in /secret that is at least 12288
223
bytes in size (depending on your host page size). This is the
224
encrypted underlying file for what you just wrote. To test reading,
225
from start to finish, you need to clear the user session keyring:
229
Then umount /secret and mount again per the instructions given above.
231
cat /secret/hello.txt
236
You can use the PAM module to automatically use a key based on your
237
login passphrase, which can then be used to perform an eCryptfs mount
240
Perform an eCryptfs mount as root, using your user login:
242
root# mount -t ecryptfs /secret /secret
244
Then, grab your raw mount parameters from
246
root# grep "ecryptfs" /etc/mtab
248
You should get something like this:
251
/secret /secret ecryptfs rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0
254
Add ``user'' to the mount options:
257
/secret /secret ecryptfs user,rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0
260
Append your edited line to your /etc/fstab file. Now it's time to test
265
Verify that eCryptfs is not mounted. Then, log in as the regular
266
user. Manually add your passphrase to the user session keyring via the
267
ecryptfs-manager utility. Then, perform the mount, while telling the
268
mount application to not call the mount helper:
270
user# mount -i /secret
272
Verify that eCryptfs mounted correctly. Then, unmount:
276
Clear your user session keyring:
278
user# keyctl clear @u
280
Add the mount command into your login script (e.g., ~/.bash_profile):
286
Finally, add this to the appropriate /etc/pam* file (e.g.,
290
auth required pam_ecryptfs.so
293
From another window, try logging in as the user. If all went well, the
294
eCryptfs PAM module will insert a key derived from your login
295
passphrase into the user session keyring. Then, the login script will
296
perform the mount, using the parameters in your /etc/fstab.
301
eCryptfs shipping in kernel version 2.6.19 does not support public
302
key. To determine what your current kernel supports, load the
303
ecryptfs module and view the contents of fs/ecryptfs/version_str under
304
your sysfs mount point.
306
eCryptfs should only be mounted on (1) empty directories or (2)
307
directories containing files only created by eCryptfs. If you mount a
308
directory that has pre-existing files not created by eCryptfs, then
309
behavior is undefined. Do not run eCryptfs in higher verbosity levels
310
unless you are doing so for the sole purpose of development, since
311
secret values will be written out to the system log in that case.
316
See <doc/ecryptfs-faq.html>. For the most up-to-date FAQ, see
317
<http://ecryptfs.sourceforge.net/ecryptfs-faq.html>.
322
Please send bug reports to the lead developer, an eCryptfs mailing
323
list hosted from SourceForge, or to the SourceForge bug tracker for
324
the eCryptfs project. For kernel bugs, please follow the procedure
325
detailed in the kernel documentation (Documentation/oops-tracing.txt)
326
to help us figure out what is happening.
added
removed
doc/sourceforge_webpage/README
