1ENCFS(1) Encrypted Filesystem ENCFS(1)
2
6 encfs - mounts or creates an encrypted virtual filesystem
7
9 encfs [--version] [-s] [-f] [-v⎪--verbose] [-i MINUTES⎪--idle=MINUTES]
10 [--extpass=program] [-S⎪--stdinpass] [--anykey] [--forcedecode]
11 [-d⎪--fuse-debug] [--public] [--no-default-flags] [--ondemand]
12 [--reverse] [--standard] [-o FUSE_OPTION] rootdir mountPoint [-- [Fuse
13 Mount Options]]
14
16 EncFS creates a virtual encrypted filesystem which stores encrypted
17 data in the rootdir directory and makes the unencrypted data visible at
18 the mountPoint directory. The user must supply a password which is
19 used to (indirectly) encrypt both filenames and file contents.
20 If EncFS is unable to find a supported filesystem at the specified
22 rootdir, then the user will be asked if they wish to create a new
23 encrypted filesystem at the specified location. Options will be pre‐
24 sented to the user allowing some control over the algorithms to use.
25 As EncFS matures, there may be an increasing number of choices.
26
28 -i, --idle=MINUTES
29 Enable automatic unmount of the filesystem after a period of inac‐
30 tivity. The period is specified in minutes, so the shortest time‐
31 out period that can be requested is one minute. EncFS will not
32 automatically unmount if there are files open within the filesys‐
33 tem, even if they are open in read-only mode. However simply hav‐
34 ing files open does not count as activity.
35 -f The -f (foreground) option causes EncFS to run in the foreground.
37 Normally EncFS spawns off as a daemon and runs in the background,
38 returning control to the spawning shell. With the -f option, it
39 will run in the foreground and any warning/debug log messages will
40 be displayed on standard error. In the default (background) mode,
41 all log messages are logged via syslog.
42 -v, --verbose
44 Causes EncFS to enable logging of various debug channels within
45 EncFS. Normally these logging messages are disabled and have no
46 effect. It is recommended that you run in foreground (-f) mode
47 when running with verbose enabled.
48 -s The -s (single threaded) option causes EncFS to run in single
50 threaded mode. By default, EncFS runs in multi-threaded mode.
51 This option is used during EncFS development in order to simplify
52 debugging and allow it to run under memory checking tools..
53 -d, --fuse-debug
55 Enables debugging within the FUSE library. This should only be
56 used if you suspect a problem within FUSE itself (not EncFS), as it
57 generates a lot of low-level data and is not likely to be very
58 helpful in general problem tracking. Try verbose mode (-v) first,
59 which gives a higher level view of what is happening within EncFS.
60 --forcedecode
62 This option only has an effect on filesystems which use MAC block
63 headers. By default, if a block is decoded and the stored MAC
64 doesn't match what is calculated, then an IO error is returned to
65 the application and the block is not returned. However, by speci‐
66 fying --forcedecode, only an error will be logged and the data will
67 still be returned to the application. This may be useful for
68 attempting to read corrupted files.
69 --public
71 Attempt to make encfs behave as a typical multi-user filesystem.
72 By default, all FUSE based filesystems are visible only to the user
73 who mounted them. No other users (including root) can view the
74 filesystem contents. The --public option does two things. It adds
75 the FUSE flags "allow_other" and "default_permission" when mounting
76 the filesystem, which tells FUSE to allow other users to access the
77 filesystem, and to use the ownership permissions provided by the
78 filesystem. Secondly, the --public flag changes how encfs's node
79 creation functions work - as they will try and set ownership of new
80 nodes based on the caller identification.
81 Warning: In order for this to work, encfs must be run as root --
83 otherwise it will not have the ability to change ownership of
84 files. I recommend that you instead investigate if the fuse
85 allow_other option can be used to do what you want before consider‐
86 ing the use of --public.
87 --ondemand
89 Mount the filesystem on-demand. This currently only makes sense in
90 combination with --idle and --extpass options. When the filesystem
91 becomes idle, instead of exiting, EncFS stops allowing access to
92 the filesystem by internally dropping it's reference to it. If
93 someone attempts to access the filesystem again, the extpass pro‐
94 gram is used to prompt the user for the password. If this suc‐
95 ceeds, then the filesystem becomes available again.
96 --reverse
98 Normally EncFS provides a plaintext view of data on demand. Nor‐
99 mally it stores enciphered data and displays plaintext data. With
100 --reverse it takes as source plaintext data and produces enciphered
101 data on-demand. This can be useful for creating remote encrypted
102 backups, where you do not wish to keep the local files unencrypted.
103 For example, the following would create an encrypted view in
105 /tmp/crypt-view.
106 encfs --reverse /home/me /tmp/crypt-view
108 You could then copy the /tmp/crypt-view directory in order to have
110 a copy of the encrypted data. You must also keep a copy of the
111 file /home/me/.encfs5 which contains the filesystem information.
112 Together, the two can be used to reproduce the unencrypted data:
113 ENCFS5_CONFIG=/home/me/.encfs5 encfs /tmp/crypt-view /tmp/plain-view
115 Now /tmp/plain-view contains the same data as /home/me
117 Note that --reverse mode only works with limited configuration
119 options, so many settings may be disabled when used.
120 --standard
122 If creating a new filesystem, this automatically selects standard
123 configuration options, to help with automatic filesystem creation.
124 This is the set of options that should be used unless you know what
125 you're doing and have read the documentation.
126 When not creating a filesystem, this flag does nothing.
128 -o FUSE_ARG
130 Pass through FUSE args to the underlying library. This makes it
131 easy to pass FUSE options when mounting EncFS via mount (and
132 /etc/fstab). Eg:
133 mount encfs#/home/me-crypt /home/me -t fuse -o kernel_cache
135 Note that encfs arguments cannot be set this way. If you need to
137 set encfs arguments, create a wrapper, such as encfs-reverse;
138 #!/bin/sh
140 encfs --reverse $*
141 Then mount using the script path
143 mount encfs-reverse#/home/me /home/me-crypt -t fuse
145 -- The -- option tells EncFS to send any remaining arguments directly
147 to FUSE. In turn, FUSE passes the arguments to fusermount. See
148 the fusermount help page for information on available commands.
149 --no-default-flags
151 Encfs adds the FUSE flags "use_ino" and "default_permissions" by
152 default, as of version 1.2.2, because that improves compatibility
153 with some programs.. If for some reason you need to disable one or
154 both of these flags, use the option --no-default-flags.
155 The following command lines produce the same result:
157 encfs raw crypt
159 encfs --no-default-flags raw crypt -- -o use_ino,default_permissions
160 --extpass=program
162 Specify an external program to use for getting the user password.
163 When the external program is spawned, the environment variable
164 "RootDir" will be set to contain the path to the root directory.
165 The program should print the password to standard output.
166 EncFS takes everything returned from the program to be the pass‐
168 word, except for a trailing newline (\n) which will be removed.
169 For example, specifying --extpass=/usr/lib/ssh/ssh-askpass will
171 cause EncFS to use ssh's password prompt program.
172 Note: EncFS reads at most 2k of data from the password program, and
174 it removes any trailing newline. Versions before 1.4.x accepted
175 only 64 bytes of text.
176 -S, --stdinpass
178 Read password from standard input, without prompting. This may be
179 useful for scripting encfs mounts.
180 Note that you should make sure the filesystem and mount points
182 exist first. Otherwise encfs will prompt for the filesystem cre‐
183 ation options, which may interfere with your script.
184 --anykey
186 Turn off key validation checking. This allows EncFS to be used
187 with secondary passwords. This could be used to store a separate
188 set of files in an encrypted filesystem. EncFS ignores files which
189 do not decode properly, so files created with separate passwords
190 will only be visible when the filesystem is mounted with their
191 associated password.
192 Note that if the primary password is changed (using encfsctl), the
194 other passwords will not be usable unless the primary password is
195 set back to what it was, as the other passwords rely on an invalid
196 decoding of the volume key, which will not remain the same if the
197 primary password is changed.
198 Warning: Use this option at your own risk.
200
202 Create a new encrypted filesystem. Store the raw (encrypted) data in
203 "~/.crypt" , and make the unencrypted data visible in "~/crypt". Both
204 directories are in the home directory in this example. This example
205 shows the full output of encfs as it asks the user if they wish to cre‐
206 ate the filesystem:
207 % encfs ~/.crypt ~/crypt
209 Directory "/home/me/.crypt" does not exist, create (y,n)?y
210 Directory "/home/me/crypt" does not exist, create (y,n)?y
211 Creating new encrypted volume.
212 Please choose from one of the following options:
213 enter "x" for expert configuration mode,
214 enter "p" for pre-configured paranoia mode,
215 anything else, or an empty line will select standard mode.
216 ?>
217 Standard configuration selected.
219 Using cipher Blowfish, key size 160, block size 512
220 New Password: <password entered here>
221 Verify: <password entered here>
222 The filesystem is now mounted and visible in ~/crypt. If files are
224 created there, they can be seen in encrypted form in ~/.crypt. To
225 unmount the filesystem, use fusermount with the -u (unmount) option:
226 % fusermount -u ~/crypt
228 Another example. To mount the same filesystem, but have fusermount
230 name the mount point '/dev/foo' (as shown in df and other tools which
231 read /etc/mtab), and also request kernel-level caching of file data
232 (which are both special arguments to fusermount):
233 % encfs ~/.crypt ~/crypt -- -n /dev/foo -c
235 Or, if you find strange behavior under some particular program when
237 working in an encrypted filesystem, it may be helpful to run in verbose
238 mode while reproducing the problem and send along the output with the
239 problem report:
240 % encfs -v -f ~/.crypt ~/crypt 2> encfs-report.txt
242 In order to avoid leaking sensitive information through the debugging
244 channels, all warnings and debug messages (as output in verbose mode)
245 contain only encrypted filenames. You can use the encfsctl program's
246 decode function to decode filenames if desired.
247
249 EncFS is not a true filesystem. It does not deal with any of the
250 actual storage or maintenance of files. It simply translates requests
251 (encrypting or decrypting as necessary) and passes the requests through
252 to the underlying host filesystem. Therefor any limitations of the
253 host filesystem will likely be inherited by EncFS (or possibly be fur‐
254 ther limited).
255 One such limitation is filename length. If your underlying filesystem
257 limits you to N characters in a filename, then EncFS will limit you to
258 approximately 3*(N-2)/4. For example if the host filesystem limits to
259 256 characters, then EncFS will be limited to 190 character filenames.
260 This is because encrypted filenames are always longer then plaintext
261 filenames.
262
264 When EncFS is given a root directory which does not contain an existing
265 EncFS filesystem, it will give the option to create one. Note that
266 options can only be set at filesystem creation time. There is no sup‐
267 port for modifying a filesystem's options in-place.
268 If you want to upgrade a filesystem to use newer features, then you
270 need to create a new filesystem and mount both the old filesystem and
271 new filesystem at the same time and copy the old to the new.
272 Multiple instances of encfs can be run at the same time, including dif‐
274 ferent versions of encfs, as long as they are compatible with the cur‐
275 rent FUSE module on your system.
276 A choice is provided for two pre-configured settings ('standard' and
278 'paranoia'), along with an expert configuration mode.
279 Standard mode uses the following settings:
281 Cipher: AES
282 Key Size: 192 bits
283 PBKDF2 with 1/2 second runtime, 160 bit salt
284 Filesystem Block Size: 1024 bytes
285 Filename Encoding: Block encoding with IV chaining
286 Unique initialization vector file headers
287 Paranoia mode uses the following settings:
289 Cipher: AES
290 Key Size: 256 bits
291 PBKDF2 with 3 second runtime, 160 bit salt
292 Filesystem Block Size: 1024 bytes
293 Filename Encoding: Block encoding with IV chaining
294 Unique initialization vector file headers
295 Message Authentication Code block headers
296 External IV Chaining
297 In the expert / manual configuration mode, each of the above options is
299 configurable. Here is a list of current options with some notes about
300 what they mean:
301
303 As of version 1.5, EncFS now uses PBKDF2 as the default key derivation
304 function. The number of iterations in the keying function is selected
305 based on wall clock time to generate the key. In standard mode, a tar‐
306 get time of 0.5 seconds is used, and in paranoia mode a target of 3.0
307 seconds is used.
308 On a 1.6Ghz AMD 64 system, it rougly 64k iterations of the key deriva‐
310 tion function can be handled in half a second. The exact number of
311 iterations to use is stored in the configuration file, as it is needed
312 to remount the filesystem.
313 If an EncFS filesystem configuration from 1.4.x is modified with ver‐
315 sion 1.5 (such as when using encfsctl to change the password), then the
316 new PBKDF2 function will be used and the filesystem will no longer be
317 readable by older versions.
318 Cipher
320 Which encryption algorithm to use. The list is generated automati‐
321 cally based on what supported algorithms EncFS found in the encryp‐
322 tion libraries. When using a recent version of OpenSSL, Blowfish
323 and AES are the typical options.
324 Blowfish is an 8 byte cipher - encoding 8 bytes at a time. AES is
326 a 16 byte cipher.
327 Cipher Key Size
329 Many, if not all, of the supported ciphers support multiple key
330 lengths. There is not really much need to have enormous key
331 lengths. Even 160 bits (the default) is probably overkill.
332 Filesystem Block Size
334 This is the size (in bytes) that EncFS deals with at one time.
335 Each block gets its own initialization vector and is encoded in the
336 cipher's cipher-block-chaining mode. A partial block at the end of
337 a file is encoded using a stream mode to avoid having to store the
338 filesize somewhere.
339 Having larger block sizes reduces the overhead of EncFS a little,
341 but it can also add overhead if your programs read small parts of
342 files. In order to read a single byte from a file, the entire
343 block that contains that byte must be read and decoded, so a large
344 block size adds overhead to small requests. With write calls it is
345 even worse, as a block must be read and decoded, the change applied
346 and the block encoded and written back out.
347 The default is 512 bytes as of version 1.0. It was hard coded to
349 64 bytes in version 0.x, which was not as efficient as the current
350 setting for general usage.
351 Filename Encoding
353 New in 1.1. A choice is given between stream encoding of filename
354 and block encoding. The advantage of stream encoding is that the
355 encoded filenames will be as short as possible. If you have a
356 filename with a single letter, it will be very short in the encoded
357 form, where as block encoded filenames are always rounded up to the
358 block size of the encryption cipher (8 bytes for Blowfish and 16
359 bytes for AES).
360 The advantage of block encoding mode is that filename lenths all
362 come out as a multiple of the cipher block size. This means that
363 someone looking at your encrypted data can't tell as much about the
364 length of your filenames. It is on by default, as it takes a simi‐
365 lar amount of time to using the stream cipher. However stream
366 cipher mode may be useful if you want shorter encrypted filenames
367 for some reason.
368 Prior to version 1.1, only stream encoding was supported.
370 Filename Initialization Vector Chaining
372 New in 1.1. In previous versions of EncFS, each filename element
373 in a path was encoded separately. So if "foo" encoded to "XXX",
374 then it would always encode that way (given the same encryption
375 key), no matter if the path was "a/b/foo", or "aa/foo/cc", etc.
376 That meant it was possible for someone looking at the encrypted
377 data to see if two files in different directories had the same
378 name, even though they wouldn't know what that name decoded to.
379 With initialization vector chaining, each directory gets its own
381 initialization vector. So "a/foo" and "b/foo" will have completely
382 different encoded names for "foo". This features has almost no
383 performance impact (for most operations), and so is the default in
384 all modes.
385 Note: One significant performance exception is directory renames.
387 Since the initialization vector for filename encoding depends on
388 the directory path, any rename requires re-encoding every filename
389 in the tree of the directory being changed. If there are thousands
390 of files, then EncFS will have to do thousands of renames. It may
391 also be possible that EncFS will come across a file that it can't
392 decode or doesn't have permission to move during the rename opera‐
393 tion, in which case it will attempt to undo any changes it made up
394 to that point and the rename will fail.
395 Per-File Initialization Vectors
397 New in 1.1. In previous versions of EncFS, each file was encoded
398 in the same way. Each block in a file has always had its own ini‐
399 tialization vector, but in a deterministic way so that block N in
400 one file is encoded in the same was as block N in another file.
401 That made it possible for someone to tell if two files were identi‐
402 cal (or parts of the file were identical) by comparing the encoded
403 data.
404 With per-file initialization vectors, each file gets its own 64bit
406 random initialization vector, so that each file is encrypted in a
407 different way.
408 This option is enabled by default.
410 External IV Chaining
412 New in 1.1.3. This option is closely related to Per-File Initial‐
413 ization Vectors and Filename Initialization Vector Chaining. Basi‐
414 cally it extends the initialization vector chaining from filenames
415 to the per-file initialization vector.
416 When this option is enabled, the per-file initialization vector is
418 encoded using the initialization vector derived from the filename
419 initialization vector chaining code. This means that the data in a
420 file becomes tied to the filename. If an encrypted file is renamed
421 outside of encfs, it will no longer be decodable within encfs.
422 Note that unless Block MAC headers are enabled, the decoding error
423 will not be detected and will result in reading random looking
424 data.
425 There is a cost associated with this. When External IV Chaining is
427 enabled, hard links will not be allowed within the filesystem, as
428 there would be no way to properly decode two different filenames
429 pointing to the same data.
430 Also, renaming a file requires modifying the file header. So
432 renames will only be allowed when the user has write access to the
433 file.
434 Because of these limits, this option is disabled by default for
436 standard mode (and enabled by default for paranoia mode).
437 Block MAC headers
439 New to 1.1. If this is enabled, every block in every file is
440 stored along with a cryptographic checksum (Message Authentication
441 Code). This makes it virtually impossible to modify a file without
442 the change being detected by EncFS. EncFS will refuse to read data
443 which does not pass the checksum, and will log the error and return
444 an IO error to the application.
445 This adds substantial overhead (default being 8 bytes per filesys‐
447 tem block), plus computational overhead, and is not enabled by
448 default except in paranoia mode.
449 When this is not enabled and if EncFS is asked to read modified or
451 corrupted data, it will have no way to verify that the decoded data
452 is what was originally encoded.
453
455 The primary goal of EncFS is to protect data off-line. That is, pro‐
456 vide a convenient way of storing files in a way that will frustrate any
457 attempt to read them if the files are later intercepted.
458 Some algorithms in EncFS are also meant to frustrate on-line attacks
460 where an attacker is assumed to be able to modify the files.
461 The most intrusive attacks, where an attacker has complete control of
463 the user's machine (and can therefor modify EncFS, or FUSE, or the ker‐
464 nel itself) are not guarded against. Do not assume that encrypted
465 files will protect your sensitive data if you enter your password into
466 a compromised computer. How you determine that the computer is safe to
467 use is beyond the scope of this documentation.
468 That said, here are some example attacks and data gathering techniques
470 on the filesystem contents along with the algorithms EncFS supports to
471 thwart them:
472 Attack: modifying a few bytes of an encrypted file (without knowing
474 what they will decode to).
475 EncFS does not use any form of XOR encryption which would allow
476 single bytes to be modified without affecting others. Most modifi‐
477 cations would affect dozens or more bytes. Additionally, MAC Block
478 headers can be used to identify any changes to files.
479 Attack: copying a random block of one file to a random block of another
481 file.
482 Each block has its own [deterministic] initialization vector.
483 Attack: copying block N to block N of another file.
485 When the Per-File Initialization Vector support is enabled (default
486 in 1.1.x filesystems), a copied block will not decode properly when
487 copied to another file.
488 Attack: copying an entire file to another file.
490 Can be prevented by enabling External IV Chaining mode.
491 Attack: determine if two filenames are the same by looking at encrypted
493 names.
494 Filename Initialization Vector chaining prevents this by giving
495 each file a 64-bit initialization vector derived from its full path
496 name.
497 Attack: compare if two files contain the same data.
499 Per-File Initialization Vector support prevents this.
500
502 This library is distributed in the hope that it will be useful, but
503 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
504 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please refer to the
505 "COPYING" file distributed with EncFS for complete details.
506
508 EncFS was written by Valient Gough <vgough@pobox.com>.
509
511 encfsctl(1)
5121.7.3 2009-11-29 ENCFS(1)