README

   1 eCryptfs: A stacked cryptographic filesystem for Linux
   2
   3 eCryptfs is free software. Please see the file COPYING for details.
   4 For documentation, please see the files in the doc/ subdirectory.  For
   5 building and installation instructions please see the INSTALL file.
   6
   7 Lead developers:
   8         Tyler Hicks (kernel)
   9         Dustin Kirkland (userspace)
  10 Contributors:
  11         Michael Halcrow
  12         Michael C. Thompson
  13         Kent Yoder
  14         Trevor Highland
  15         Theresa Nelson
  16 Former maintainers:
  17         Phillip Hellewell
  18         Michael Halcrow
  19 Web Site: http://ecryptfs.org/
  20
  21 As you should do with any filesystem, make sure to maintain a backup
  22 copy of any data you write into eCryptfs.  In addition, you should
  23 reliably store your secret keys in a secure location.  eCryptfs uses
  24 industry-standard cryptographic ciphers, key generation, and
  25 passphrase protection mechanisms; without your salt/passphrase or
  26 private key, nobody will be able to retrieve your data.
  27
  28 eCryptfs requires the userspace tools available at:
  29
  30 <http://ecryptfs.org/downloads.html>
  31
  32 Requirements include:
  33  - Kernel version 2.6.19 or above
  34   - Build crypto API support with at least one symmetric key cipher
  35   - Build key retention support
  36   - If you have an older kernel, try the latest eCryptfs full package
  37     release to build a stand-alone kernel module
  38  - Userspace tools obtainable from the site listed above; requirements
  39    for the userspace tools are:
  40   - keyutils
  41    - David Howells' userspace keyring headers and libraries (version
  42      1.0 or higher)
  43    - Finding its way into some distros
  44    - Obtainable from <http://people.redhat.com/~dhowells/keyutils>
  45
  46
  47 KERNEL BUILD OPTIONS
  48
  49 Code maturity level options  --->
  50   [*] Prompt for development and/or incomplete code/drivers
  51
  52 Security options  --->
  53   <M> Enable access key retention support
  54
  55 Cryptographic options  --->
  56   <M>   CBC support
  57   <M>   ECB support
  58   <M>   MD5 digest algorithm
  59   <M>   AES cipher algorithms
  60
  61 File systems  --->
  62   Miscellaneous filesystems  --->
  63     <M> eCrypt filesystem layer support (EXPERIMENTAL)
  64
  65
  66 NOTES
  67
  68 eCryptfs is still in a developmental stage. When you upgrade the
  69 eCryptfs kernel module, it is possible that the eCryptfs file format
  70 has been updated. For this reason you should copy your files to an
  71 unencrypted location and then copy the files back into the new
  72 eCryptfs mount point to migrate the files.  File format version 3
  73 and beyond (in kernel version 2.6.24) is expected to remain readable,
  74 however.
  75
  76
  77 BUILD AND INSTALL INSTRUCTIONS
  78
  79 1) Consult the INSTALL file. In the majority of cases, this step
  80    should involve the standard procedure for Linux packages:
  81      % ./configure --prefix=/usr && make && make install
  82
  83 2) Make sure that you have sysfs mounted and that a valid entry for
  84    the sysfs mount point is in your /etc/mtab file.
  85
  86
  87 INTERACTIVE MOUNTING
  88
  89 Create a new directory into which eCryptfs will write its encrypted
  90 files (i.e., /root/crypt).  Then, create the mount point directory
  91 (i.e., /mnt/crypt).  Here is an example of how you might mount
  92 eCryptfs:
  93
  94 mount -t ecryptfs /root/crypt /mnt/crypt
  95
  96 Note that you can also perform a layover mount (essentially,
  97 converting an existing path into an eCryptfs mount point) to reduce
  98 the likelihood of contention between eCryptfs and other applications
  99 for access to the lower files; this is generally the recommended way
 100 to mount eCryptfs:
 101
 102 mount -t ecryptfs /secret /secret
 103
 104 Navigate the menus to select your preferred mount options.
 105
 106
 107 NON-INTERACTIVE MOUNTING
 108
 109 eCryptfs supports mounting through command-line options. You can do so
 110 by passing groups of name=value attribute pairs as a -o option to the
 111 mount helper.  Each key type has a set of name=value pairs associated
 112 with it.  For instance, the ``passphrase'' key type can accept a
 113 ``passwd=XXX'' name=value pair and a ``salt=XXX'' name=value pair.
 114 Attributes that apply to a particular key type immediately follow the
 115 key type specifier ``key=XXX'' and are separated by colons.
 116 Attributes that do not apply to any specific key type (general
 117 attributes) are separated by comma's.  The option string will take the
 118 form:
 119
 120  name1=value1,key=alias:name2=value2:name3=value3,name4=value4,name5=value5
 121
 122 name1=value1, name4=value4, and name5=value5 are all generic global
 123 attributes that can apply to any key type.  name2=value2 and
 124 name3=value3 are specific to the key type.
 125
 126 A BNF grammar for the option set follows:
 127
 128 <NULL> ::=
 129 <letter> ::= (a | b | c | ... | z)
 130 <letter-string> ::= <letter> (<letter-string> | <NULL>)
 131 <character> ::= <any printable ASCII character that is not , or :>
 132 <character-elem> ::= (<character> | <NULL>)
 133 <character-string> ::= <character-elem> (<character-string> | <NULL>)
 134 <name> ::= <letter-string>
 135 <value> ::= <character-string>
 136 <attr> ::= <name> "=" <value>
 137 <comma-attr-list> ::= <attr> ("," <comma-attr-list> | <NULL>)
 138 <colon-attr-list> ::= <attr> (":" <colon-attr-list> | <NULL>)
 139 <key-attr-list> ::= "key=" <letter-string> (<colon-attr-list> | <NULL>)
 140 <attr-list> ::= (<comma-attr-list> | <key-attr-list>)
 141 <options-set> ::= <attr-list> (<attr-list> | <NULL>)
 142
 143 Values read from a file should be specified with name value pairs. For
 144 example, a passphrase may be specified in a file by adding the following
 145 line to the file:
 146
 147 passwd=<passphrase>
 148
 149 Currently supported aliases and attributes parsed by the mount helper include:
 150
 151  key=passphrase:
 152      passphrase_passwd=<passphrase>
 153      passphrase_passwd_file=/path/to/file
 154      passphrase_passwd_fd=<file descriptor>
 155      passphrase_salt=<salt value>
 156
 157  key=openssl:
 158      openssl_keyfile=/path/to/key
 159      openssl_passwd=<passphrase>
 160      openssl_passwd_file=/path/to/file
 161      openssl_passwd_fd=<file descriptor>
 162
 163 The following general attributes are valid kernel mount options,
 164 and may also be acted upon by the mount helper, mount.ecryptfs:
 165
 166  ecryptfs_cipher=<cipher>
 167         Currently supported ciphers include:
 168          aes
 169          blowfish
 170          des3_ede
 171          cast5
 172          cast6
 173          twofish
 174
 175  ecryptfs_key_bytes=<key bytes>
 176         With the exception of AES-192, eCryptfs requires that the
 177         keysize be a multiple of the block size.
 178
 179  ecryptfs_sig=<hex signature>
 180         The signature for the FEKEK to use to encrypt the FEK for newly
 181         created files.  A key with description <sig> should be in the
 182         user's session keyring.  The mount helper, with its key modules,
 183         should make sure that the key gets placed there.
 184
 185  ecryptfs_passthrough
 186         Allows for non-eCryptfs files to be read and written from within an
 187         eCryptfs mount. This option is disabled by default.
 188
 189  ecryptfs_xattr_metadata
 190         When set, newly created files will have their cryptographic
 191         metadata stored in the extended attribute region of the file rather
 192         than the header (requires kernel support).
 193
 194  ecryptfs_encrypted_view
 195         When set, this option causes eCryptfs to present applications a
 196         view of encrypted files as if the cryptographic metadata were
 197         stored in the file header, whether the metadata is actually stored
 198         in the header or in the extended attributes.
 199
 200  ecryptfs_hmac
 201         When set, eCryptfs will include HMAC integrity enforcement to
 202         its files (requires kernel support).
 203
 204  ecryptfs_debug=<value>
 205         A value greater than 0 enables kernel debug messages, see NOTES
 206         below.
 207
 208 The following general attributes are parsed only by the mount helper,
 209 mount.ecryptfs:
 210
 211  no_sig_cache
 212         Do not perform any key signature cache checks. By default,
 213         when mounting, the eCryptfs mount helper will look for the key
 214         signature in <$HOME/.ecryptfs/sig-cache.txt>. If the key
 215         signature is not found, then the user will get a warning and
 216         will be prompted on whether to continue and whether to add the
 217         new key signature to the sig-cache.txt file. This behavior can
 218         be suppressed with the no_sig_cache option.
 219
 220 If you wish to have the same passphrase used in previous passphrase
 221 mounts and store it in a file (*not* recommended unless you can
 222 provide sufficient protection of the file itself), you can take the
 223 following steps:
 224
 225 (Previous mount; specify passphrase on command line)
 226 mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passphrase_passwd=my_passphrase
 227
 228 (Next mount; have passphrase read from a file)
 229 echo "passphrase_passwd=my_passphrase" > /mnt/secureusb/my_passphrase
 230 mount -t ecryptfs /mnt/dev /mnt/dir -o key=passphrase:passphrase_passwd_file=/mnt/secureusb/my_passphrase
 231
 232 Saving your unencrypted passphrase to a file on the same disk that
 233 contains your encrypted files defeats the purpose of using a
 234 cryptographic filesystem in the first place.  You should instead store
 235 the file that contains your passphrase on a physically secure medium,
 236 such as a USB flash drive that you keep locked in a drawer, if you
 237 choose to store it to a file at all.
 238
 239 In general, it is probably best to just type in your passphrase via
 240 stdin every time you need to perform a mount.  Future versions of
 241 eCryptfs will allow hardware token devices, such as a TPM chip, to
 242 protect your secret keys.
 243
 244
 245 TESTING A NEW MOUNT POINT
 246
 247 Try writing a new file:
 248
 249 echo "Hello, World" > /secret/hello.txt
 250
 251 The operation will complete.  When you unmount eCryptfs, you will
 252 Notice that there is a new file in /secret that is at least 12288
 253 bytes in size (depending on your host page size).  This is the
 254 encrypted underlying file for what you just wrote.  To test reading,
 255 from start to finish, you need to clear the user session keyring:
 256
 257 keyctl clear @u
 258
 259 Then umount /secret and mount again per the instructions given above.
 260
 261 cat /secret/hello.txt
 262
 263
 264 PAM MODULE
 265
 266 You can use the PAM module to automatically use a key based on your
 267 login passphrase, which can then be used to perform an eCryptfs mount
 268 non-interactively.
 269
 270 Perform an eCryptfs mount as root, using your user login:
 271
 272 root# mount -t ecryptfs /secret /secret
 273
 274 Then, grab your raw mount parameters from
 275
 276 root# grep "ecryptfs" /etc/mtab
 277
 278 You should get something like this:
 279
 280 ---
 281 /secret /secret ecryptfs rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0
 282 ---
 283
 284 Add ``user'' and ``noauto'' to the mount options:
 285
 286 ---
 287 /secret /secret ecryptfs user,noauto,rw,ecryptfs_sig=deadbeefdeadbeef,ecryptfs_key_bytes=16,ecryptfs_cipher=aes 0 0
 288 ---
 289
 290 Append your edited line to your /etc/fstab file. Now it's time to test
 291 the mount.
 292
 293 root# umount /secret
 294
 295 Verify that eCryptfs is not mounted. Then, log in as the regular
 296 user. Manually add your passphrase to the user session keyring via the
 297 ecryptfs-manager utility. Then, perform the mount, while telling the
 298 mount application to not call the mount helper:
 299
 300 user# mount -i /secret
 301
 302 Verify that eCryptfs mounted correctly. Then, unmount:
 303
 304 user# umount /secret
 305
 306 Clear your user session keyring:
 307
 308 user# keyctl clear @u
 309
 310 Add the mount command into your login script (e.g., ~/.bash_profile):
 311
 312 ---
 313 mount -i /secret
 314 ---
 315
 316 Finally, add this to the appropriate /etc/pam* file (e.g.,
 317 /etc/pam.d/login) after the call to pam_unix.so:
 318
 319 ---
 320 auth required pam_ecryptfs.so
 321 ---
 322
 323 You will need to insert this intelligently into your PAM stack so that
 324 PAM actually calls pam_ecryptfs.so. Depending on your distribution,
 325 this may involve, for instance, changing the context of pam_unix.so
 326 from ``sufficient'' to ``required'' and moving pam_deny.so to another
 327 location in the stack. Be mindful of the security implications of any
 328 changes you make to your PAM stack.
 329
 330 From another window, try logging in as the user. If all went well, the
 331 eCryptfs PAM module will insert a key derived from your login
 332 passphrase into the user session keyring. Then, the login script will
 333 perform the mount, using the parameters in your /etc/fstab.
 334
 335 The script src/utils/ecryptfs-setup-pam.sh attempts to automate
 336 setting up PAM mounts on Red Hat-based distros. Use that for
 337 inspiration in setting up your own eCryptfs PAM mount.
 338
 339
 340 NOTES
 341
 342 eCryptfs shipping in kernel version 2.6.19 does not support public
 343 key.  To determine what your current kernel supports, load the
 344 ecryptfs module and view the contents of fs/ecryptfs/version_str under
 345 your sysfs mount point.
 346
 347 Do not run eCryptfs in higher verbosity levels unless you are doing so
 348 for the sole purpose of development, since secret values will be written
 349 out to the system log in that case.
 350
 351
 352 TROUBLESHOOTING
 353
 354 For the most up-to-date support resources, see
 355 <http://ecryptfs.org/support.html>.
 356
 357
 358 BUGS
 359
 360 Please send bug reports to the Launchpad bug tracker:
 361  * https://bugs.launchpad.net/ecryptfs/+filebug
 362
 363 For kernel bugs, please follow the procedure
 364 detailed in the kernel documentation (Documentation/oops-tracing.txt)
 365 to help us figure out what is happening.
 366
 367
 368 Mike Halcrow
 369 mhalcrow@us.ibm.com