1ENCFS(1)                     Encrypted Filesystem                     ENCFS(1)
2
3
4

NAME

6       encfs - mounts or creates an encrypted virtual filesystem
7

SYNOPSIS

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

DESCRIPTION

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
24       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

OPTIONS

31       --version
32           Shows EncFS version.  Using --verbose before --version may display
33           additional information.
34
35       -c, --config
36           Causes EncFS to use the supplied file as the configuration file.
37
38       -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
44       -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
49       -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
54       -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
61       --annotate
62           Print annotation lines to stderr during configuration.
63
64       --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
70           When not creating a filesystem, this flag does nothing.
71
72       --paranoia
73           Same as --standard, but for paranoia mode.
74
75       --insecure
76           Allows you to disable data encoding, thus to pass plain data as is.
77           Fully discouraged of course!
78
79       --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
86           For example, the following would create an encrypted view in
87           /tmp/crypt-view.
88
89               encfs --reverse /home/me /tmp/crypt-view
90
91           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
97               ENCFS6_CONFIG=/home/me/.encfs6.xml encfs /tmp/crypt-view /tmp/plain-view
98
99           Now /tmp/plain-view contains the same data as /home/me
100
101           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
106       --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
111       --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
117           EncFS takes everything returned from the program to be the
118           password, except for a trailing newline (\n) which will be removed.
119
120           For example, specifying --extpass=/usr/lib/ssh/ssh-askpass will
121           cause EncFS to use ssh's password prompt program.
122
123           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
127       -S, --stdinpass
128           Read password from standard input, without prompting.  This may be
129           useful for scripting encfs mounts.
130
131           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
135       --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
143           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
149           Warning: Use this option at your own risk.
150
151       --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
160       --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
166           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
170       -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
178       -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
187       --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
192       -u, --unmount
193           Unmounts the specified mountPoint.
194
195       --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
207           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
213       --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
221       --noattrcache
222           Same as --nocache but for attributes only.
223
224       --nodatacache
225           Same as --nocache but for data only.
226
227       --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
233           The following command lines produce the same result:
234
235               encfs raw crypt
236               encfs --no-default-flags raw crypt -- -o use_ino,default_permissions
237
238       -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
243               mount encfs#/home/me-crypt /home/me -t fuse -o kernel_cache
244
245           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
248               #!/bin/sh
249               encfs --reverse "$@"
250
251           Then mount using the script path
252
253               mount encfs-reverse#/home/me /home/me-crypt -t fuse
254
255       -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
262       -H, --fuse-help
263           Shows FUSE help.
264
265       --  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

ENVIRONMENT VARIABLES

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
276           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

EXAMPLES

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
288           % 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
298           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
303       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
307           % fusermount -u ~/crypt
308
309       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
314           % encfs ~/.crypt ~/crypt -- -n /dev/foo -c
315
316       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
321           % encfs -v -f ~/.crypt ~/crypt 2> encfs-report.txt
322
323       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

CAVEATS

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
336       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

FILESYSTEM OPTIONS

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
349       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
353       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
357       A choice is provided for two pre-configured settings ('standard' and
358       'paranoia'), along with an expert configuration mode.
359
360       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
369       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
380       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

Key Derivation Function

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
391       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
396       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
401       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
407           Blowfish is an 8 byte cipher - encoding 8 bytes at a time.  AES is
408           a 16 byte cipher.
409
410       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
415       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
422           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
430           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
434       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
443           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
451           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
457           Prior to version 1.1, only stream encoding was supported.
458
459       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
468           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
474           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
484       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
493           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
497           This option is enabled by default.
498
499           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
502       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
508           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
517           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
522           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
526           Because of these limits, this option is disabled by default for
527           standard mode (and enabled by default for paranoia mode).
528
529           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
535       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
543           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
547           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
551       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
557           Enabled by default.  Can be disabled in expert mode.
558

Attacks

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
564       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
567       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
574       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
578       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
585       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
589       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
594       Attack: copying an entire file to another file.
595           Can be prevented by enabling External IV Chaining mode.
596
597       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
603       Attack: compare if two files contain the same data.
604           Per-File Initialization Vector support prevents this.
605

DISCLAIMER

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

AUTHORS

613       EncFS was written by Valient Gough <vgough@pobox.com>.
614
615       Site : https://vgough.github.io/encfs/.
616
617       Support, bug reports... : https://github.com/vgough/encfs.
618
619       Mailing list : none.
620
621       Cygwin, Windows ports : https://github.com/vgough/encfs/wiki.
622

SEE ALSO

624       encfsctl(1)
625
626
627
6281.9.5                             2022-07-21                          ENCFS(1)
Impressum