~mrooney/ecryptfs/nautilus-integration

2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
1
eCryptfs: A stacked cryptographic filesystem for Linux
2
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.
6
271 by Dustin Kirkland
update some sourceforge -> launchpad links
7
Lead developers:
8
	Tyler Hicks (kernel)
9
	Dustin Kirkland (userspace)
10
Contributors:
11
	Michael Halcrow
12
	Michael C. Thompson
13
	Kent Yoder
14
	Trevor Highland
15
	Theresa Nelson
16
Former maintainers:
17
	Phillip Hellewell
18
	Michael Halcrow
19
Web Site: http://launchpad.net/ecryptfs
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
20
21
As you should do with any filesystem, make sure to maintain a backup
22
copy of any data you write into eCryptfs.  In addition, you should
23
reliably store your secret keys in a secure location.  eCryptfs uses
24
industry-standard cryptographic ciphers, key generation, and
25
passphrase protection mechanisms; without your salt/passphrase or
26
private key, nobody will be able to retrieve your data.
27
28
eCryptfs requires the userspace tools downloadable from the
239 by Dustin Kirkland
update s/sourceforge/launchpad/g links
29
Launchpad site:
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
30
239 by Dustin Kirkland
update s/sourceforge/launchpad/g links
31
<http://launchpad.net/ecryptfs>
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
32
33
Requirements include:
34
 - Kernel version 2.6.19 or above
35
  - Build crypto API support with at least one symmetric key cipher
36
  - Build key retention support
37
  - If you have an older kernel, try the latest eCryptfs full package
38
    release to build a stand-alone kernel module
39
 - Userspace tools obtainable from the site listed above; requirements
40
   for the userspace tools are:
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
41
  - keyutils
42
   - David Howells' userspace keyring headers and libraries (version
43
     1.0 or higher)
44
   - Finding its way into some distros
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
45
   - Obtainable from <http://people.redhat.com/~dhowells/keyutils> 
46
  - libgcrypt
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
47
    - Part of most distros; install the development package
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
48
    - If you need to build from source, you probably will want these:
49
     - <ftp://ftp.gnupg.org/gcrypt/libgpg-error>
50
     - <ftp://ftp.gnupg.org/gcrypt/libgcrypt>
51
52
53
KERNEL BUILD OPTIONS
54
55
Code maturity level options  --->
56
  [*] Prompt for development and/or incomplete code/drivers
57
58
Security options  --->
59
  <M> Enable access key retention support
60
61
Cryptographic options  --->
162 by Mike halcrow
Update README to reflect namespaced key module parameters.
62
  <M>   CBC support
63
  <M>   ECB support
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
64
  <M>   MD5 digest algorithm
65
  <M>   AES cipher algorithms
66
67
File systems  --->
68
  Miscellaneous filesystems  --->
69
    <M> eCrypt filesystem layer support (EXPERIMENTAL)
70
71
72
NOTES
73
74
eCryptfs is still in a developmental stage. When you upgrade the
75
eCryptfs kernel module, it is possible that the eCryptfs file format
76
has been updated. For this reason you should copy your files to an
77
unencrypted location and then copy the files back into the new
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
78
eCryptfs mount point to migrate the files.  File format version 3
79
and beyond (in kernel version 2.6.24) is expected to remain readable,
80
however.
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
81
82
83
BUILD AND INSTALL INSTRUCTIONS
84
85
1) Consult the INSTALL file. In the majority of cases, this step
86
   should involve the standard procedure for Linux packages:
87
     % ./configure --prefix=/usr && make && make install
88
89
2) Make sure that you have sysfs mounted and that a valid entry for
90
   the sysfs mount point is in your /etc/mtab file.
91
92
93
INTERACTIVE MOUNTING
94
95
Create a new directory into which eCryptfs will write its encrypted
96
files (i.e., /root/crypt).  Then, create the mount point directory
97
(i.e., /mnt/crypt).  Here is an example of how you might mount
98
eCryptfs:
99
100
mount -t ecryptfs /root/crypt /mnt/crypt
101
102
Note that you can also perform a layover mount (essentially,
103
converting an existing path into an eCryptfs mount point) to reduce
104
the likelihood of contention between eCryptfs and other applications
105
for access to the lower files; this is generally the recommended way
106
to mount eCryptfs:
107
108
mount -t ecryptfs /secret /secret
109
110
Navigate the menus to select your preferred mount options.
111
112
113
NON-INTERACTIVE MOUNTING
114
115
eCryptfs supports mounting through command-line options. You can do so
116
by passing groups of name=value attribute pairs as a -o option to the
117
mount helper.  Each key type has a set of name=value pairs associated
118
with it.  For instance, the ``passphrase'' key type can accept a
119
``passwd=XXX'' name=value pair and a ``salt=XXX'' name=value pair.
120
Attributes that apply to a particular key type immediately follow the
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
121
key type specifier ``key=XXX'' and are separated by colons.
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
122
Attributes that do not apply to any specific key type (general
123
attributes) are separated by comma's.  The option string will take the
124
form:
125
126
 name1=value1,key=alias:name2=value2:name3=value3,name4=value4,name5=value5
127
128
name1=value1, name4=value4, and name5=value5 are all generic global
129
attributes that can apply to any key type.  name2=value2 and
130
name3=value3 are specific to the key type.
131
132
A BNF grammar for the option set follows:
133
134
<NULL> ::=
135
<letter> ::= (a | b | c | ... | z)
136
<letter-string> ::= <letter> (<letter-string> | <NULL>)
137
<character> ::= <any printable ASCII character that is not , or :>
138
<character-elem> ::= (<character> | <NULL>)
139
<character-string> ::= <character-elem> (<character-string> | <NULL>)
140
<name> ::= <letter-string>
141
<value> ::= <character-string>
142
<attr> ::= <name> "=" <value>
143
<comma-attr-list> ::= <attr> ("," <comma-attr-list> | <NULL>)
144
<colon-attr-list> ::= <attr> (":" <colon-attr-list> | <NULL>)
145
<key-attr-list> ::= "key=" <letter-string> (<colon-attr-list> | <NULL>)
146
<attr-list> ::= (<comma-attr-list> | <key-attr-list>)
147
<options-set> ::= <attr-list> (<attr-list> | <NULL>)
148
149
Values read from a file should be specified with name value pairs. For
150
example, a passphrase may be specified in a file by adding the following
151
line to the file:
152
153
passwd=<passphrase>
154
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
155
Currently supported aliases and attributes parsed by the mount helper include:
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
156
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
157
 key=passphrase:
162 by Mike halcrow
Update README to reflect namespaced key module parameters.
158
     passphrase_passwd=<passphrase>
159
     passphrase_passwd_file=/path/to/file
164 by Mike halcrow
Clean up code and parameter names in documentation and key module.
160
     passphrase_passwd_fd=<file descriptor>
162 by Mike halcrow
Update README to reflect namespaced key module parameters.
161
     passphrase_salt=<salt value>
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
162
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
163
 key=openssl:
162 by Mike halcrow
Update README to reflect namespaced key module parameters.
164
     openssl_keyfile=/path/to/key
165
     openssl_passwd=<passphrase>
166
     openssl_passwd_file=/path/to/file
167
     openssl_passwd_fd=<file descriptor>
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
168
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
169
The following general attributes are valid kernel mount options,
170
and may also be acted upon by the mount helper, mount.ecryptfs:
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
171
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
172
 ecryptfs_cipher=<cipher>
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
173
        Currently supported ciphers include:
174
         aes
175
         blowfish
176
         des3_ede
177
         cast5
178
         cast6
179
         twofish
180
181
 ecryptfs_key_bytes=<key bytes>
182
	With the exception of AES-192, eCryptfs requires that the
183
	keysize be a multiple of the block size.
184
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
185
 ecryptfs_sig=<hex signature>
186
	The signature for the FEKEK to use to encrypt the FEK for newly
187
	created files.  A key with description <sig> should be in the
188
	user's session keyring.  The mount helper, with its key modules,
189
	should make sure that the key gets placed there.
190
191
 ecryptfs_passthrough
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
192
	Allows for non-eCryptfs files to be read and written from within an
193
	eCryptfs mount. This option is disabled by default.
194
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
195
 ecryptfs_xattr_metadata
196
	When set, newly created files will have their cryptographic
197
	metadata stored in the extended attribute region of the file rather
106 by Mike halcrow
Update README for key module params.
198
	than the header (requires kernel support).
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
199
200
 ecryptfs_encrypted_view
201
	When set, this option causes eCryptfs to present applications a
202
	view of encrypted files as if the cryptographic metadata were
203
	stored in the file header, whether the metadata is actually stored
204
	in the header or in the extended attributes.
205
56 by mhalcrow@us.ibm.com
Add HMAC mount option to mount helper.
206
 ecryptfs_hmac
207
        When set, eCryptfs will include HMAC integrity enforcement to
106 by Mike halcrow
Update README for key module params.
208
        its files (requires kernel support).
56 by mhalcrow@us.ibm.com
Add HMAC mount option to mount helper.
209
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
210
 ecryptfs_debug=<value>
211
	A value greater than 0 enables kernel debug messages, see NOTES
212
	below.
213
214
The following general attributes are parsed only by the mount helper,
215
mount.ecryptfs:
216
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
217
 no_sig_cache
218
        Do not perform any key signature cache checks. By default,
219
        when mounting, the eCryptfs mount helper will look for the key
220
        signature in <$HOME/.ecryptfs/sig-cache.txt>. If the key
221
        signature is not found, then the user will get a warning and
222
        will be prompted on whether to continue and whether to add the
223
        new key signature to the sig-cache.txt file. This behavior can
224
        be suppressed with the no_sig_cache option.
225
226
If you wish to have the same passphrase used in previous passphrase
227
mounts and store it in a file (*not* recommended unless you can
228
provide sufficient protection of the file itself), you can take the
229
following steps:
230
231
(Previous mount; specify passphrase on command line)
162 by Mike halcrow
Update README to reflect namespaced key module parameters.
232
mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passphrase_passwd=my_passphrase
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
233
162 by Mike halcrow
Update README to reflect namespaced key module parameters.
234
(Next mount; have passphrase read from a file)
165 by Mike halcrow
Clean up manpages and README some more.
235
echo "passphrase_passwd=my_passphrase" > /mnt/secureusb/my_passphrase
236
mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passphrase_passwd_file=/mnt/secureusb/my_passphrase
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
237
238
Saving your unencrypted passphrase to a file on the same disk that
239
contains your encrypted files defeats the purpose of using a
240
cryptographic filesystem in the first place.  You should instead store
241
the file that contains your passphrase on a physically secure medium,
242
such as a USB flash drive that you keep locked in a drawer, if you
243
choose to store it to a file at all.
244
245
In general, it is probably best to just type in your passphrase via
246
stdin every time you need to perform a mount.  Future versions of
247
eCryptfs will allow hardware token devices, such as a TPM chip, to
248
protect your secret keys.
249
250
251
TESTING A NEW MOUNT POINT
252
253
Try writing a new file:
254
255
echo "Hello, World" > /secret/hello.txt
256
257
The operation will complete.  When you unmount eCryptfs, you will
258
Notice that there is a new file in /secret that is at least 12288
259
bytes in size (depending on your host page size).  This is the
260
encrypted underlying file for what you just wrote.  To test reading,
261
from start to finish, you need to clear the user session keyring:
262
263
keyctl clear @u
264
265
Then umount /secret and mount again per the instructions given above.
266
267
cat /secret/hello.txt
268
269
270
PAM MODULE
271
272
You can use the PAM module to automatically use a key based on your
273
login passphrase, which can then be used to perform an eCryptfs mount
274
non-interactively.
275
276
Perform an eCryptfs mount as root, using your user login:
277
278
root# mount -t ecryptfs /secret /secret
279
280
Then, grab your raw mount parameters from 
281
282
root# grep "ecryptfs" /etc/mtab
283
284
You should get something like this:
285
286
---
287
/secret /secret ecryptfs rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0
288
---
289
290
Add ``user'' and ``noauto'' to the mount options:
291
292
---
293
/secret /secret ecryptfs user,noauto,rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0
294
---
295
296
Append your edited line to your /etc/fstab file. Now it's time to test
297
the mount.
298
299
root# umount /secret
300
301
Verify that eCryptfs is not mounted. Then, log in as the regular
302
user. Manually add your passphrase to the user session keyring via the
303
ecryptfs-manager utility. Then, perform the mount, while telling the
304
mount application to not call the mount helper:
305
306
user# mount -i /secret
307
308
Verify that eCryptfs mounted correctly. Then, unmount:
309
310
user# umount /secret
311
312
Clear your user session keyring:
313
314
user# keyctl clear @u
315
316
Add the mount command into your login script (e.g., ~/.bash_profile):
317
318
---
319
mount -i /secret
320
---
321
322
Finally, add this to the appropriate /etc/pam* file (e.g.,
323
/etc/pam.d/login) after the call to pam_unix.so:
324
325
---
326
auth required pam_ecryptfs.so
327
---
328
329
You will need to insert this intelligently into your PAM stack so that
330
PAM actually calls pam_ecryptfs.so. Depending on your distribution,
331
this may involve, for instance, changing the context of pam_unix.so
332
from ``sufficient'' to ``required'' and moving pam_deny.so to another
333
location in the stack. Be mindful of the security implications of any
334
changes you make to your PAM stack.
335
336
From another window, try logging in as the user. If all went well, the
337
eCryptfs PAM module will insert a key derived from your login
338
passphrase into the user session keyring. Then, the login script will
339
perform the mount, using the parameters in your /etc/fstab.
340
341
The script src/utils/ecryptfs-setup-pam.sh attempts to automate
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
342
setting up PAM mounts on Red Hat-based distros. Use that for
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
343
inspiration in setting up your own eCryptfs PAM mount.
344
345
346
NOTES
347
348
eCryptfs shipping in kernel version 2.6.19 does not support public
349
key.  To determine what your current kernel supports, load the
350
ecryptfs module and view the contents of fs/ecryptfs/version_str under
351
your sysfs mount point.
352
28 by mhalcrow@us.ibm.com
Documentation updates by Eric Sandeen.
353
Do not run eCryptfs in higher verbosity levels unless you are doing so
354
for the sole purpose of development, since secret values will be written
355
out to the system log in that case.
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
356
357
358
TROUBLESHOOTING
359
360
See <doc/ecryptfs-faq.html>. For the most up-to-date FAQ, see
271 by Dustin Kirkland
update some sourceforge -> launchpad links
361
<http://launchpad.net/ecryptfs>.
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
362
363
364
BUGS
365
239 by Dustin Kirkland
update s/sourceforge/launchpad/g links
366
Please send bug reports to the Launchpad bug tracker:
367
 * https://bugs.launchpad.net/ecryptfs/+filebug
368
369
For kernel bugs, please follow the procedure
2 by mhalcrow@us.ibm.com
Initial import of eCryptfs filesystem userspace utilities (mount helper, daemon component,
370
detailed in the kernel documentation (Documentation/oops-tracing.txt)
371
to help us figure out what is happening.
372
373
374
Mike Halcrow
375
mhalcrow@us.ibm.com