.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "ENCFS 1" .TH ENCFS 1 "2020-05-14" "1.9.5" "Encrypted Filesystem" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" encfs \- mounts or creates an encrypted virtual filesystem .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBencfs\fR [\fB\-\-version\fR] [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-c\fR|\fB\-\-config\fR] [\fB\-t\fR|\fB\-\-syslogtag\fR] [\fB\-s\fR] [\fB\-f\fR] [\fB\-\-annotate\fR] [\fB\-\-standard\fR] [\fB\-\-paranoia\fR] [\fB\-\-insecure\fR] [\fB\-\-reverse\fR] [\fB\-\-reversewrite\fR] [\fB\-\-extpass=program\fR] [\fB\-S\fR|\fB\-\-stdinpass\fR] [\fB\-\-anykey\fR] [\fB\-\-forcedecode\fR] [\fB\-require\-macs\fR] [\fB\-i \s-1MINUTES\s0\fR|\fB\-\-idle=MINUTES\fR] [\fB\-m\fR|\fB\-\-ondemand\fR] [\fB\-\-delaymount\fR] [\fB\-u\fR|\fB\-\-unmount\fR] [\fB\-\-public\fR] [\fB\-\-nocache\fR] [\fB\-\-noattrcache\fR] [\fB\-\-nodatacache\fR] [\fB\-\-no\-default\-flags\fR] [\fB\-o \s-1FUSE_OPTION\s0\fR] [\fB\-d\fR|\fB\-\-fuse\-debug\fR] [\fB\-H\fR|\fB\-\-fuse\-help\fR] \&\fIrootdir\fR \fImountPoint\fR [\fB\-\-\fR [\fIFuse Mount Options\fR]] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBEncFS\fR creates a virtual encrypted filesystem which stores encrypted data in the \fIrootdir\fR directory and makes the unencrypted data visible at the \&\fImountPoint\fR directory. The user must supply a password which is used to (indirectly) encrypt both filenames and file contents. .PP If \fBEncFS\fR is unable to find a supported filesystem at the specified \&\fIrootdir\fR, 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 \fBEncFS\fR matures, there may be an increasing number of choices. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-version\fR" 4 .IX Item "--version" Shows \fBEncFS\fR version. Using \fB\-\-verbose\fR before \fB\-\-version\fR may display additional information. .IP "\fB\-c\fR, \fB\-\-config\fR" 4 .IX Item "-c, --config" Causes \fBEncFS\fR to use the supplied file as the configuration file. .IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 .IX Item "-v, --verbose" Causes \fBEncFS\fR to enable logging of various debug channels within \fBEncFS\fR. Normally these logging messages are disabled and have no effect. It is recommended that you run in foreground (\fB\-f\fR) mode when running with verbose enabled. .IP "\fB\-t\fR, \fB\-\-syslogtag\fR" 4 .IX Item "-t, --syslogtag" This option allows to set the syslog tag which will be used when messages are logged via syslog. By default the syslog tag is set to \fBencfs\fR. .IP "\fB\-s\fR" 4 .IX Item "-s" The \fB\-s\fR (\fIsingle threaded\fR) option causes \fBEncFS\fR to run in single threaded mode. By default, \fBEncFS\fR runs in multi-threaded mode. This option is used during \fBEncFS\fR development in order to simplify debugging and allow it to run under memory checking tools. .IP "\fB\-f\fR" 4 .IX Item "-f" The \fB\-f\fR (\fIforeground\fR) option causes \fBEncFS\fR to run in the foreground. Normally \fBEncFS\fR spawns off as a daemon and runs in the background, returning control to the spawning shell. With the \fB\-f\fR 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. .IP "\fB\-\-annotate\fR" 4 .IX Item "--annotate" Print annotation lines to stderr during configuration. .IP "\fB\-\-standard\fR" 4 .IX Item "--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. .Sp When not creating a filesystem, this flag does nothing. .IP "\fB\-\-paranoia\fR" 4 .IX Item "--paranoia" Same as \fB\-\-standard\fR, but for \fBparanoia\fR mode. .IP "\fB\-\-insecure\fR" 4 .IX Item "--insecure" Allows you to disable data encoding, thus to pass plain data as is. Fully discouraged of course! .IP "\fB\-\-reverse\fR" 4 .IX Item "--reverse" Normally \fBEncFS\fR provides a plaintext view of data on demand: it stores enciphered data and displays plaintext data. With \fB\-\-reverse\fR 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. .Sp For example, the following would create an encrypted view in /tmp/crypt\-view. .Sp .Vb 1 \& encfs \-\-reverse /home/me /tmp/crypt\-view .Ve .Sp 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: .Sp .Vb 1 \& ENCFS6_CONFIG=/home/me/.encfs6.xml encfs /tmp/crypt\-view /tmp/plain\-view .Ve .Sp Now /tmp/plain\-view contains the same data as /home/me .Sp Note that \fB\-\-reverse\fR mode only works with limited configuration options, so many settings may be disabled when used. Incompatible options as for now : Filename Initialization Vector Chaining and External \s-1IV\s0 Chaining. .IP "\fB\-\-reversewrite\fR" 4 .IX Item "--reversewrite" Same as \fB\-\-reverse\fR but will allow writes, if possible (configuration must have UniqueIV disabled). Incompatible option : Per-File Initialization Vectors. .IP "\fB\-\-extpass=program\fR" 4 .IX Item "--extpass=program" Specify an external program to use for getting the user password. When the external program is spawned, the environment variable \*(L"RootDir\*(R" will be set to contain the path to the root directory. The program should print the password to standard output. .Sp \&\fBEncFS\fR takes everything returned from the program to be the password, except for a trailing newline (\en) which will be removed. .Sp For example, specifying \fB\-\-extpass\fR=\fI/usr/lib/ssh/ssh\-askpass\fR will cause \&\fBEncFS\fR to use ssh's password prompt program. .Sp \&\fBNote\fR: \fBEncFS\fR 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. .IP "\fB\-S\fR, \fB\-\-stdinpass\fR" 4 .IX Item "-S, --stdinpass" Read password from standard input, without prompting. This may be useful for scripting encfs mounts. .Sp 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. .IP "\fB\-\-anykey\fR" 4 .IX Item "--anykey" Turn off key validation checking. This allows \fBEncFS\fR to be used with secondary passwords. This could be used to store a separate set of files in an encrypted filesystem. \fBEncFS\fR 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. .Sp Note that if the primary password is changed (using \fBencfsctl\fR), 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. .Sp \&\fBWarning\fR: Use this option at your own risk. .IP "\fB\-\-forcedecode\fR" 4 .IX Item "--forcedecode" This option only has an effect on filesystems which use \s-1MAC\s0 block headers. By default, if a block is decoded and the stored \s-1MAC\s0 doesn't match what is calculated, then an \s-1IO\s0 error is returned to the application and the block is not returned. However, by specifying \fB\-\-forcedecode\fR, 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. .IP "\fB\-\-require\-macs\fR" 4 .IX Item "--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. .Sp 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. .IP "\fB\-i\fR, \fB\-\-idle=MINUTES\fR" 4 .IX Item "-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. \fBEncFS\fR 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. .IP "\fB\-m\fR, \fB\-\-ondemand\fR" 4 .IX Item "-m, --ondemand" Mount the filesystem on-demand. This currently only makes sense in combination with \fB\-\-idle\fR and \fB\-\-extpass\fR options. When the filesystem becomes idle, instead of exiting, \fBEncFS\fR 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. .IP "\fB\-\-delaymount\fR" 4 .IX Item "--delaymount" Do not mount the filesystem when encfs starts; instead, delay mounting until first use. This option only makes sense with \fB\-\-ondemand\fR. .IP "\fB\-u\fR, \fB\-\-unmount\fR" 4 .IX Item "-u, --unmount" Unmounts the specified \fImountPoint\fR. .IP "\fB\-\-public\fR" 4 .IX Item "--public" Attempt to make encfs behave as a typical multi-user filesystem. By default, all \s-1FUSE\s0 based filesystems are visible only to the user who mounted them. No other users (including root) can view the filesystem contents. The \fB\-\-public\fR option does two things. It adds the \s-1FUSE\s0 flags \*(L"allow_other\*(R" and \&\*(L"default_permission\*(R" when mounting the filesystem, which tells \s-1FUSE\s0 to allow other users to access the filesystem, and to use the ownership permissions provided by the filesystem. Secondly, the \fB\-\-public\fR flag changes how encfs's node creation functions work \- as they will try and set ownership of new nodes based on the caller identification. .Sp \&\fBWarning\fR: 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 \fB\-\-public\fR. .IP "\fB\-\-nocache\fR" 4 .IX Item "--nocache" Disable the kernel's cache of file attributes. Setting this option makes EncFS pass \*(L"attr_timeout=0\*(R" and \*(L"entry_timeout=0\*(R" to \&\s-1FUSE.\s0 This makes sure that modifications to the backing file attributes that occour outside EncFS show up immediately in the EncFS mount. The internal EncFS data cache is also disabled. The main use case for \fB\-\-nocache\fR is reverse mode. .IP "\fB\-\-noattrcache\fR" 4 .IX Item "--noattrcache" Same as \fB\-\-nocache\fR but for attributes only. .IP "\fB\-\-nodatacache\fR" 4 .IX Item "--nodatacache" Same as \fB\-\-nocache\fR but for data only. .IP "\fB\-\-no\-default\-flags\fR" 4 .IX Item "--no-default-flags" \&\fBEncfs\fR adds the \s-1FUSE\s0 flags \*(L"use_ino\*(R" and \*(L"default_permissions\*(R" 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 \&\fB\-\-no\-default\-flags\fR. .Sp The following command lines produce the same result: .Sp .Vb 2 \& encfs raw crypt \& encfs \-\-no\-default\-flags raw crypt \-\- \-o use_ino,default_permissions .Ve .IP "\fB\-o \s-1FUSE_ARG\s0\fR" 4 .IX Item "-o FUSE_ARG" Pass through \fB\s-1FUSE\s0\fR args to the underlying library. This makes it easy to pass \s-1FUSE\s0 options when mounting \fBEncFS\fR via mount (and /etc/fstab). Eg: .Sp .Vb 1 \& mount encfs#/home/me\-crypt /home/me \-t fuse \-o kernel_cache .Ve .Sp Note that encfs arguments cannot be set this way. If you need to set encfs arguments, create a wrapper, such as encfs-reverse; .Sp .Vb 2 \& #!/bin/sh \& encfs \-\-reverse "$@" .Ve .Sp Then mount using the script path .Sp .Vb 1 \& mount encfs\-reverse#/home/me /home/me\-crypt \-t fuse .Ve .IP "\fB\-d\fR, \fB\-\-fuse\-debug\fR" 4 .IX Item "-d, --fuse-debug" Enables debugging within the \fB\s-1FUSE\s0\fR library. This should only be used if you suspect a problem within \fB\s-1FUSE\s0\fR itself (not \fBEncFS\fR), as it generates a lot of low-level data and is not likely to be very helpful in general problem tracking. Try \fIverbose\fR mode (\fB\-v\fR) first, which gives a higher level view of what is happening within \fBEncFS\fR. .IP "\fB\-H\fR, \fB\-\-fuse\-help\fR" 4 .IX Item "-H, --fuse-help" Shows \fB\s-1FUSE\s0\fR help. .IP "\fB\-\-\fR" 4 .IX Item "--" The \fB\-\-\fR option tells \fBEncFS\fR to send any remaining arguments directly to \&\fB\s-1FUSE\s0\fR. In turn, \fB\s-1FUSE\s0\fR passes the arguments to \fBfusermount\fR. See the \fBfusermount\fR help page for information on available commands. .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" .IP "\fB\s-1ENCFS6_CONFIG\s0\fR" 4 .IX Item "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. .Sp 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. .SH "EXAMPLES" .IX Header "EXAMPLES" Create a new encrypted filesystem. Store the raw (encrypted) data in \&\*(L"~/.crypt\*(R" , and make the unencrypted data visible in \*(L"~/crypt\*(R". 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: .PP .Vb 9 \& % 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: \& Verify: .Ve .PP The filesystem is now mounted and visible in \fI~/crypt\fR. If files are created there, they can be seen in encrypted form in \fI~/.crypt\fR. To unmount the filesystem, use \fIfusermount\fR with the \fB\-u\fR (unmount) option: .PP .Vb 1 \& % fusermount \-u ~/crypt .Ve .PP Another example. To mount the same filesystem, but have fusermount name the mount point '/dev/foo' (as shown in \fIdf\fR and other tools which read /etc/mtab), and also request kernel-level caching of file data (which are both special arguments to fusermount): .PP .Vb 1 \& % encfs ~/.crypt ~/crypt \-\- \-n /dev/foo \-c .Ve .PP 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: .PP .Vb 1 \& % encfs \-v \-f ~/.crypt ~/crypt 2> encfs\-report.txt .Ve .PP 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 \fIencfsctl\fR program's \fIdecode\fR function to decode filenames if desired. .SH "CAVEATS" .IX Header "CAVEATS" \&\fBEncFS\fR 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 \fBEncFS\fR (or possibly be further limited). .PP One such limitation is filename length. If your underlying filesystem limits you to N characters in a filename, then \fBEncFS\fR will limit you to approximately 3*(N\-2)/4. For example if the host filesystem limits to 255 characters, then \&\fBEncFS\fR will be limited to 189 character filenames. This is because encrypted filenames are always longer than plaintext filenames. .SH "FILESYSTEM OPTIONS" .IX Header "FILESYSTEM OPTIONS" When \fBEncFS\fR is given a root directory which does not contain an existing \&\fBEncFS\fR 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. .PP 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. .PP 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 \s-1FUSE\s0 module on your system. .PP A choice is provided for two pre-configured settings ('standard' and \&'paranoia'), along with an expert configuration mode. .PP \&\fIStandard\fR mode uses the following settings: Cipher: \s-1AES\s0 Key Size: 192 bits \s-1PBKDF2\s0 with 1/2 second runtime, 160 bit salt Filesystem Block Size: 1024 bytes Filename Encoding: Block encoding with \s-1IV\s0 chaining Unique initialization vector file headers File holes passed through .PP \&\fIParanoia\fR mode uses the following settings: Cipher: \s-1AES\s0 Key Size: 256 bits \s-1PBKDF2\s0 with 3 second runtime, 160 bit salt Filesystem Block Size: 1024 bytes Filename Encoding: Block encoding with \s-1IV\s0 chaining Unique initialization vector file headers Message Authentication Code block headers External \s-1IV\s0 Chaining File holes passed through .PP 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: .SH "Key Derivation Function" .IX Header "Key Derivation Function" As of version 1.5, \fBEncFS\fR now uses \s-1PBKDF2\s0 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. .PP On a 1.6Ghz \s-1AMD 64\s0 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. .PP If an \fBEncFS\fR filesystem configuration from 1.4.x is modified with version 1.5 (such as when using encfsctl to change the password), then the new \s-1PBKDF2\s0 function will be used and the filesystem will no longer be readable by older versions. .IP "\fICipher\fR" 4 .IX Item "Cipher" Which encryption algorithm to use. The list is generated automatically based on what supported algorithms \fBEncFS\fR found in the encryption libraries. When using a recent version of \fBOpenSSL\fR, Blowfish and \s-1AES\s0 are the typical options. .Sp Blowfish is an 8 byte cipher \- encoding 8 bytes at a time. \s-1AES\s0 is a 16 byte cipher. .IP "\fICipher Key Size\fR" 4 .IX Item "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. .IP "\fIFilesystem Block Size\fR" 4 .IX Item "Filesystem Block Size" This is the size (in bytes) that \fBEncFS\fR 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. .Sp Having larger block sizes reduces the overhead of \fBEncFS\fR 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. .Sp 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. .IP "\fIFilename Encoding\fR" 4 .IX Item "Filename Encoding" \&\fBNew in 1.1\fR. 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 \s-1AES\s0). .Sp The advantage of block encoding mode is that filename lengths 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. .Sp Based on an underlying filesystem supporting a maximum of 255 characters in filenames, here is the maximum possible filename length depending on the choosen encoding scheme : stream (189), block (176), block32 (143). Note that we should rather talk about bytes, when filenames contain special (multi-bytes) characters. .Sp Prior to version 1.1, only stream encoding was supported. .IP "\fIFilename Initialization Vector Chaining\fR" 4 .IX Item "Filename Initialization Vector Chaining" \&\fBNew in 1.1\fR. In previous versions of \fBEncFS\fR, each filename element in a path was encoded separately. So if \*(L"foo\*(R" encoded to \*(L"\s-1XXX\*(R",\s0 then it would always encode that way (given the same encryption key), no matter if the path was \*(L"a/b/foo\*(R", or \*(L"aa/foo/cc\*(R", 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. .Sp With initialization vector chaining, each directory gets its own initialization vector. So \*(L"a/foo\*(R" and \*(L"b/foo\*(R" will have completely different encoded names for \*(L"foo\*(R". This features has almost no performance impact (for most operations), and so is the default in all modes. .Sp \&\fBNote:\fR 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. .IP "\fIPer-File Initialization Vectors\fR" 4 .IX Item "Per-File Initialization Vectors" \&\fBNew in 1.1\fR. In previous versions of \fBEncFS\fR, 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 was encoded in the same way 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. .Sp With per-file initialization vectors, each file gets its own 64\-bit random initialization vector, so that each file is encrypted in a different way. .Sp This option is enabled by default. .Sp Reverse mode derivates \s-1IV\s0 from inode number, it may then change for example when source files are copied from one \s-1FS\s0 to another. .IP "\fIExternal \s-1IV\s0 Chaining\fR" 4 .IX Item "External IV Chaining" \&\fBNew in 1.1.3\fR. 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. .Sp 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 \s-1MAC\s0 headers are enabled, the decoding error will not be detected and will result in reading random looking data. .Sp There is a cost associated with this. When External \s-1IV\s0 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. .Sp Also, renaming a file requires modifying the file header. So renames will only be allowed when the user has write access to the file. .Sp Because of these limits, this option is disabled by default for standard mode (and enabled by default for paranoia mode). .Sp This option may be incompatible with some cloud providers, as during a rename, file's content changes, but not its timestamp. Due to this, file's changes may no be correctly seen by cloud providers' sync programs. It is then not recommended for cloud usage. .IP "\fIBlock \s-1MAC\s0 headers\fR" 4 .IX Item "Block MAC headers" \&\fBNew to 1.1\fR. 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 \&\fBEncFS\fR. \fBEncFS\fR will refuse to read data which does not pass the checksum, and will log the error and return an \s-1IO\s0 error to the application. .Sp This adds substantial overhead (default being 8 bytes per filesystem block), plus computational overhead, and is not enabled by default except in paranoia mode. .Sp When this is not enabled and if \fBEncFS\fR is asked to read modified or corrupted data, it will have no way to verify that the decoded data is what was originally encoded. .IP "\fIFile-hole pass-through\fR" 4 .IX Item "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 \s-1SMB\s0 protocol. .Sp Enabled by default. Can be disabled in expert mode. .SH "Attacks" .IX Header "Attacks" The primary goal of \fBEncFS\fR 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. .PP Some algorithms in \fBEncFS\fR are also meant to frustrate on-line attacks where an attacker is assumed to be able to modify the files. .PP The most intrusive attacks, where an attacker has complete control of the user's machine (and can therefore modify \fBEncFS\fR, or \fB\s-1FUSE\s0\fR, 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. .PP That said, here are some example attacks and data gathering techniques on the filesystem contents along with the algorithms \fBEncFS\fR supports to thwart them: .IP "\fBAttack\fR: modifying a few bytes of an encrypted file (without knowing what they will decode to)." 4 .IX Item "Attack: modifying a few bytes of an encrypted file (without knowing what they will decode to)." \&\fBEncFS\fR does not use any form of \s-1XOR\s0 encryption which would allow single bytes to be modified without affecting others. Most modifications would affect dozens or more bytes. Additionally, \s-1MAC\s0 Block headers can be used to identify any changes to files. .IP "\fBAttack\fR: copying a random block of one file to a random block of another file." 4 .IX Item "Attack: copying a random block of one file to a random block of another file." Each block has its own [deterministic] initialization vector. .IP "\fBAttack\fR: copying block N to block N of another file." 4 .IX Item "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. .IP "\fBAttack\fR: copying an entire file to another file." 4 .IX Item "Attack: copying an entire file to another file." Can be prevented by enabling External \s-1IV\s0 Chaining mode. .IP "\fBAttack\fR: determine if two filenames are the same by looking at encrypted names." 4 .IX Item "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. .IP "\fBAttack\fR: compare if two files contain the same data." 4 .IX Item "Attack: compare if two files contain the same data." Per-File Initialization Vector support prevents this. .SH "DISCLAIMER" .IX Header "DISCLAIMER" This library is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 Please refer to the \*(L"\s-1COPYING\*(R"\s0 file distributed with \&\fBEncFS\fR for complete details. .SH "AUTHORS" .IX Header "AUTHORS" \&\fBEncFS\fR was written by \fBValient Gough \fR. .PP Site : \fBhttps://vgough.github.io/encfs/\fR. .PP Support, bug reports... : \fBhttps://github.com/vgough/encfs\fR. .PP Mailing list : none. .PP Cygwin, Windows ports : \fBhttps://github.com/vgough/encfs/wiki\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBencfsctl\fR\|(1)