ENCFS(1) | Encrypted Filesystem | ENCFS(1) |
NAME¶
encfs - mounts or creates an encrypted virtual filesystemSYNOPSIS¶
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.
- --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.
encfs --reverse /home/me /tmp/crypt-view
ENCFS5_CONFIG=/home/me/.encfs5 encfs /tmp/crypt-view /tmp/plain-view
- --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.
- -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
#!/bin/sh encfs --reverse $*
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.
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.
- -S, --stdinpass
- Read password from standard input, without prompting. This
may be useful for scripting encfs mounts.
- --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.
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 ~/cryptAnother 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 -cOr, 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.txtIn 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.
- 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.
- 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).
- 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.
- 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.
- 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.
- 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.
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)2009-11-29 | 1.7.3 |