1ENCFS(1) Encrypted Filesystem ENCFS(1)
2
6 encfs - mounts or creates an encrypted virtual filesystem
7
9 encfs [--version] [-v|--verbose] [-c|--config] [-t|--syslogtag] [-s]
10 [-f] [--annotate] [--standard] [--paranoia] [--insecure] [--reverse]
11 [--reversewrite] [--extpass=program] [-S|--stdinpass] [--anykey]
12 [--forcedecode] [-require-macs] [-i MINUTES|--idle=MINUTES]
13 [-m|--ondemand] [--delaymount] [-u|--unmount] [--public] [--nocache]
14 [--noattrcache] [--nodatacache] [--no-default-flags] [-o FUSE_OPTION]
15 [-d|--fuse-debug] [-H|--fuse-help] rootdir mountPoint [-- [Fuse Mount
16 Options]]
17
19 EncFS creates a virtual encrypted filesystem which stores encrypted
20 data in the rootdir directory and makes the unencrypted data visible at
21 the mountPoint directory. The user must supply a password which is
22 used to (indirectly) encrypt both filenames and file contents.
23 If EncFS is unable to find a supported filesystem at the specified
25 rootdir, then the user will be asked if they wish to create a new
26 encrypted filesystem at the specified location. Options will be
27 presented to the user allowing some control over the algorithms to use.
28 As EncFS matures, there may be an increasing number of choices.
29
31 --version
32 Shows EncFS version. Using --verbose before --version may display
33 additional information.
34 -c, --config
36 Causes EncFS to use the supplied file as the configuration file.
37 -v, --verbose
39 Causes EncFS to enable logging of various debug channels within
40 EncFS. Normally these logging messages are disabled and have no
41 effect. It is recommended that you run in foreground (-f) mode
42 when running with verbose enabled.
43 -t, --syslogtag
45 This option allows to set the syslog tag which will be used when
46 messages are logged via syslog. By default the syslog tag is set to
47 encfs.
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 -f The -f (foreground) option causes EncFS to run in the foreground.
55 Normally EncFS spawns off as a daemon and runs in the background,
56 returning control to the spawning shell. With the -f option, it
57 will run in the foreground and any warning/debug log messages will
58 be displayed on standard error. In the default (background) mode,
59 all log messages are logged via syslog.
60 --annotate
62 Print annotation lines to stderr during configuration.
63 --standard
65 If creating a new filesystem, this automatically selects standard
66 configuration options, to help with automatic filesystem creation.
67 This is the set of options that should be used unless you know what
68 you're doing and have read the documentation.
69 When not creating a filesystem, this flag does nothing.
71 --paranoia
73 Same as --standard, but for paranoia mode.
74 --insecure
76 Allows you to disable data encoding, thus to pass plain data as is.
77 Fully discouraged of course!
78 --reverse
80 Normally EncFS provides a plaintext view of data on demand: it
81 stores enciphered data and displays plaintext data. With --reverse
82 it takes as source plaintext data and produces enciphered data on-
83 demand. This can be useful for creating remote encrypted backups,
84 where you do not wish to keep the local files unencrypted.
85 For example, the following would create an encrypted view in
87 /tmp/crypt-view.
88 encfs --reverse /home/me /tmp/crypt-view
90 You could then copy the /tmp/crypt-view directory in order to have
92 a copy of the encrypted data. You must also keep a copy of the
93 file /home/me/.encfs6.xml which contains the filesystem
94 information. Together, the two can be used to reproduce the
95 unencrypted data:
96 ENCFS6_CONFIG=/home/me/.encfs6.xml encfs /tmp/crypt-view /tmp/plain-view
98 Now /tmp/plain-view contains the same data as /home/me
100 Note that --reverse mode only works with limited configuration
102 options, so many settings may be disabled when used. Incompatible
103 options as for now : Filename Initialization Vector Chaining and
104 External IV Chaining.
105 --reversewrite
107 Same as --reverse but will allow writes, if possible (configuration
108 must have UniqueIV disabled). Incompatible option : Per-File
109 Initialization Vectors.
110 --extpass=program
112 Specify an external program to use for getting the user password.
113 When the external program is spawned, the environment variable
114 "RootDir" will be set to contain the path to the root directory.
115 The program should print the password to standard output.
116 EncFS takes everything returned from the program to be the
118 password, except for a trailing newline (\n) which will be removed.
119 For example, specifying --extpass=/usr/lib/ssh/ssh-askpass will
121 cause EncFS to use ssh's password prompt program.
122 Note: EncFS reads at most 2k of data from the password program, and
124 it removes any trailing newline. Versions before 1.4.x accepted
125 only 64 bytes of text.
126 -S, --stdinpass
128 Read password from standard input, without prompting. This may be
129 useful for scripting encfs mounts.
130 Note that you should make sure the filesystem and mount points
132 exist first. Otherwise encfs will prompt for the filesystem
133 creation options, which may interfere with your script.
134 --anykey
136 Turn off key validation checking. This allows EncFS to be used
137 with secondary passwords. This could be used to store a separate
138 set of files in an encrypted filesystem. EncFS ignores files which
139 do not decode properly, so files created with separate passwords
140 will only be visible when the filesystem is mounted with their
141 associated password.
142 Note that if the primary password is changed (using encfsctl), the
144 other passwords will not be usable unless the primary password is
145 set back to what it was, as the other passwords rely on an invalid
146 decoding of the volume key, which will not remain the same if the
147 primary password is changed.
148 Warning: Use this option at your own risk.
150 --forcedecode
152 This option only has an effect on filesystems which use MAC block
153 headers. By default, if a block is decoded and the stored MAC
154 doesn't match what is calculated, then an IO error is returned to
155 the application and the block is not returned. However, by
156 specifying --forcedecode, only an error will be logged and the data
157 will still be returned to the application. This may be useful for
158 attempting to read corrupted files.
159 --require-macs
161 If creating a new filesystem, this forces block authentication code
162 headers to be enabled. When mounting an existing filesystem, this
163 causes encfs to exit if block authentication code headers are not
164 enabled.
165 This can be used to improve security in case the ciphertext is
167 vulnerable to tampering, by preventing an attacker from disabling
168 MACs in the config file.
169 -i, --idle=MINUTES
171 Enable automatic unmount of the filesystem after a period of
172 inactivity. The period is specified in minutes, so the shortest
173 timeout period that can be requested is one minute. EncFS will not
174 automatically unmount if there are files open within the
175 filesystem, even if they are open in read-only mode. However
176 simply having files open does not count as activity.
177 -m, --ondemand
179 Mount the filesystem on-demand. This currently only makes sense in
180 combination with --idle and --extpass options. When the filesystem
181 becomes idle, instead of exiting, EncFS stops allowing access to
182 the filesystem by internally dropping its reference to it. If
183 someone attempts to access the filesystem again, the extpass
184 program is used to prompt the user for the password. If this
185 succeeds, then the filesystem becomes available again.
186 --delaymount
188 Do not mount the filesystem when encfs starts; instead, delay
189 mounting until first use. This option only makes sense with
190 --ondemand.
191 -u, --unmount
193 Unmounts the specified mountPoint.
194 --public
196 Attempt to make encfs behave as a typical multi-user filesystem.
197 By default, all FUSE based filesystems are visible only to the user
198 who mounted them. No other users (including root) can view the
199 filesystem contents. The --public option does two things. It adds
200 the FUSE flags "allow_other" and "default_permission" when mounting
201 the filesystem, which tells FUSE to allow other users to access the
202 filesystem, and to use the ownership permissions provided by the
203 filesystem. Secondly, the --public flag changes how encfs's node
204 creation functions work - as they will try and set ownership of new
205 nodes based on the caller identification.
206 Warning: In order for this to work, encfs must be run as root --
208 otherwise it will not have the ability to change ownership of
209 files. I recommend that you instead investigate if the fuse
210 allow_other option can be used to do what you want before
211 considering the use of --public.
212 --nocache
214 Disable the kernel's cache of file attributes. Setting this option
215 makes EncFS pass "attr_timeout=0" and "entry_timeout=0" to FUSE.
216 This makes sure that modifications to the backing file attributes
217 that occour outside EncFS show up immediately in the EncFS mount.
218 The internal EncFS data cache is also disabled. The main use case
219 for --nocache is reverse mode.
220 --noattrcache
222 Same as --nocache but for attributes only.
223 --nodatacache
225 Same as --nocache but for data only.
226 --no-default-flags
228 Encfs adds the FUSE flags "use_ino" and "default_permissions" by
229 default, as of version 1.2.2, because that improves compatibility
230 with some programs. If for some reason you need to disable one or
231 both of these flags, use the option --no-default-flags.
232 The following command lines produce the same result:
234 encfs raw crypt
236 encfs --no-default-flags raw crypt -- -o use_ino,default_permissions
237 -o FUSE_ARG
239 Pass through FUSE args to the underlying library. This makes it
240 easy to pass FUSE options when mounting EncFS via mount (and
241 /etc/fstab). Eg:
242 mount encfs#/home/me-crypt /home/me -t fuse -o kernel_cache
244 Note that encfs arguments cannot be set this way. If you need to
246 set encfs arguments, create a wrapper, such as encfs-reverse;
247 #!/bin/sh
249 encfs --reverse "$@"
250 Then mount using the script path
252 mount encfs-reverse#/home/me /home/me-crypt -t fuse
254 -d, --fuse-debug
256 Enables debugging within the FUSE library. This should only be
257 used if you suspect a problem within FUSE itself (not EncFS), as it
258 generates a lot of low-level data and is not likely to be very
259 helpful in general problem tracking. Try verbose mode (-v) first,
260 which gives a higher level view of what is happening within EncFS.
261 -H, --fuse-help
263 Shows FUSE help.
264 -- The -- option tells EncFS to send any remaining arguments directly
266 to FUSE. In turn, FUSE passes the arguments to fusermount. See
267 the fusermount help page for information on available commands.
268
270 ENCFS6_CONFIG
271 Which config file (typically named .encfs6.xml) to use. By
272 default, the config file is read from the encrypted directory.
273 Using this option allows to store the config file separated from
274 the encrypted files.
275 Warning: If you lose the config file, the encrypted file contents
277 are irrecoverably lost. It contains the master key encrypted with
278 your password. Without the master key, recovery is impossible, even
279 if you know the password.
280
282 Create a new encrypted filesystem. Store the raw (encrypted) data in
283 "~/.crypt" , and make the unencrypted data visible in "~/crypt". Both
284 directories are in the home directory in this example. This example
285 shows the full output of encfs as it asks the user if they wish to
286 create the filesystem:
287 % encfs ~/.crypt ~/crypt
289 Directory "/home/me/.crypt" does not exist, create (y,n)?y
290 Directory "/home/me/crypt" does not exist, create (y,n)?y
291 Creating new encrypted volume.
292 Please choose from one of the following options:
293 enter "x" for expert configuration mode,
294 enter "p" for pre-configured paranoia mode,
295 anything else, or an empty line will select standard mode.
296 ?>
297 Standard configuration selected.
299 Using cipher Blowfish, key size 160, block size 512
300 New Password: <password entered here>
301 Verify: <password entered here>
302 The filesystem is now mounted and visible in ~/crypt. If files are
304 created there, they can be seen in encrypted form in ~/.crypt. To
305 unmount the filesystem, use fusermount with the -u (unmount) option:
306 % fusermount -u ~/crypt
308 Another example. To mount the same filesystem, but have fusermount
310 name the mount point '/dev/foo' (as shown in df and other tools which
311 read /etc/mtab), and also request kernel-level caching of file data
312 (which are both special arguments to fusermount):
313 % encfs ~/.crypt ~/crypt -- -n /dev/foo -c
315 Or, if you find strange behavior under some particular program when
317 working in an encrypted filesystem, it may be helpful to run in verbose
318 mode while reproducing the problem and send along the output with the
319 problem report:
320 % encfs -v -f ~/.crypt ~/crypt 2> encfs-report.txt
322 In order to avoid leaking sensitive information through the debugging
324 channels, all warnings and debug messages (as output in verbose mode)
325 contain only encrypted filenames. You can use the encfsctl program's
326 decode function to decode filenames if desired.
327
329 EncFS is not a true filesystem. It does not deal with any of the
330 actual storage or maintenance of files. It simply translates requests
331 (encrypting or decrypting as necessary) and passes the requests through
332 to the underlying host filesystem. Therefore any limitations of the
333 host filesystem will be inherited by EncFS (or possibly be further
334 limited).
335 One such limitation is filename length. If your underlying filesystem
337 limits you to N characters in a filename, then EncFS will limit you to
338 approximately 3*(N-2)/4. For example if the host filesystem limits to
339 255 characters, then EncFS will be limited to 189 character filenames.
340 This is because encrypted filenames are always longer than plaintext
341 filenames.
342
344 When EncFS is given a root directory which does not contain an existing
345 EncFS filesystem, it will give the option to create one. Note that
346 options can only be set at filesystem creation time. There is no
347 support for modifying a filesystem's options in-place.
348 If you want to upgrade a filesystem to use newer features, then you
350 need to create a new filesystem and mount both the old filesystem and
351 new filesystem at the same time and copy the old to the new.
352 Multiple instances of encfs can be run at the same time, including
354 different versions of encfs, as long as they are compatible with the
355 current FUSE module on your system.
356 A choice is provided for two pre-configured settings ('standard' and
358 'paranoia'), along with an expert configuration mode.
359 Standard mode uses the following settings:
361 Cipher: AES
362 Key Size: 192 bits
363 PBKDF2 with 1/2 second runtime, 160 bit salt
364 Filesystem Block Size: 1024 bytes
365 Filename Encoding: Block encoding with IV chaining
366 Unique initialization vector file headers
367 File holes passed through
368 Paranoia mode uses the following settings:
370 Cipher: AES
371 Key Size: 256 bits
372 PBKDF2 with 3 second runtime, 160 bit salt
373 Filesystem Block Size: 1024 bytes
374 Filename Encoding: Block encoding with IV chaining
375 Unique initialization vector file headers
376 Message Authentication Code block headers
377 External IV Chaining
378 File holes passed through
379 In the expert / manual configuration mode, each of the above options is
381 configurable. Here is a list of current options with some notes about
382 what they mean:
383
385 As of version 1.5, EncFS now uses PBKDF2 as the default key derivation
386 function. The number of iterations in the keying function is selected
387 based on wall clock time to generate the key. In standard mode, a
388 target time of 0.5 seconds is used, and in paranoia mode a target of
389 3.0 seconds is used.
390 On a 1.6Ghz AMD 64 system, roughly 64k iterations of the key derivation
392 function can be handled in half a second. The exact number of
393 iterations to use is stored in the configuration file, as it is needed
394 to remount the filesystem.
395 If an EncFS filesystem configuration from 1.4.x is modified with
397 version 1.5 (such as when using encfsctl to change the password), then
398 the new PBKDF2 function will be used and the filesystem will no longer
399 be readable by older versions.
400 Cipher
402 Which encryption algorithm to use. The list is generated
403 automatically based on what supported algorithms EncFS found in the
404 encryption libraries. When using a recent version of OpenSSL,
405 Blowfish and AES are the typical options.
406 Blowfish is an 8 byte cipher - encoding 8 bytes at a time. AES is
408 a 16 byte cipher.
409 Cipher Key Size
411 Many, if not all, of the supported ciphers support multiple key
412 lengths. There is not really much need to have enormous key
413 lengths. Even 160 bits (the default) is probably overkill.
414 Filesystem Block Size
416 This is the size (in bytes) that EncFS deals with at one time.
417 Each block gets its own initialization vector and is encoded in the
418 cipher's cipher-block-chaining mode. A partial block at the end of
419 a file is encoded using a stream mode to avoid having to store the
420 filesize somewhere.
421 Having larger block sizes reduces the overhead of EncFS a little,
423 but it can also add overhead if your programs read small parts of
424 files. In order to read a single byte from a file, the entire
425 block that contains that byte must be read and decoded, so a large
426 block size adds overhead to small requests. With write calls it is
427 even worse, as a block must be read and decoded, the change applied
428 and the block encoded and written back out.
429 The default is 512 bytes as of version 1.0. It was hard coded to
431 64 bytes in version 0.x, which was not as efficient as the current
432 setting for general usage.
433 Filename Encoding
435 New in 1.1. A choice is given between stream encoding of filename
436 and block encoding. The advantage of stream encoding is that the
437 encoded filenames will be as short as possible. If you have a
438 filename with a single letter, it will be very short in the encoded
439 form, where as block encoded filenames are always rounded up to the
440 block size of the encryption cipher (8 bytes for Blowfish and 16
441 bytes for AES).
442 The advantage of block encoding mode is that filename lengths all
444 come out as a multiple of the cipher block size. This means that
445 someone looking at your encrypted data can't tell as much about the
446 length of your filenames. It is on by default, as it takes a
447 similar amount of time to using the stream cipher. However stream
448 cipher mode may be useful if you want shorter encrypted filenames
449 for some reason.
450 Based on an underlying filesystem supporting a maximum of 255
452 characters in filenames, here is the maximum possible filename
453 length depending on the choosen encoding scheme : stream (189),
454 block (176), block32 (143). Note that we should rather talk about
455 bytes, when filenames contain special (multi-bytes) characters.
456 Prior to version 1.1, only stream encoding was supported.
458 Filename Initialization Vector Chaining
460 New in 1.1. In previous versions of EncFS, each filename element
461 in a path was encoded separately. So if "foo" encoded to "XXX",
462 then it would always encode that way (given the same encryption
463 key), no matter if the path was "a/b/foo", or "aa/foo/cc", etc.
464 That meant it was possible for someone looking at the encrypted
465 data to see if two files in different directories had the same
466 name, even though they wouldn't know what that name decoded to.
467 With initialization vector chaining, each directory gets its own
469 initialization vector. So "a/foo" and "b/foo" will have completely
470 different encoded names for "foo". This features has almost no
471 performance impact (for most operations), and so is the default in
472 all modes.
473 Note: One significant performance exception is directory renames.
475 Since the initialization vector for filename encoding depends on
476 the directory path, any rename requires re-encoding every filename
477 in the tree of the directory being changed. If there are thousands
478 of files, then EncFS will have to do thousands of renames. It may
479 also be possible that EncFS will come across a file that it can't
480 decode or doesn't have permission to move during the rename
481 operation, in which case it will attempt to undo any changes it
482 made up to that point and the rename will fail.
483 Per-File Initialization Vectors
485 New in 1.1. In previous versions of EncFS, each file was encoded
486 in the same way. Each block in a file has always had its own
487 initialization vector, but in a deterministic way, so that block N
488 in one file was encoded in the same way as block N in another file.
489 That made it possible for someone to tell if two files were
490 identical (or parts of the file were identical) by comparing the
491 encoded data.
492 With per-file initialization vectors, each file gets its own 64-bit
494 random initialization vector, so that each file is encrypted in a
495 different way.
496 This option is enabled by default.
498 Reverse mode derivates IV from inode number, it may then change for
500 example when source files are copied from one FS to another.
501 External IV Chaining
503 New in 1.1.3. This option is closely related to Per-File
504 Initialization Vectors and Filename Initialization Vector Chaining.
505 Basically it extends the initialization vector chaining from
506 filenames to the per-file initialization vector.
507 When this option is enabled, the per-file initialization vector is
509 encoded using the initialization vector derived from the filename
510 initialization vector chaining code. This means that the data in a
511 file becomes tied to the filename. If an encrypted file is renamed
512 outside of encfs, it will no longer be decodable within encfs.
513 Note that unless Block MAC headers are enabled, the decoding error
514 will not be detected and will result in reading random looking
515 data.
516 There is a cost associated with this. When External IV Chaining is
518 enabled, hard links will not be allowed within the filesystem, as
519 there would be no way to properly decode two different filenames
520 pointing to the same data.
521 Also, renaming a file requires modifying the file header. So
523 renames will only be allowed when the user has write access to the
524 file.
525 Because of these limits, this option is disabled by default for
527 standard mode (and enabled by default for paranoia mode).
528 This option may be incompatible with some cloud providers, as
530 during a rename, file's content changes, but not its timestamp. Due
531 to this, file's changes may no be correctly seen by cloud
532 providers' sync programs. It is then not recommended for cloud
533 usage.
534 Block MAC headers
536 New to 1.1. If this is enabled, every block in every file is
537 stored along with a cryptographic checksum (Message Authentication
538 Code). This makes it virtually impossible to modify a file without
539 the change being detected by EncFS. EncFS will refuse to read data
540 which does not pass the checksum, and will log the error and return
541 an IO error to the application.
542 This adds substantial overhead (default being 8 bytes per
544 filesystem block), plus computational overhead, and is not enabled
545 by default except in paranoia mode.
546 When this is not enabled and if EncFS is asked to read modified or
548 corrupted data, it will have no way to verify that the decoded data
549 is what was originally encoded.
550 File-hole pass-through
552 Make encfs leave holes in files. If a block is read as all zeros,
553 it will be assumed to be a hole and will be left as 0's when read
554 (not deciphered). This is required if accessing encfs using the
555 SMB protocol.
556 Enabled by default. Can be disabled in expert mode.
558
560 The primary goal of EncFS is to protect data off-line. That is,
561 provide a convenient way of storing files in a way that will frustrate
562 any attempt to read them if the files are later intercepted.
563 Some algorithms in EncFS are also meant to frustrate on-line attacks
565 where an attacker is assumed to be able to modify the files.
566 The most intrusive attacks, where an attacker has complete control of
568 the user's machine (and can therefore modify EncFS, or FUSE, or the
569 kernel itself) are not guarded against. Do not assume that encrypted
570 files will protect your sensitive data if you enter your password into
571 a compromised computer. How you determine that the computer is safe to
572 use is beyond the scope of this documentation.
573 That said, here are some example attacks and data gathering techniques
575 on the filesystem contents along with the algorithms EncFS supports to
576 thwart them:
577 Attack: modifying a few bytes of an encrypted file (without knowing
579 what they will decode to).
580 EncFS does not use any form of XOR encryption which would allow
581 single bytes to be modified without affecting others. Most
582 modifications would affect dozens or more bytes. Additionally, MAC
583 Block headers can be used to identify any changes to files.
584 Attack: copying a random block of one file to a random block of another
586 file.
587 Each block has its own [deterministic] initialization vector.
588 Attack: copying block N to block N of another file.
590 When the Per-File Initialization Vector support is enabled (default
591 in 1.1.x filesystems), a copied block will not decode properly when
592 copied to another file.
593 Attack: copying an entire file to another file.
595 Can be prevented by enabling External IV Chaining mode.
596 Attack: determine if two filenames are the same by looking at encrypted
598 names.
599 Filename Initialization Vector chaining prevents this by giving
600 each file a 64-bit initialization vector derived from its full path
601 name.
602 Attack: compare if two files contain the same data.
604 Per-File Initialization Vector support prevents this.
605
607 This library is distributed in the hope that it will be useful, but
608 WITHOUT ANY WARRANTY; without even the implied warranty of
609 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please refer to
610 the "COPYING" file distributed with EncFS for complete details.
611
613 EncFS was written by Valient Gough <vgough@pobox.com>.
614 Site : https://vgough.github.io/encfs/.
616 Support, bug reports... : https://github.com/vgough/encfs.
618 Mailing list : none.
620 Cygwin, Windows ports : https://github.com/vgough/encfs/wiki.
622
624 encfsctl(1)
6251.9.5 2022-07-21 ENCFS(1)