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 |