Provided by: encfs_1.7.4-2.4ubuntu2_amd64 
NAME
encfs - mounts or creates an encrypted virtual filesystem
SYNOPSIS
encfs [--version] [-s] [-f] [-v⎪--verbose] [-i MINUTES⎪--idle=MINUTES] [--extpass=program]
[-S⎪--stdinpass] [--anykey] [--forcedecode] [-d⎪--fuse-debug] [--public]
[--no-default-flags] [--ondemand] [--reverse] [--standard] [-o FUSE_OPTION] rootdir
mountPoint [-- [Fuse Mount Options]]
DESCRIPTION
EncFS creates a virtual encrypted filesystem which stores encrypted data in the rootdir
directory and makes the unencrypted data visible at the mountPoint directory. The user
must supply a password which is used to (indirectly) encrypt both filenames and file
contents.
If EncFS is unable to find a supported filesystem at the specified rootdir, then the user
will be asked if they wish to create a new encrypted filesystem at the specified location.
Options will be presented to the user allowing some control over the algorithms to use.
As EncFS matures, there may be an increasing number of choices.
OPTIONS
-i, --idle=MINUTES
Enable automatic unmount of the filesystem after a period of inactivity. The period
is specified in minutes, so the shortest timeout period that can be requested is one
minute. EncFS will not automatically unmount if there are files open within the
filesystem, even if they are open in read-only mode. However simply having files open
does not count as activity.
-f The -f (foreground) option causes EncFS to run in the foreground. Normally EncFS
spawns off as a daemon and runs in the background, returning control to the spawning
shell. With the -f option, it will run in the foreground and any warning/debug log
messages will be displayed on standard error. In the default (background) mode, all
log messages are logged via syslog.
-v, --verbose
Causes EncFS to enable logging of various debug channels within EncFS. Normally these
logging messages are disabled and have no effect. It is recommended that you run in
foreground (-f) mode when running with verbose enabled.
-s The -s (single threaded) option causes EncFS to run in single threaded mode. By
default, EncFS runs in multi-threaded mode. This option is used during EncFS
development in order to simplify debugging and allow it to run under memory checking
tools..
-d, --fuse-debug
Enables debugging within the FUSE library. This should only be used if you suspect a
problem within FUSE itself (not EncFS), as it generates a lot of low-level data and is
not likely to be very helpful in general problem tracking. Try verbose mode (-v)
first, which gives a higher level view of what is happening within EncFS.
--forcedecode
This option only has an effect on filesystems which use MAC block headers. By
default, if a block is decoded and the stored MAC doesn't match what is calculated,
then an IO error is returned to the application and the block is not returned.
However, by specifying --forcedecode, only an error will be logged and the data will
still be returned to the application. This may be useful for attempting to read
corrupted files.
--public
Attempt to make encfs behave as a typical multi-user filesystem. By default, all FUSE
based filesystems are visible only to the user who mounted them. No other users
(including root) can view the filesystem contents. The --public option does two
things. It adds the FUSE flags "allow_other" and "default_permission" when mounting
the filesystem, which tells FUSE to allow other users to access the filesystem, and to
use the ownership permissions provided by the filesystem. Secondly, the --public flag
changes how encfs's node creation functions work - as they will try and set ownership
of new nodes based on the caller identification.
Warning: In order for this to work, encfs must be run as root -- otherwise it will not
have the ability to change ownership of files. I recommend that you instead
investigate if the fuse allow_other option can be used to do what you want before
considering the use of --public.
--ondemand
Mount the filesystem on-demand. This currently only makes sense in combination with
--idle and --extpass options. When the filesystem becomes idle, instead of exiting,
EncFS stops allowing access to the filesystem by internally dropping it's reference to
it. If someone attempts to access the filesystem again, the extpass program is used
to prompt the user for the password. If this succeeds, then the filesystem becomes
available again.
--reverse
Normally EncFS provides a plaintext view of data on demand. Normally it stores
enciphered data and displays plaintext data. With --reverse it takes as source
plaintext data and produces enciphered data on-demand. This can be useful for
creating remote encrypted backups, where you do not wish to keep the local files
unencrypted.
For example, the following would create an encrypted view in /tmp/crypt-view.
encfs --reverse /home/me /tmp/crypt-view
You could then copy the /tmp/crypt-view directory in order to have a copy of the
encrypted data. You must also keep a copy of the file /home/me/.encfs5 which contains
the filesystem information. Together, the two can be used to reproduce the
unencrypted data:
ENCFS5_CONFIG=/home/me/.encfs5 encfs /tmp/crypt-view /tmp/plain-view
Now /tmp/plain-view contains the same data as /home/me
Note that --reverse mode only works with limited configuration options, so many
settings may be disabled when used.
--standard
If creating a new filesystem, this automatically selects standard configuration
options, to help with automatic filesystem creation. This is the set of options that
should be used unless you know what you're doing and have read the documentation.
When not creating a filesystem, this flag does nothing.
-o FUSE_ARG
Pass through FUSE args to the underlying library. This makes it easy to pass FUSE
options when mounting EncFS via mount (and /etc/fstab). Eg:
mount encfs#/home/me-crypt /home/me -t fuse -o kernel_cache
Note that encfs arguments cannot be set this way. If you need to set encfs arguments,
create a wrapper, such as encfs-reverse;
#!/bin/sh
encfs --reverse $*
Then mount using the script path
mount encfs-reverse#/home/me /home/me-crypt -t fuse
-- The -- option tells EncFS to send any remaining arguments directly to FUSE. In turn,
FUSE passes the arguments to fusermount. See the fusermount help page for information
on available commands.
--no-default-flags
Encfs adds the FUSE flags "use_ino" and "default_permissions" by default, as of
version 1.2.2, because that improves compatibility with some programs.. If for some
reason you need to disable one or both of these flags, use the option
--no-default-flags.
The following command lines produce the same result:
encfs raw crypt
encfs --no-default-flags raw crypt -- -o use_ino,default_permissions
--extpass=program
Specify an external program to use for getting the user password. When the external
program is spawned, the environment variable "RootDir" will be set to contain the path
to the root directory. The program should print the password to standard output.
EncFS takes everything returned from the program to be the password, except for a
trailing newline (\n) which will be removed.
For example, specifying --extpass=/usr/lib/ssh/ssh-askpass will cause EncFS to use
ssh's password prompt program.
Note: EncFS reads at most 2k of data from the password program, and it removes any
trailing newline. Versions before 1.4.x accepted only 64 bytes of text.
-S, --stdinpass
Read password from standard input, without prompting. This may be useful for
scripting encfs mounts.
Note that you should make sure the filesystem and mount points exist first. Otherwise
encfs will prompt for the filesystem creation options, which may interfere with your
script.
--anykey
Turn off key validation checking. This allows EncFS to be used with secondary
passwords. This could be used to store a separate set of files in an encrypted
filesystem. EncFS ignores files which do not decode properly, so files created with
separate passwords will only be visible when the filesystem is mounted with their
associated password.
Note that if the primary password is changed (using encfsctl), the other passwords
will not be usable unless the primary password is set back to what it was, as the
other passwords rely on an invalid decoding of the volume key, which will not remain
the same if the primary password is changed.
Warning: Use this option at your own risk.
EXAMPLES
Create a new encrypted filesystem. Store the raw (encrypted) data in "~/.crypt" , and
make the unencrypted data visible in "~/crypt". Both directories are in the home
directory in this example. This example shows the full output of encfs as it asks the
user if they wish to create the filesystem:
% encfs ~/.crypt ~/crypt
Directory "/home/me/.crypt" does not exist, create (y,n)?y
Directory "/home/me/crypt" does not exist, create (y,n)?y
Creating new encrypted volume.
Please choose from one of the following options:
enter "x" for expert configuration mode,
enter "p" for pre-configured paranoia mode,
anything else, or an empty line will select standard mode.
?>
Standard configuration selected.
Using cipher Blowfish, key size 160, block size 512
New Password: <password entered here>
Verify: <password entered here>
The filesystem is now mounted and visible in ~/crypt. If files are created there, they
can be seen in encrypted form in ~/.crypt. To unmount the filesystem, use fusermount with
the -u (unmount) option:
% fusermount -u ~/crypt
Another example. To mount the same filesystem, but have fusermount name the mount point
'/dev/foo' (as shown in df and other tools which read /etc/mtab), and also request kernel-
level caching of file data (which are both special arguments to fusermount):
% encfs ~/.crypt ~/crypt -- -n /dev/foo -c
Or, if you find strange behavior under some particular program when working in an
encrypted filesystem, it may be helpful to run in verbose mode while reproducing the
problem and send along the output with the problem report:
% encfs -v -f ~/.crypt ~/crypt 2> encfs-report.txt
In order to avoid leaking sensitive information through the debugging channels, all
warnings and debug messages (as output in verbose mode) contain only encrypted filenames.
You can use the encfsctl program's decode function to decode filenames if desired.
CAVEATS
EncFS is not a true filesystem. It does not deal with any of the actual storage or
maintenance of files. It simply translates requests (encrypting or decrypting as
necessary) and passes the requests through to the underlying host filesystem. Therefor
any limitations of the host filesystem will likely be inherited by EncFS (or possibly be
further limited).
One such limitation is filename length. If your underlying filesystem limits you to N
characters in a filename, then EncFS will limit you to approximately 3*(N-2)/4. For
example if the host filesystem limits to 256 characters, then EncFS will be limited to 190
character filenames. This is because encrypted filenames are always longer then plaintext
filenames.
FILESYSTEM OPTIONS
When EncFS is given a root directory which does not contain an existing EncFS filesystem,
it will give the option to create one. Note that options can only be set at filesystem
creation time. There is no support for modifying a filesystem's options in-place.
If you want to upgrade a filesystem to use newer features, then you need to create a new
filesystem and mount both the old filesystem and new filesystem at the same time and copy
the old to the new.
Multiple instances of encfs can be run at the same time, including different versions of
encfs, as long as they are compatible with the current FUSE module on your system.
A choice is provided for two pre-configured settings ('standard' and 'paranoia'), along
with an expert configuration mode.
Standard mode uses the following settings:
Cipher: AES
Key Size: 192 bits
PBKDF2 with 1/2 second runtime, 160 bit salt
Filesystem Block Size: 1024 bytes
Filename Encoding: Block encoding with IV chaining
Unique initialization vector file headers
Paranoia mode uses the following settings:
Cipher: AES
Key Size: 256 bits
PBKDF2 with 3 second runtime, 160 bit salt
Filesystem Block Size: 1024 bytes
Filename Encoding: Block encoding with IV chaining
Unique initialization vector file headers
Message Authentication Code block headers
External IV Chaining
In the expert / manual configuration mode, each of the above options is configurable.
Here is a list of current options with some notes about what they mean:
Key Derivation Function
As of version 1.5, EncFS now uses PBKDF2 as the default key derivation function. The
number of iterations in the keying function is selected based on wall clock time to
generate the key. In standard mode, a target time of 0.5 seconds is used, and in paranoia
mode a target of 3.0 seconds is used.
On a 1.6Ghz AMD 64 system, it rougly 64k iterations of the key derivation function can be
handled in half a second. The exact number of iterations to use is stored in the
configuration file, as it is needed to remount the filesystem.
If an EncFS filesystem configuration from 1.4.x is modified with version 1.5 (such as when
using encfsctl to change the password), then the new PBKDF2 function will be used and the
filesystem will no longer be readable by older versions.
Cipher
Which encryption algorithm to use. The list is generated automatically based on what
supported algorithms EncFS found in the encryption libraries. When using a recent
version of OpenSSL, Blowfish and AES are the typical options.
Blowfish is an 8 byte cipher - encoding 8 bytes at a time. AES is a 16 byte cipher.
Cipher Key Size
Many, if not all, of the supported ciphers support multiple key lengths. There is not
really much need to have enormous key lengths. Even 160 bits (the default) is
probably overkill.
Filesystem Block Size
This is the size (in bytes) that EncFS deals with at one time. Each block gets its
own initialization vector and is encoded in the cipher's cipher-block-chaining mode.
A partial block at the end of a file is encoded using a stream mode to avoid having to
store the filesize somewhere.
Having larger block sizes reduces the overhead of EncFS a little, but it can also add
overhead if your programs read small parts of files. In order to read a single byte
from a file, the entire block that contains that byte must be read and decoded, so a
large block size adds overhead to small requests. With write calls it is even worse,
as a block must be read and decoded, the change applied and the block encoded and
written back out.
The default is 512 bytes as of version 1.0. It was hard coded to 64 bytes in version
0.x, which was not as efficient as the current setting for general usage.
Filename Encoding
New in 1.1. A choice is given between stream encoding of filename and block encoding.
The advantage of stream encoding is that the encoded filenames will be as short as
possible. If you have a filename with a single letter, it will be very short in the
encoded form, where as block encoded filenames are always rounded up to the block size
of the encryption cipher (8 bytes for Blowfish and 16 bytes for AES).
The advantage of block encoding mode is that filename lenths all come out as a
multiple of the cipher block size. This means that someone looking at your encrypted
data can't tell as much about the length of your filenames. It is on by default, as
it takes a similar amount of time to using the stream cipher. However stream cipher
mode may be useful if you want shorter encrypted filenames for some reason.
Prior to version 1.1, only stream encoding was supported.
Filename Initialization Vector Chaining
New in 1.1. In previous versions of EncFS, each filename element in a path was
encoded separately. So if "foo" encoded to "XXX", then it would always encode that
way (given the same encryption key), no matter if the path was "a/b/foo", or
"aa/foo/cc", etc. That meant it was possible for someone looking at the encrypted
data to see if two files in different directories had the same name, even though they
wouldn't know what that name decoded to.
With initialization vector chaining, each directory gets its own initialization
vector. So "a/foo" and "b/foo" will have completely different encoded names for
"foo". This features has almost no performance impact (for most operations), and so
is the default in all modes.
Note: One significant performance exception is directory renames. Since the
initialization vector for filename encoding depends on the directory path, any rename
requires re-encoding every filename in the tree of the directory being changed. If
there are thousands of files, then EncFS will have to do thousands of renames. It may
also be possible that EncFS will come across a file that it can't decode or doesn't
have permission to move during the rename operation, in which case it will attempt to
undo any changes it made up to that point and the rename will fail.
Per-File Initialization Vectors
New in 1.1. In previous versions of EncFS, each file was encoded in the same way.
Each block in a file has always had its own initialization vector, but in a
deterministic way so that block N in one file is encoded in the same was as block N in
another file. That made it possible for someone to tell if two files were identical
(or parts of the file were identical) by comparing the encoded data.
With per-file initialization vectors, each file gets its own 64bit random
initialization vector, so that each file is encrypted in a different way.
This option is enabled by default.
External IV Chaining
New in 1.1.3. This option is closely related to Per-File Initialization Vectors and
Filename Initialization Vector Chaining. Basically it extends the initialization
vector chaining from filenames to the per-file initialization vector.
When this option is enabled, the per-file initialization vector is encoded using the
initialization vector derived from the filename initialization vector chaining code.
This means that the data in a file becomes tied to the filename. If an encrypted file
is renamed outside of encfs, it will no longer be decodable within encfs. Note that
unless Block MAC headers are enabled, the decoding error will not be detected and will
result in reading random looking data.
There is a cost associated with this. When External IV Chaining is enabled, hard
links will not be allowed within the filesystem, as there would be no way to properly
decode two different filenames pointing to the same data.
Also, renaming a file requires modifying the file header. So renames will only be
allowed when the user has write access to the file.
Because of these limits, this option is disabled by default for standard mode (and
enabled by default for paranoia mode).
Block MAC headers
New to 1.1. If this is enabled, every block in every file is stored along with a
cryptographic checksum (Message Authentication Code). This makes it virtually
impossible to modify a file without the change being detected by EncFS. EncFS will
refuse to read data which does not pass the checksum, and will log the error and
return an IO error to the application.
This adds substantial overhead (default being 8 bytes per filesystem block), plus
computational overhead, and is not enabled by default except in paranoia mode.
When this is not enabled and if EncFS is asked to read modified or corrupted data, it
will have no way to verify that the decoded data is what was originally encoded.
Attacks
The primary goal of EncFS is to protect data off-line. That is, provide a convenient way
of storing files in a way that will frustrate any attempt to read them if the files are
later intercepted.
Some algorithms in EncFS are also meant to frustrate on-line attacks where an attacker is
assumed to be able to modify the files.
The most intrusive attacks, where an attacker has complete control of the user's machine
(and can therefor modify EncFS, or FUSE, or the kernel itself) are not guarded against.
Do not assume that encrypted files will protect your sensitive data if you enter your
password into a compromised computer. How you determine that the computer is safe to use
is beyond the scope of this documentation.
That said, here are some example attacks and data gathering techniques on the filesystem
contents along with the algorithms EncFS supports to thwart them:
Attack: modifying a few bytes of an encrypted file (without knowing what they will decode
to).
EncFS does not use any form of XOR encryption which would allow single bytes to be
modified without affecting others. Most modifications would affect dozens or more
bytes. Additionally, MAC Block headers can be used to identify any changes to files.
Attack: copying a random block of one file to a random block of another file.
Each block has its own [deterministic] initialization vector.
Attack: copying block N to block N of another file.
When the Per-File Initialization Vector support is enabled (default in 1.1.x
filesystems), a copied block will not decode properly when copied to another file.
Attack: copying an entire file to another file.
Can be prevented by enabling External IV Chaining mode.
Attack: determine if two filenames are the same by looking at encrypted names.
Filename Initialization Vector chaining prevents this by giving each file a 64-bit
initialization vector derived from its full path name.
Attack: compare if two files contain the same data.
Per-File Initialization Vector support prevents this.
DISCLAIMER
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Please refer to the "COPYING" file distributed with EncFS for complete details.
AUTHORS
EncFS was written by Valient Gough <vgough@pobox.com>.
SEE ALSO
encfsctl(1)