diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 369 |
1 files changed, 369 insertions, 0 deletions
@@ -0,0 +1,369 @@ +eCryptfs: A stacked cryptographic filesystem for Linux + +eCryptfs is free software. Please see the file COPYING for details. +For documentation, please see the files in the doc/ subdirectory. For +building and installation instructions please see the INSTALL file. + +Lead developers: + Tyler Hicks (kernel) + Dustin Kirkland (userspace) +Contributors: + Michael Halcrow + Michael C. Thompson + Kent Yoder + Trevor Highland + Theresa Nelson +Former maintainers: + Phillip Hellewell + Michael Halcrow +Web Site: http://ecryptfs.org/ + +As you should do with any filesystem, make sure to maintain a backup +copy of any data you write into eCryptfs. In addition, you should +reliably store your secret keys in a secure location. eCryptfs uses +industry-standard cryptographic ciphers, key generation, and +passphrase protection mechanisms; without your salt/passphrase or +private key, nobody will be able to retrieve your data. + +eCryptfs requires the userspace tools available at: + +<http://ecryptfs.org/downloads.html> + +Requirements include: + - Kernel version 2.6.19 or above + - Build crypto API support with at least one symmetric key cipher + - Build key retention support + - If you have an older kernel, try the latest eCryptfs full package + release to build a stand-alone kernel module + - Userspace tools obtainable from the site listed above; requirements + for the userspace tools are: + - keyutils + - David Howells' userspace keyring headers and libraries (version + 1.0 or higher) + - Finding its way into some distros + - Obtainable from <http://people.redhat.com/~dhowells/keyutils> + + +KERNEL BUILD OPTIONS + +Code maturity level options ---> + [*] Prompt for development and/or incomplete code/drivers + +Security options ---> + <M> Enable access key retention support + +Cryptographic options ---> + <M> CBC support + <M> ECB support + <M> MD5 digest algorithm + <M> AES cipher algorithms + +File systems ---> + Miscellaneous filesystems ---> + <M> eCrypt filesystem layer support (EXPERIMENTAL) + + +NOTES + +eCryptfs is still in a developmental stage. When you upgrade the +eCryptfs kernel module, it is possible that the eCryptfs file format +has been updated. For this reason you should copy your files to an +unencrypted location and then copy the files back into the new +eCryptfs mount point to migrate the files. File format version 3 +and beyond (in kernel version 2.6.24) is expected to remain readable, +however. + + +BUILD AND INSTALL INSTRUCTIONS + +1) Consult the INSTALL file. In the majority of cases, this step + should involve the standard procedure for Linux packages: + % ./configure --prefix=/usr && make && make install + +2) Make sure that you have sysfs mounted and that a valid entry for + the sysfs mount point is in your /etc/mtab file. + + +INTERACTIVE MOUNTING + +Create a new directory into which eCryptfs will write its encrypted +files (i.e., /root/crypt). Then, create the mount point directory +(i.e., /mnt/crypt). Here is an example of how you might mount +eCryptfs: + +mount -t ecryptfs /root/crypt /mnt/crypt + +Note that you can also perform a layover mount (essentially, +converting an existing path into an eCryptfs mount point) to reduce +the likelihood of contention between eCryptfs and other applications +for access to the lower files; this is generally the recommended way +to mount eCryptfs: + +mount -t ecryptfs /secret /secret + +Navigate the menus to select your preferred mount options. + + +NON-INTERACTIVE MOUNTING + +eCryptfs supports mounting through command-line options. You can do so +by passing groups of name=value attribute pairs as a -o option to the +mount helper. Each key type has a set of name=value pairs associated +with it. For instance, the ``passphrase'' key type can accept a +``passwd=XXX'' name=value pair and a ``salt=XXX'' name=value pair. +Attributes that apply to a particular key type immediately follow the +key type specifier ``key=XXX'' and are separated by colons. +Attributes that do not apply to any specific key type (general +attributes) are separated by comma's. The option string will take the +form: + + name1=value1,key=alias:name2=value2:name3=value3,name4=value4,name5=value5 + +name1=value1, name4=value4, and name5=value5 are all generic global +attributes that can apply to any key type. name2=value2 and +name3=value3 are specific to the key type. + +A BNF grammar for the option set follows: + +<NULL> ::= +<letter> ::= (a | b | c | ... | z) +<letter-string> ::= <letter> (<letter-string> | <NULL>) +<character> ::= <any printable ASCII character that is not , or :> +<character-elem> ::= (<character> | <NULL>) +<character-string> ::= <character-elem> (<character-string> | <NULL>) +<name> ::= <letter-string> +<value> ::= <character-string> +<attr> ::= <name> "=" <value> +<comma-attr-list> ::= <attr> ("," <comma-attr-list> | <NULL>) +<colon-attr-list> ::= <attr> (":" <colon-attr-list> | <NULL>) +<key-attr-list> ::= "key=" <letter-string> (<colon-attr-list> | <NULL>) +<attr-list> ::= (<comma-attr-list> | <key-attr-list>) +<options-set> ::= <attr-list> (<attr-list> | <NULL>) + +Values read from a file should be specified with name value pairs. For +example, a passphrase may be specified in a file by adding the following +line to the file: + +passwd=<passphrase> + +Currently supported aliases and attributes parsed by the mount helper include: + + key=passphrase: + passphrase_passwd=<passphrase> + passphrase_passwd_file=/path/to/file + passphrase_passwd_fd=<file descriptor> + passphrase_salt=<salt value> + + key=openssl: + openssl_keyfile=/path/to/key + openssl_passwd=<passphrase> + openssl_passwd_file=/path/to/file + openssl_passwd_fd=<file descriptor> + +The following general attributes are valid kernel mount options, +and may also be acted upon by the mount helper, mount.ecryptfs: + + ecryptfs_cipher=<cipher> + Currently supported ciphers include: + aes + blowfish + des3_ede + cast5 + cast6 + twofish + + ecryptfs_key_bytes=<key bytes> + With the exception of AES-192, eCryptfs requires that the + keysize be a multiple of the block size. + + ecryptfs_sig=<hex signature> + The signature for the FEKEK to use to encrypt the FEK for newly + created files. A key with description <sig> should be in the + user's session keyring. The mount helper, with its key modules, + should make sure that the key gets placed there. + + ecryptfs_passthrough + Allows for non-eCryptfs files to be read and written from within an + eCryptfs mount. This option is disabled by default. + + ecryptfs_xattr_metadata + When set, newly created files will have their cryptographic + metadata stored in the extended attribute region of the file rather + than the header (requires kernel support). + + ecryptfs_encrypted_view + When set, this option causes eCryptfs to present applications a + view of encrypted files as if the cryptographic metadata were + stored in the file header, whether the metadata is actually stored + in the header or in the extended attributes. + + ecryptfs_hmac + When set, eCryptfs will include HMAC integrity enforcement to + its files (requires kernel support). + + ecryptfs_debug=<value> + A value greater than 0 enables kernel debug messages, see NOTES + below. + +The following general attributes are parsed only by the mount helper, +mount.ecryptfs: + + no_sig_cache + Do not perform any key signature cache checks. By default, + when mounting, the eCryptfs mount helper will look for the key + signature in <$HOME/.ecryptfs/sig-cache.txt>. If the key + signature is not found, then the user will get a warning and + will be prompted on whether to continue and whether to add the + new key signature to the sig-cache.txt file. This behavior can + be suppressed with the no_sig_cache option. + +If you wish to have the same passphrase used in previous passphrase +mounts and store it in a file (*not* recommended unless you can +provide sufficient protection of the file itself), you can take the +following steps: + +(Previous mount; specify passphrase on command line) +mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passphrase_passwd=my_passphrase + +(Next mount; have passphrase read from a file) +echo "passphrase_passwd=my_passphrase" > /mnt/secureusb/my_passphrase +mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passphrase_passwd_file=/mnt/secureusb/my_passphrase + +Saving your unencrypted passphrase to a file on the same disk that +contains your encrypted files defeats the purpose of using a +cryptographic filesystem in the first place. You should instead store +the file that contains your passphrase on a physically secure medium, +such as a USB flash drive that you keep locked in a drawer, if you +choose to store it to a file at all. + +In general, it is probably best to just type in your passphrase via +stdin every time you need to perform a mount. Future versions of +eCryptfs will allow hardware token devices, such as a TPM chip, to +protect your secret keys. + + +TESTING A NEW MOUNT POINT + +Try writing a new file: + +echo "Hello, World" > /secret/hello.txt + +The operation will complete. When you unmount eCryptfs, you will +Notice that there is a new file in /secret that is at least 12288 +bytes in size (depending on your host page size). This is the +encrypted underlying file for what you just wrote. To test reading, +from start to finish, you need to clear the user session keyring: + +keyctl clear @u + +Then umount /secret and mount again per the instructions given above. + +cat /secret/hello.txt + + +PAM MODULE + +You can use the PAM module to automatically use a key based on your +login passphrase, which can then be used to perform an eCryptfs mount +non-interactively. + +Perform an eCryptfs mount as root, using your user login: + +root# mount -t ecryptfs /secret /secret + +Then, grab your raw mount parameters from + +root# grep "ecryptfs" /etc/mtab + +You should get something like this: + +--- +/secret /secret ecryptfs rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0 +--- + +Add ``user'' and ``noauto'' to the mount options: + +--- +/secret /secret ecryptfs user,noauto,rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0 +--- + +Append your edited line to your /etc/fstab file. Now it's time to test +the mount. + +root# umount /secret + +Verify that eCryptfs is not mounted. Then, log in as the regular +user. Manually add your passphrase to the user session keyring via the +ecryptfs-manager utility. Then, perform the mount, while telling the +mount application to not call the mount helper: + +user# mount -i /secret + +Verify that eCryptfs mounted correctly. Then, unmount: + +user# umount /secret + +Clear your user session keyring: + +user# keyctl clear @u + +Add the mount command into your login script (e.g., ~/.bash_profile): + +--- +mount -i /secret +--- + +Finally, add this to the appropriate /etc/pam* file (e.g., +/etc/pam.d/login) after the call to pam_unix.so: + +--- +auth required pam_ecryptfs.so +--- + +You will need to insert this intelligently into your PAM stack so that +PAM actually calls pam_ecryptfs.so. Depending on your distribution, +this may involve, for instance, changing the context of pam_unix.so +from ``sufficient'' to ``required'' and moving pam_deny.so to another +location in the stack. Be mindful of the security implications of any +changes you make to your PAM stack. + +From another window, try logging in as the user. If all went well, the +eCryptfs PAM module will insert a key derived from your login +passphrase into the user session keyring. Then, the login script will +perform the mount, using the parameters in your /etc/fstab. + +The script src/utils/ecryptfs-setup-pam.sh attempts to automate +setting up PAM mounts on Red Hat-based distros. Use that for +inspiration in setting up your own eCryptfs PAM mount. + + +NOTES + +eCryptfs shipping in kernel version 2.6.19 does not support public +key. To determine what your current kernel supports, load the +ecryptfs module and view the contents of fs/ecryptfs/version_str under +your sysfs mount point. + +Do not run eCryptfs in higher verbosity levels unless you are doing so +for the sole purpose of development, since secret values will be written +out to the system log in that case. + + +TROUBLESHOOTING + +For the most up-to-date support resources, see +<http://ecryptfs.org/support.html>. + + +BUGS + +Please send bug reports to the Launchpad bug tracker: + * https://bugs.launchpad.net/ecryptfs/+filebug + +For kernel bugs, please follow the procedure +detailed in the kernel documentation (Documentation/oops-tracing.txt) +to help us figure out what is happening. + + +Mike Halcrow +mhalcrow@us.ibm.com |