Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ENCFS(1)		     Encrypted Filesystem		      ENCFS(1)

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]
       [--delaymount] [--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 its 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.

       --delaymount
	   Do not mount	the filesystem when encfs starts; instead, delay
	   mounting until first	use. This option only makes sense with
	   --ondemand.

       --require-macs
	   If creating a new filesystem, this forces block authentication code
	   headers to be enabled.  When	mounting an existing filesystem, this
	   causes encfs	to exit	if block authentication	code headers are not
	   enabled.

	   This	can be used to improve security	in case	the ciphertext is
	   vulnerable to tampering, by preventing an attacker from disabling
	   MACs	in the config file.

       --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/.encfs6.xml which contains the	filesystem
	   information.	 Together, the two can be used to reproduce the
	   unencrypted data:

	       ENCFS6_CONFIG=/home/me/.encfs6.xml 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.

       --nocache
	   Disable the kernel's	cache of file attributes.  Setting this	option
	   makes EncFS pass "attr_timeout=0" and "entry_timeout=0" to FUSE.
	   This	makes sure that	modifications to the backing files that	occour
	   outside EncFS show up immediately in	the EncFS mount. The main use
	   case	for "--nocache"	is reverse mode.

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

ENVIRONMENT VARIABLES
       ENCFS6_CONFIG
	   Which config	file (typically	named .encfs6.xml) to use.  By
	   default, the	config file is read from the encrypted directory.
	   Using this option allows to store the config	file separated from
	   the encrypted files.

	   Warning: If you lose	the config file, the encrypted file contents
	   are irrecoverably lost. It contains the master key encrypted	with
	   your	password. Without the master key, recovery is impossible, even
	   if you know the 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 ~/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.  Therefore any limitations of	the
       host filesystem will 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 than 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
	   File	holes passed through

       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
	   File	holes passed through

       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, roughly 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.

       File-hole pass-through
	   Make	encfs leave holes in files.  If	a block	is read	as all zeros,
	   it will be assumed to be a hole and will be left as 0's when	read
	   (not	deciphered).  This is required if accessing encfs using	the
	   SMB protocol.

	   Enabled by default.	Can be disabled	in expert mode.

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 therefore 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)

1.9.1				  2016-09-18			      ENCFS(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | EXAMPLES | CAVEATS | FILESYSTEM OPTIONS | Key Derivation Function | Attacks | DISCLAIMER | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=encfs&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help