Difference between revisions of "ECryptfs"

From ArchWiki
Jump to: navigation, search
(Simple)
m (Manual setup: grammar (done with going through the diff now))
 
(223 intermediate revisions by 30 users not shown)
Line 1: Line 1:
 
{{Lowercase title}}
 
{{Lowercase title}}
[[Category:Security]]
+
[[Category:Encryption]]
 
[[Category:File systems]]
 
[[Category:File systems]]
 
[[fr:Encryption avec eCryptfs]]
 
[[fr:Encryption avec eCryptfs]]
 
[[it:System Encryption with eCryptfs]]
 
[[it:System Encryption with eCryptfs]]
[[ru:System Encryption with eCryptfs]]
+
[[ja:ECryptfs]]
{{Article summary start}}
+
[[ru:ECryptfs]]
{{Article summary text|Setup and usage of eCryptfs}}
+
{{Related articles start}}
{{Article summary heading|Related}}
+
{{Related|Disk encryption}}
{{Article summary wiki|Disk Encryption}}
+
{{Related articles end}}
{{Article summary end}}
+
This article describes basic usage of [https://launchpad.net/ecryptfs eCryptfs]. It guides you through the process of creating a private and secure encrypted directory within your {{ic|$HOME}} directory to store sensitive files and private data.
  
This article describes basic usage of [https://launchpad.net/ecryptfs eCryptfs]. It guides you through the process of creating a private and secure encrypted directory within your ''$HOME'' directory, where you can store all your sensitive files and private data.
+
In implementation eCryptfs differs from [[dm-crypt]], which provides a ''block device encryption layer'', while eCryptfs is an actual file-system – a [[wikipedia:Cryptographic_filesystems|stacked cryptographic file system]]. For comparison of the two you can refer to [http://ksouedu.com/doc/ecryptfs-utils/ecryptfs-faq.html#compare this table] and the [[Disk encryption#Comparison table]]. One distinguished feature is that the encryption is stacked on an existing filesystem; eCryptfs can be mounted onto any single existing directory and does not require a separate partition (or size pre-allocation).  
  
In implementation eCryptfs differs from dm-crypt, which provides a ''block device encryption layer'', while eCryptfs is an actual file-system – a [http://en.wikipedia.org/wiki/Cryptographic_filesystems stacked cryptographic file system] to be exact. For comparison of the two you can refer to [http://ecryptfs.sourceforge.net/ecryptfs-faq.html#compare this table ].
+
== Basics ==
  
The summary is that it doesn't require special on-disk storage allocation effort, such as separate partitions, you can mount eCryptfs on top of any single directory to protect it. That includes e.g. your entire $HOME and network file systems (i.e. having encrypted NFS shares). All cryptographic metadata is stored in the headers of files, so encrypted data can be easily moved, stored for backup and recovered. There are other advantages, but there are also drawbacks, for instance eCryptfs is not suitable for encrypting complete partitions which also means you can't protect your swap space with it (instead you can combine it with dm-crypt).
+
As mentioned in the summary eCryptfs does not require special on-disk storage allocation effort, such as a separate partition or pre-allocated space. Instead, you can mount eCryptfs on top of any single directory to protect it. That includes, for example, a user's entire {{ic|$HOME}} directory or single dedicated directories within it. All cryptographic metadata is stored in the headers of files, so encrypted data can be easily moved, stored for backup and recovered. There are other advantages, but there are also drawbacks, for instance eCryptfs is not suitable for encrypting complete partitions which also means you cannot protect swap space with it (but you can, of course, combine it with [[Dm-crypt/Swap encryption]]). If you are just starting to set up disk encryption, swap encryption and other points to consider are covered in [[Disk encryption#Preparation]].
  
For more details on how eCryptfs compares to other disk encryption solutions, see [[Disk Encryption#Comparison table]].  
+
To familiarize with eCryptfs a few points:
 +
* As a stacked filesystem, a mounting of an eCryptfs directory refers to mounting a (stacked) encrypted directory to another '''un'''encrypted mount point (directory) at Linux kernel runtime.
 +
* It is possible to share an encrypted directory between users. However, the encryption is linked to one passphrase so this must be shared as well. It is also possible to share a directory with differently encrypted files (different passphrases).
 +
* A number of eCryptfs acronyms are used throughout the documentation:
 +
** The encrypted directory is referred to as the '''lower''' and the unencrypted as the '''upper''' directory throughout the eCryptfs documentation and this article. While not relevant for this article, the "overlay" filesystem introduced with Linux 3.18 uses (and [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/filesystems/overlayfs.txt explains]) the same upper/lower nomenclatura for the stacking of filesystems.
 +
** the '''mount''' passphrase (or key) is what gives access to the encrypted files, i.e. unlocks the encryption. eCryptfs uses the term '''wrapped''' passphrase to refer to the cryptographically secured mount passphrase.
 +
** a {{ic|FEFEK}} refers to a '''F'''ile's '''E'''ncryption key '''E'''ncryption '''Key''' (see [https://www.kernel.org/doc/Documentation/security/keys-ecryptfs.txt kernel documentation]).
 +
** a {{ic|FNEK}} refers to a '''F'''ile '''N'''ame '''E'''ncryption '''K'''ey, a key to (optionally) encrypt the filenames stored in the encrypted directory.
  
== Deficiencies ==
+
Before using eCryptfs, the following disadvantages should be checked for applicability.
  
Before you make any big decisions like encrypting your $HOME you should know that eCyptfs does not handle sparse files well. For most intents and purposes that shouldn't concern us, however one very popular use case are torrents. Right now eCryptfs tries to encrypt the whole sparse file allocated space right away, which can lead to starving the system of resources in case of big files (remember torrents can easily be 10GB or bigger). You can track progress of this bug in this Launchpad report: https://bugs.launchpad.net/ubuntu/+source/ecryptfs-utils/+bug/431975
+
=== Deficiencies ===
  
Simple workaround, for now, is to create a '''.Public''' folder (as '''.Private''' folder is used for encrypted data later in the article) and use that for torrents, unencrypted and symlinked to a directory like ''~/Downloads/torrents''. For some people this of course defeats the whole purpose of encryption, for others who are protecting their data from theft it doesn't.
+
* Ease of use 
 +
:The {{Pkg|ecryptfs-utils}} package provides several different ways of setting up eCryptfs. The high-level "Ubuntu tools" are the easiest to use, but they hard-code the lower directory path and other settings, limiting their usefulness. The package also includes low-level tools which are fully configurable, but they are somewhat more difficult to use compared to alternatives like [[EncFS]].
 +
* Network storage mounts
 +
:eCryptfs has long-standing [https://bugs.launchpad.net/ecryptfs/+bug/277578 bugs] when used on top of NFS and possibly other networked filesystems. It is always possible to use eCryptfs on a local directory and then copy the encrypted files from the local directory to a network host. However, if you want to set up eCryptfs directly on top of an NFS mount, with no local copy of the files, eCryptfs may crash or behave incorrectly. If in doubt, [[EncFS]] may be a better choice in this case.
 +
* Sparse files
 +
:[[wikipedia:Sparse_file|Sparse files]] written to eCryptfs will produce larger, non-sparse encrypted files in the lower directory. For example, in an eCryptfs directory running {{ic|truncate -s 1G file.img}} creates a 1GB encrypted file on the underlying filesystem, with the corresponding resource (disk space, data throughput) requirements. If the same file were created on an unencrypted filesystem or a filesystem using [[Disk_encryption#Block device encryption|block device encryption]], it would only take a few kilobytes.
  
=== Login password ===
+
:This should be considered before encrypting large portions of the directory structure, though in most cases the disadvantages will be minor. If you need to use large sparse files, you can work around this issue by putting the sparse files in an unencrypted directory or using block device encryption for them.
  
{{note|1= With {{pkg|shadow}} 4.1.4.3-3 ''sha512'' is the default for new passwords (see [https://bugs.archlinux.org/task/13591#comment85993 bug 13591] and corresponding [https://projects.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/shadow&id=98001501a8306ef5a0df55d1cffc048851894940 commit]).}}
+
== Setup & mounting ==
  
If you are encrypting your whole home, with auto-mounting you should use a strong password and consider changing the hash algorithm for ''/etc/shadow'' from '''md5''' to stronger ones like '''sha512/bcrypt''' that helps to protect your password against rainbow-table attacks. See https://wiki.archlinux.org/index.php/SHA_password_hashes for more information.
+
Before starting, check the eCryptfs documentation. It is distributed with a very good and complete set of [http://ecryptfs.org/documentation.html manual pages].
  
== Basics ==
+
eCryptfs has been included in Linux since version 2.6.19. Start by loading the {{ic|ecryptfs}} module:
eCryptfs is a part of Linux since version 2.6.19. But to work with it you will need the userspace tools provided by the package {{pkg|ecryptfs-utils}} available in the [[Official Repositories]].
+
# modprobe ecryptfs
 +
 
 +
{{Tip|If you use {{Pkg|linux-grsec}}, auto-loading of cryptographic modules may fail when executing the {{ic|ecryptfs-mount-private}} wrapper (as of November 2014). As a work-around, load the mentioned module manually; for example {{ic|modprobe md5}} as root and [[Modprobe.d#Loading|configure]] the system to load it at next boot.}}
 +
 
 +
To actually mount an eCryptfs filesystem, you need to use userspace tools provided by the package {{pkg|ecryptfs-utils}} available in the [[Official repositories]]. Unfortunately, due to the poor design of these tools, you must choose between three ways of setting up eCryptfs with different tradeoffs:
 +
 
 +
# Use the [[#High-level tools (hardcoded paths)|high-level tools]], which set things up automatically but require the lower directory to be {{ic|~/.Private/}}, and allow only one encrypted filesystem per user.
 +
# Use [[#ecryptfs-simple|ecryptfs-simple]], available from AUR, which is an easy way to mount eCryptfs filesystems using any lower directory and upper directory.
 +
# [[#Manual setup]], which involves separate steps for loading the passphrase and mounting eCryptfs, but allows complete control over the directories and encryption settings.
 +
 
 +
=== High-level tools (hardcoded paths) ===
 +
 
 +
Most of the user-friendly convenience tools installed by the ''ecryptfs-utils'' package assume a very specific eCryptfs setup, namely the one that is officially used by Ubuntu (where it can be selected as an option during distro installation). Unfortunately, these choices are not just default options but are actually hard-coded in the tools. If this set-up does not suit your needs, then you can not use the convenience tools and will have to follow the steps at [[#Manual setup]] instead.
 +
 
 +
The set-up used by these tools is as follows:
 +
 
 +
* each user can have '''only one encrypted directory''' that is managed by these tools:
 +
** either full {{ic|$HOME}} directory encryption, or
 +
** a single encrypted data directory (by default {{ic|~/Private/}}, but this can be customized).
 +
* the '''lower directory''' for each user is always {{ic|~/.Private/}}<br><small>(in the case of full home dir encryption, this will be a symlink to the actual location at {{ic|/home/.ecryptfs/$USER/.Private/}})</small>
 +
* the '''encryption options''' used are:
 +
** ''cipher:'' AES
 +
** ''key length:'' 16 bytes (128 bits)
 +
** ''key management scheme:'' passphrase
 +
** ''plaintext passthrough:'' enabled
 +
* the '''configuration / control info''' for the encrypted directory is stored in a bunch of files at {{ic|~/.ecryptfs/}}:<br><small>(in the case of full home dir encryption, this will be a symlink to the actual location at {{ic|/home/.ecryptfs/$USER/.ecryptfs/}})</small>
 +
** {{ic|Private.mnt}} ''[plain text file]'' - contains the path where the upper directory should be mounted (e.g. {{ic|/home/lucy}} or {{ic|/home/lucy/Private}})
 +
** {{ic|Private.sig}} ''[plain text file]'' - contains the signature used to identify the mount passphrase in the kernel keyring
 +
** {{ic|wrapped-passphrase}} ''[binary file]'' - the mount passphrase, encrypted with the login passphrase
 +
** {{ic|auto-mount}}, {{ic|auto-umount}} ''[empty files]'' - if they exist, the {{ic|pam_ecryptfs.so}} module will (assuming it is loaded) automatically mount/unmount this encrypted directory when the user logs in/out
 +
 
 +
==== Encrypting a data directory ====
 +
For a full {{ic|$HOME}} directory encryption see [[#Encrypting a home directory]]
 +
 
 +
Before the data directory encryption is setup, decide whether it should later be mounted manually or automatically with the user log-in.
 +
 
 +
To encrypt a single data directory as a user and mount it manually later, run:
 +
$ ecryptfs-setup-private --nopwcheck --noautomount
 +
 
 +
and follow the instructions. The option {{ic|--nopwcheck}} enables you to choose a passphrase different to the user login passphrase and the option {{ic|--noautomount}} is self-explanatory. So, if you want to setup the encrypted directory automatically on log-in later, just ''leave out'' both options right away.
 +
 
 +
The script will automatically create the {{ic|~/.Private/}} and {{ic|~/.ecryptfs/}} directory structures as described in the box above. It will also ask for two passphrases:
 +
 
 +
;'''login passphrase''': This is the password you will have to enter each time you want to mount the encrypted directory. If you want auto-mounting on login to work, it has to be the same password you use to login to your user account.
 +
 
 +
;'''mount passphrase''': This is used to derive the actual file encryption master key. Thus, you should not enter a custom one unless you know what you are doing - instead press Enter to let it auto-generate a secure random one. It will be encrypted using the login passphrase and stored in this encrypted form in {{ic|~/.ecryptfs/wrapped-passphrase}}. Later it will automatically be decrypted ("unwrapped") again in RAM when needed, so you never have to enter it manually. Make sure this file does not get lost, otherwise you can never access your encrypted folder again! You may want to run {{ic|ecryptfs-unwrap-passphrase}} to see the mount passphrase in unencrypted form, write it down on a piece of paper, and keep it in a safe (or similar), so you can use it to recover your encrypted data in case the ''wrapped-passphrase'' file is accidentally lost/corrupted or in case you forget the login passphrase.
 +
 
 +
The mount point ("upper directory") for the encrypted folder will be at {{ic|~/Private}} by default, however you can manually change this right after the setup command has finished running, by doing:
 +
 
 +
$ mv ~/Private /path/to/new/folder
 +
$ echo /path/to/new/folder > ~/.ecryptfs/Private.mnt
 +
 
 +
To actually use your encrypted folder, you will have to mount it - see [[#Mounting]] below.
 +
 
 +
==== Encrypting a home directory ====
 +
 
 +
The wrapper script {{ic|ecryptfs-migrate-home}} will set up an encrypted home directory for a user and take care of migrating any existing files they have in their not yet encrypted home directory.
 +
 
 +
To run it, the user in question must be logged out and own no processes. The best way to achieve this is to log the user out, log into a console as the root user, and check that {{ic|ps -U ''username''}} returns no output.  You also need to ensure that you have {{pkg|rsync}} and {{pkg|lsof}} installed. Once the prerequisites have been met, run:
  
Once you have installed that package you can load the ecryptfs module and continue with the setup:
 
 
  # modprobe ecryptfs
 
  # modprobe ecryptfs
 +
# ecryptfs-migrate-home -u ''username''
  
The ecryptfs-utils package is distributed with a few helper scripts which will help you with key management and similar tasks. Some were written to automate this whole process of setting up encrypted directories (''ecryptfs-setup-private'') or help you combine eCryptfs with dm-crypt to protect swap space (''ecryptfs-setup-swap''). Despite those scripts we will go trough the process manually so you get a better understanding of what is really being done.
+
and follow the instructions. After the wrapper script is complete, follow the instructions for auto-mounting - see [[#Auto-mounting]] below. It is imperative that the user logs in ''before'' the next reboot, to complete the process.
  
Before we say anything else it's advised that you check the eCryptfs documentation. It is distributed with a very good and complete set of manual pages.
+
Once everything is working, the unencrypted backup of the users home directory, which is saved to {{ic|/home/''username''.''random_characters''}}, can and should be deleted.
  
=== Setup (simple) ===
+
==== Mounting ====
  
As a user run
+
===== Manually =====
ecryptfs-setup-private
+
and follow the instructions.
+
  
=== Setup (in detail) ===
+
Executing the wrapper
 +
$ ecryptfs-mount-private
 +
and entering the passphrase is all needed to mount the encrypted directory to the [[#High-level tools (hardcoded paths)|above]] described ''upper directory'' {{ic|~/Private}}.
  
First create your private directories, in this example we will call them exactly that: Private
+
Likewise, executing
  $ su -
+
  $ ecryptfs-umount-private
# mkdir -m 700 /home/username/.Private
+
will unmount it again.  
# mkdir -m 500 /home/username/Private
+
# chown username:username /home/username/{.Private,Private}
+
  
Let's summarize
+
{{Tip|If it is not required to access the private data permanently during a user session, maybe define an [[alias]] to speed the manual step up.}}
* Actual encrypted data will be stored in ~/.Private directory (so-called ''lower'' directory)
+
* While mounted, decrypted data will be available in ~/Private directory (so-called ''upper'' directory)
+
** While not mounted nothing can be written to this directory
+
** While mounted it has the same permissions as the lower directory
+
  
eCryptfs can now be mounted on top of ~/Private.
+
The tools include another script that can be very handy to access an encrypted {{ic|.Private}} data or home directory. Executing {{ic|ecryptfs-recover-private}} as root will search the system (or an optional specific path) for the directory, interactively query the passphrase for it and mount the directory. It can, for example, be used from a live-CD or different system to access the encrypted data in case of a recovery. Note that if booting from an Arch Linux ISO you must first install the {{pkg|ecryptfs-utils}} to it. Further, it will only be able to mount {{ic|.Private}} directories created with the Ubuntu tools.
  # mount -t ecryptfs /home/username/.Private /home/username/Private
+
  
You will need to answer a few questions and provide a passphrase which should be used to mount this directory in the future. However you can also have different keys encrypting different data (more about this below). For convenience we will limit this guide to only one key and passphrase. Let's see an example:
+
===== Auto-mounting =====
Key type: passphrase
+
Passphrase: ThisIsAVeryWeakPassphrase
+
Cipher: aes
+
Key byte: 16
+
Plaintext passtrough: no
+
Filename encryption: no
+
Add signature to cache: yes
+
  
Let's summarize
+
The default way to auto-mount an encrypted directory is via [[Pam_mount|PAM]]. See {{ic|man pam_ecryptfs}} and - for more details - 'PAM MODULE' in:
* The passphrase is your '''mount passphrase''' which will be salted, hashed and loaded into the kernel keyring.
+
/usr/share/doc/ecryptfs-utils/README
** In eCryptfs terms, this salted, hashed passphrase is your "file encryption key, encryption key", or '''fekek'''.
+
* eCryptfs supports a few different ciphers (AES, blowfish, twofish...). You can read about them on Wikipedia.
+
* Plaintext passtrough enables you to store and work with '''un-encrypted''' files stored in the lower directory.
+
* Filename encryption is available since Linux 2.6.29
+
** In eCryptfs terms the key used to protect filenames is known as "filename encryption key", or '''fnek'''.
+
* The signature of the key(s) will be stored in {{ic|/root/.ecryptfs/sig-cache.txt}}.
+
  
Since our later goal is to be able to mount without root privileges, we will now move the eCryptfs configuration directory to your own home and transfer the ownership to you:
+
For auto-mounting it is required that the passphrase to access the encrypted directory is synchronised with the user log-in.  
# mv /root/.ecryptfs /home/username
+
# chown username:username /home/username/.ecryptfs
+
  
Your setup is now complete and directory is mounted. You can place any file in the '''~/Private''' directory and it will get encrypted in '''~/.Private'''.
+
The following steps set it up:
  
Now copy a few files to your new private directory, and then un-mount it. If you inspect the files you will see that they are unreadable &ndash; encrypted. That was cool you say, but how do I get them back... and that brings us to:
+
1. Check if {{ic|~/.ecryptfs/auto-mount}}, {{ic|~/.ecryptfs/auto-umount}} and {{ic|~/.ecryptfs/wrapped-passphrase}} exist (these are automatically created by ''ecryptfs-setup-private'').
  
==== Extra Notes ====
+
2. Add ''ecryptfs'' to the pam-stack exactly as following to allow transparent unwrapping of the passphrase on login:
  
Above is detailed the simplest way to setup the mount point, but '''ecryptfs-setup-private''' runs through some extra steps.
+
Open {{ic|/etc/pam.d/system-auth}} and ''after'' the line containing {{ic|auth required pam_unix.so}} add:
 +
auth    required    pam_ecryptfs.so unwrap
 +
Next, ''above'' the line containing {{ic|password required pam_unix.so}} insert:
 +
password    optional    pam_ecryptfs.so
 +
And finally, ''after'' the line {{ic|session required pam_unix.so}} add:
 +
session    optional    pam_ecryptfs.so unwrap
  
* The above '''mount passphrase''' is derived from the passphrase you type in. This is not considered very [http://ecryptfs.sourceforge.net/ecryptfs-faq.html#pubkey-about secure], so the setup script grabs some characters from {{ic|/dev/random}} for safety:
+
3. Re-login and check output of ''mount'' which should now contain a mountpoint, e.g.:
 +
/home/$USER/.Private on /home/$USER/Private type ecryptfs (...)
 +
for the user's encrypted directory. It should be perfectly readable at {{ic|~$HOME/Private/}}.
  
od -x -N $bytes --width=$bytes /dev/urandom | head -n 1 | sed "s/^0000000//" | sed "s/\s*//g"
+
The latter should be automatically unmounted and made unavailable when the user logs off.
  
* '''ecryptfs-setup-private''' also takes the resulting mount passphrase and wraps it with your login passphrase (pasword) and stores this in '''~/.ecryptfs/wrapped-passphrase'''. You can replicate this with:
+
{{Warning|1=Unfortunately the automatic unmounting is susceptible to [https://bbs.archlinux.org/viewtopic.php?id=194509 break] with systemd and bugs are filed against it.[https://bugs.freedesktop.org/show_bug.cgi?id=72759] [https://nwrickert2.wordpress.com/2013/12/16/systemd-user-manager-ecryptfs-and-opensuse-13-1/] [https://bugs.launchpad.net/ubuntu/+source/ecryptfs-utils/+bug/313812/comments/43] [http://lists.alioth.debian.org/pipermail/pkg-systemd-maintainers/2014-October/004088.html]
 +
If you experience this problem, you can test it by commenting out {{ic|-session  optional  pam_systemd.so}} in {{ic|/etc/pam.d/system-login}}. However, this is no solution because commenting out will break other systemd functionalities.}}
  
$ ecryptfs-wrap-passphrase ~/.ecryptfs/wrapped-passphrase
+
=== ecryptfs-simple ===
  Passphrase to wrap:
+
  Wrapping passphrase:
+
  
=== Mounting (the hard way) ===
+
Use [http://xyne.archlinux.ca/projects/ecryptfs-simple/ ecryptfs-simple] if you just want to use eCryptfs to mount arbitrary directories the way you can with [[EncFS]]. ecryptfs-simple does not require root privileges or entries in {{ic|/etc/fstab}}, nor is it limited to hard-coded directories such as {{ic|~/.Private}}. The package is available to be [[installed]] as {{AUR|ecryptfs-simple}} and from [http://xyne.archlinux.ca/repos/ Xyne's repos].
Whenever you need your files available you can repeat the above mount procedure, using the same passphrase and options if you want to access your previously encrypted files or using a different passphrase (and possibly options) if for some reason you want to have different keys protecting different data (imagine having a publicly shared directory where different data is encrypted by different users, and their keys).
+
  
In any case going trough those questions every time could be a bit tedious.
+
As the name implies, usage is simple:
 +
# simple mounting
 +
ecryptfs-simple /path/to/foo /path/to/bar
  
One solution would be to create an entry in the '''{{ic|/etc/fstab}}''' file for this mount point:
+
# automatic mounting: prompts for options on the first mount of a directory then reloads them next time
 +
ecryptfs-simple -a /path/to/foo /path/to/bar
  
  /home/user/.Private /home/user/Private ecryptfs [... user ... ecryptfs_sig=XY,ecryptfs_cipher=aes,ecryptfs_key_bytes=16,ecryptfs_unlink_sigs 0 0
+
  # unmounting by source directory
 +
ecryptfs-simple -u /path/to/foo
  
* You will notice that we defined the '''user''' option, it enables you to mount the directory as a user (if it does not works as a normal user, you may need to setuid mount.ecryptfs by running as root: ''chmod +s /sbin/mount.ecryptfs'')
+
# unmounting by mountpoint
* Notice the '''ecryptfs_sig''' option, replace ''XY'' with your own key signature (as seen in the '''mtab''' line earlier and in {{ic|sig-cache.txt}})
+
ecryptfs-simple -u /path/to/bar
* If you enabled filename encryption then pass an additional mount option: '''ecryptfs_fnek_sig'''=''XY'', where ''XY'' is the same signature you provide with the '''ecryptfs_sig''' option.
+
* Last option '''ecrypfs_unlink_sigs''' ensures that your keyring is cleared every time the directory is un-mounted
+
  
Since your key was deleted from the kernel keyring when you un-mounted, in order to mount you need to insert it into the keyring again. You can use the '''ecryptfs-add-passphrase''' utility or the '''ecryptfs-manager''' to do it:
+
=== Manual setup ===
  
When the key is inserted you can mount the directory:  
+
The following details instructions to set up eCryptfs encrypted directories manually. This involves two steps. First, the passphrase is processed and loaded into the kernel keyring. Second, the filesystem is actually mounted using the key from the keyring.
 +
 
 +
There are two ways to add the passphrase to the kernel keyring in the first step. The simpler option is {{ic|ecryptfs-add-passphrase}}, which uses a single passphrase to encrypt the files. The disadvantage is that you cannot change the passphrase later. It works like this:
 
  $ ecryptfs-add-passphrase
 
  $ ecryptfs-add-passphrase
  Passphrase: ThisIsAVeryWeakPassphrase
+
Passphrase:  
   
+
  Inserted auth tok with sig [78c6f0645fe62da0] into the user session keyring
$ mount -i /home/username/Private
+
You can also pipe a passphrase into {{ic|ecryptfs-add-passphrase -}}. Keep in mind that if you leave your passphrase in a file, it will usually defeat the purpose of using encryption.
  
You will notice that we used the '''{{Ic|-i}}''' option this time. It disables invoking the mount helper. Speaking of which, using {{Ic|-i}} by default mounts with: '''nosuid, noexec''' and '''nodev'''. If you want to have at least executable files in your private directory you can add the '''exec''' option to the fstab line.
+
As an alternative to a plain passphrase, you can use a "wrapped passphrase", where the files are encrypted using a randomly generated key, which is itself encrypted with your passphrase and stored in a file. In this case, you can change your passphrase by unwrapping the key file with your old passphrase and rewrapping it using your new passphrase.  
  
This would be a good place to mention the '''keyctl''' utility from the (earlier installed) ''keyutils'' package. It can be used for any advanced key management tasks. Following examples show how to list your keyring contents and how to clear them:
+
In the following we do a generation similar to the [http://bazaar.launchpad.net/~ecryptfs/ecryptfs/trunk/view/head:/src/utils/ecryptfs-setup-private#L96 source] and then use ''ecryptfs-wrap-passphrase'' to wrap it with the password ("Arch") to {{ic|~/.ecryptfs/wrapped-passphrase}}:
  $ keyctl list @u
+
  $ printf "%s\n%s" $(od -x -N 100 --width=30 /dev/random | head -n 1 | sed "s/^0000000//" | sed "s/\s*//g") "Arch" | ecryptfs-wrap-passphrase /home/''username''/.ecryptfs/wrapped-passphrase
$ keyctl clear @u
+
  
{{Note|However, one should remember that /etc/fstab is for system-wide partitions only and should not be used for user-specific mounts}}
+
Next, we can enter our passphrase "Arch" to load the key into the keyring:
 +
$ printf "%s" "Arch" | ecryptfs-insert-wrapped-passphrase-into-keyring /home/''username''/.ecryptfs/wrapped-passphrase -
 +
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring
  
=== Auto-mounting (the easy way) ===
+
In either case, when you successfully add the passphrase to the kernel keyring, you will get a "key signature" like {{ic|78c6f0645fe62da0}} which you will need in the next step.
A better way is to use PAM directly, see:
+
/usr/share/doc/ecryptfs-utils/README
+
  
1. Open '''/etc/pam.d/login''' and add
+
There are two different ways of manually mounting eCryptfs, described in the following sections. The first way, using {{ic|mount.ecryptfs_private}}, can be run as a regular user and involves setting up some configuration files. This method does not allow you to change the encryption settings, such as key size. The second way is to use a raw {{ic|mount}} command, which gives you complete control over all settings, but requires you to either run it as root, or add an entry to {{ic|/etc/fstab}} which lets a user mount eCryptfs.
auth required pam_ecryptfs.so unwrap
+
after the line containing '''auth ... pam_unix.so''', and
+
session optional pam_ecryptfs.so unwrap
+
after the line '''session ... pam_unix.so'''.
+
  
2. Check if '''~/.ecryptfs/auto-mount''' and '''~/.ecryptfs/wrapped-passphrase''' (these are automatically created by '''ecryptfs-setup-private''') exist.
+
{{Tip|The following examples use an encrypted directory ({{ic|.secret}}) different to the default, hard-coded {{ic|.Private}} in the Ubuntu tools. This is on purpose to avoid problems of erroneous [[#Auto-mounting]] when the system has PAM setup for it, as well as problems with other tools using the hard-coded defaults.}}
  
3. Relogin and check output of '''mount''' which should now contain a mountpoint
+
==== With configuration files ====
/home/user/.Private...
+
  
=== Usage ===
+
This method involves running {{ic|mount.ecryptfs_private}} from the {{Pkg|ecryptfs-utils}} package, after first loading your passphrase. This binary requires no root privileges to work by default.
Besides using your private directory as storage for sensitive files, and private data, you can also use it to protect application data. Take ''Firefox'' for an example, not only does it have an internal password manager but the browsing history and cache can also be sensitive. Protecting it is easy:
+
  $ mv ~/.mozilla ~/Private/mozilla
+
  $ ln -s ~/Private/mozilla ~/.mozilla
+
  
=== Removal ===
+
First choose a name for your configuration files in {{ic|~/.ecryptfs}} and decide on the lower and upper directories. In this example we use {{ic|secret}} for the configuration files, put in encrypted data in {{ic|~/.secret}}, and mount the decrypted files at {{ic|~/secret}}. Create the required directories:
If you want to move a file out of the private directory just move it to it's new destination while ~/Private is mounted. Also note that there are no special steps involved if you want to remove your private directory. Make sure it is un-mounted and delete ~/.Private, along with all the files.
+
$ mkdir ~/.secret ~/secret ~/.ecryptfs
  
=== Backup ===
+
Now specify the directories in {{ic|~/.ecryptfs/secret.conf}}, using full paths. Its format looks like the one in {{ic|/etc/fstab}} without the mount options:
Setup explained here separates the directory with encrypted data from the mount point, so the encrypted data is available for backup at any time. With an overlay mount (i.e. ''~/Secret'' mounted over ''~/Secret'') the lower, encrypted, data is harder to get to. Today when cronjobs and other automation software do automatic backups the risk of leaking your sensitive data is higher.
+
$ echo "$HOME/.secret $HOME/secret ecryptfs" > ~/.ecryptfs/secret.conf
  
We explained earlier that all cryptographic metadata is stored in the headers of files. You can easily do backups, or incremental backups, of your '''~/.Private''' directory, treating it like any other directory.
+
Write the key signature you got from {{ic|ecryptfs-add-passphrase}} or {{ic|ecryptfs-insert-wrapped-passphrase-into-keyring}} (see above) into {{ic|~/.ecryptfs/secret.sig}}:
 +
$ echo 78c6f0645fe62da0 > ~/.ecryptfs/secret.sig
  
== Advanced ==
+
If you also want to enable filename encryption, add a second passphrase to the keyring (or reuse the first passphrase) and '''append''' its key signature to {{ic|~/.ecryptfs/secret.sig}}:
This wiki article covers only the basic setup of a private encrypted directory. There is however another article about eCryptfs on Arch Linux, which covers encryption of your entire $HOME and encrypting swap space without breaking hibernation (suspend to disk).
+
  $ echo 326a6d3e2a5d444a >> ~/.ecryptfs/secret.sig
  
That article includes many more steps (i.e. using PAM modules and automatic mounting) and the author was opposed to replicating it here, because there is just no single "right" way to do it. The author proposes some solutions and discusses the security implications, but they are his solutions and as such might not be the best nor are they endorsed by the eCryptfs project in any way.
+
Finally, mount {{ic|~/.secret}} on {{ic|~/secret}}:
 +
$ mount.ecryptfs_private secret
  
  Article: [http://sysphere.org/~anrxc/j/articles/ecryptfs/index.html eCryptfs and $HOME] by Adrian C. (anrxc).
+
When you're done, unmount it:
 +
  $ umount.ecryptfs_private secret
  
Consider that ''Chromium OS'', as released by Google, is using eCryptfs to protect devices that are, and will be, powered by it. Some implementation details are available and they make excellent reading. You can read them [http://www.chromium.org/chromium-os/chromiumos-design-docs/protecting-cached-user-data here], they could help a lot as you're coming up with your own strategy.
+
==== Raw mount command ====
  
=== PAM Mount ===
+
By running the actual {{ic|mount}} command manually, you get complete control over the encryption options. The disadvantage is that you need to either run {{ic|mount}} as root, or add an entry to {{ic|/etc/fstab}} for each eCryptfs directory so users can mount them.
  
The above "''eCryptfs and $HOME''" article uses a shell init file to mount the home directory. The same can be done using [[pam_mount]] with the added benefit that home is un-mounted when all sessions are logged out. Add the following lines to {{ic|/etc/security/pam_mount.conf.xml}}:
+
First create your private directories. In this example, we use the same ones as the previous section:
 +
$ mkdir -m 700 ~/.secret
 +
$ mkdir -m 500 ~/secret
 +
 
 +
To summarize:
 +
* Actual encrypted data will be stored in the lower {{ic|~/.secret}} directory
 +
* While mounted, decrypted data will be available in {{ic|~/secret}} directory
 +
** While not mounted nothing can be written to this directory
 +
** While mounted it has the same permissions as the lower directory
 +
 
 +
Now, supposed you have created the [[#Manual_setup|wrapped keyphrase]] above, you need to insert the encryption key once to the root user's keyring:
 +
# printf "%s" "Arch" | ecryptfs-insert-wrapped-passphrase-into-keyring /home/''username''/.ecryptfs/wrapped-passphrase -
 +
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring
 +
 
 +
so that the followng mount command succeeds:
 +
# mount -i -t ecryptfs ~/.secret ~/secret -o ecryptfs_sig=7c5d3dd8a1b49db0,ecryptfs_fnek_sig=7c5d3dd8a1b49db0,ecryptfs_cipher=aes,ecryptfs_key_bytes=32,ecryptfs_unlink_sigs
 +
* {{ic|ecryptfs_sig}} sets the data passphrase key signature.
 +
* {{ic|ecryptfs_fnek_sig}} sets the filename passphrase key signature; you can omit this option if you do not want to encrypt filenames.
 +
* {{ic|ecryptfs_key_bytes}} can be 16, 24, or 32 to change the encryption key size.
 +
* {{ic|ecryptfs_unlink_sigs}} will remove the passphrase(s) from the keyring when you unmount, so you have to add the passphrase(s) back again in order to re-mount the filesystem.
 +
* There are a few other options listed in the {{ic|ecryptfs}} man page.
 +
 
 +
{{Tip|There is a {{ic|mount.ecryptfs}} tool, which you can run as root to enter the mount settings interactively. Once you've used it to mount eCryptfs, you can check {{ic|/etc/mtab}} to find out what options it used.}}
 +
 
 +
Once you've chosen the right mount options, you can add an entry to {{ic|/etc/fstab}} so regular users can mount eCryptfs on these directories. Copy the mount options to a new {{ic|/etc/fstab}} entry and add the options {{ic|user}} and {{ic|noauto}}. The full entry will look similar to (bold entries added):
 +
 
 +
{{hc|/etc/fstab|2=/home/''username''/.secret /home/''username''/secret ecryptfs '''noauto''','''user''',ecryptfs_sig=7c5d3dd8a1b49db0,ecryptfs_fnek_sig=7c5d3dd8a1b49db0,ecryptfs_cipher=aes,ecryptfs_key_bytes=32,ecryptfs_unlink_sigs '''0 0'''}}
 +
 
 +
* The {{ic|noauto}} option is important, because otherwise systemd will error trying to mount the entry directly on boot.
 +
* The {{ic|user}} option enables to mount the directory as a user.
 +
** The user mount will default to option {{ic|noexec}}. If you want to have at least executable files in your private directory, you can add {{ic|exec}} to the fstab options.
 +
 
 +
The setup is now complete and the directory should be mountable by the user.
 +
 
 +
===== Mounting =====
 +
 
 +
To mount the encrypted directory as the user, the passphrase must be unwrapped and made available in the user's keyring. Following above section example:
 +
$ ecryptfs-insert-wrapped-passphrase-into-keyring /home/''username''/.ecryptfs/wrapped-passphrase
 +
Passphrase:
 +
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring
 +
 
 +
Now the directory can be mounted without the mount helper questions: 
 +
$ mount -i /home/''username''/secret
 +
 
 +
and files be placed into the {{ic|secret}} directory. The above two steps are necessary every time to mount the directory manually.
 +
 
 +
To unmount it again:
 +
 
 +
$ umount /home/''username''/secret
 +
 
 +
To finalize, the preliminary passphrase to wrap the encryption passphrase may be changed:
 +
$ ecryptfs-rewrap-passphrase /home/''username''/.ecryptfs/wrapped-passphrase
 +
Old wrapping passphrase:
 +
New wrapping passphrase:
 +
New wrapping passphrase (again):
 +
 
 +
The un-mounting should also clear the keyring, to check the user's keyring or clear it manually: 
 +
$ keyctl list @u
 +
$ keyctl clear @u
 +
 
 +
{{Note|One should remember that {{ic|/etc/fstab}} is for system-wide partitions only and should not generally be used for user-specific mounts}}
 +
 
 +
===== Auto-mounting =====
 +
 
 +
Different methods can be employed to automount the previously defined user-mount in {{ic|/etc/fstab}} on login. As a first general step, follow point (1) and (2) of [[#Auto-mounting]].
 +
 
 +
Then, if you login via console, a simple way is to specify the [[#Mounting_2|user-interactive]] ''mount'' and ''umount'' in the user's shell configuration files, for example [[Bash#Configuration files]].
 +
 
 +
{{Accuracy|<br>- the section should be more generic than it is now<br>
 +
- the described method does not work for users, for encountered problems:|section=#Automounting}}
 +
 
 +
Another method is to automount the eCryptfs directory on user login using [[pam_mount]]. To configure this method, add the following lines to {{ic|/etc/security/pam_mount.conf.xml}}:
 
   
 
   
 
  <luserconf name=".pam_mount.conf.xml" />
 
  <luserconf name=".pam_mount.conf.xml" />
Line 181: Line 303:
 
Please prefer writing manually these lines instead of simply copy/pasting them (especially the lclmount line), otherwise you might get some corrupted characters.
 
Please prefer writing manually these lines instead of simply copy/pasting them (especially the lclmount line), otherwise you might get some corrupted characters.
 
Explanation:
 
Explanation:
* the first line indicates where the user-based configuration file is located (here {{ic|~/.pam_mount.conf.xml}}) ;
+
* the first line indicates where the user-based configuration file is located (here {{ic|~/.pam_mount.conf.xml}})
* the second line overwrites the default required mount options which are unnecessary ("nosuid,nodev") ;
+
* the second line overwrites the default required mount options which are unnecessary ("nosuid,nodev")
 
* the last line indicates which mount command to run (eCryptfs needs the {{Ic|-i}} switch).
 
* the last line indicates which mount command to run (eCryptfs needs the {{Ic|-i}} switch).
  
 
Then set the volume definition, preferably to {{ic|~/.pam_mount.conf.xml}}:
 
Then set the volume definition, preferably to {{ic|~/.pam_mount.conf.xml}}:
 
  <pam_mount>
 
  <pam_mount>
     <volume noroot="1" fstype="ecryptfs" path="/home/.ecryptfs/user/.Private/" mountpoint="/home/user/"/>
+
     <volume noroot="1" fstype="ecryptfs" path="/home/user/.secret/" mountpoint="/home/user/secret/"/>
 
  </pam_mount>
 
  </pam_mount>
  
"noroot" is needed because the encryption key will be added to the user's keyring
+
"noroot" is needed because the encryption key will be added to the user's keyring.
  
Finally, edit {{ic|/etc/pam.d/login}} as described in [[pam_mount]]'s article.
+
Finally, edit {{ic|/etc/pam.d/login}} as described in the [[pam_mount]] article.
  
==== Optional step ====
+
====== Optional step ======
  
 
To avoid wasting time needlessly unwrapping the passphrase you can create a script that will check ''pmvarrun'' to see the number of open sessions:
 
To avoid wasting time needlessly unwrapping the passphrase you can create a script that will check ''pmvarrun'' to see the number of open sessions:
Line 208: Line 330:
 
The article suggests adding these to {{ic|/etc/pam.d/login}}, but the changes will need to be added to all other places you login, such as {{ic|/etc/pam.d/kde}}.
 
The article suggests adding these to {{ic|/etc/pam.d/login}}, but the changes will need to be added to all other places you login, such as {{ic|/etc/pam.d/kde}}.
  
=== PAM mount by eCryptfs module ===
+
== Usage ==
To use the eCryptfs PAM module it self for mounting you should know it depends on some hard-coded Ubuntu defaults. Like using AES cipher with a 16 byte key. As described in this BBS post [https://bbs.archlinux.org/viewtopic.php?pid=727422#p727422] you have to do the following steps:
+
  
1) For your understanding and preparation, read the guide mentioned above. [http://sysphere.org/~anrxc/j/articles/ecryptfs/index.html]
+
{{Expansion|Content that still may to be covered:
 +
- point to the above "Setup & Mounting" section for how to mount and unmount [this section here will cover all other (i.e. setup-independent) usage info]<br>
 +
- reference ecryptfs tools not used/mentioned in the prior sections (e.g. with a short link to the online manpages and mention of the other tools usage, as it seems useful (not covered yet are, e.g. ecryptfs-stat, ecryptfs-find, ecryptfs-rewrite-file.) <br>
 +
- mention the options to share an encrypted folder between users and to place non-encrypted files or folders in the encrypted container ("pass-through")
 +
(references for the points: [https://wiki.archlinux.org/index.php?title&61;Talk:ECryptfs&oldid&61;347981] and (maybe) [https://wiki.archlinux.org/index.php?title&61;ECryptfs&oldid&61;291214])
 +
|section=Major_restructuring/rewrite}}
  
2)  Install [https://www.archlinux.org/packages/core/x86_64/keyutils/ keyutils] and [https://www.archlinux.org/packages/community/x86_64/ecryptfs-utils/ ecryptfs-utils] from the official Repos.
+
=== Symlinking into the encrypted directory ===
  
'''[Do the following steps as root!]'''
+
Besides using your private directory as storage for sensitive files, and private data, you can also use it to protect application data. [[Firefox]] for example has an internal password manager, but the browsing history and cache can also be sensitive. Protecting it is easy:
 +
  $ mv ~/.mozilla ~/Private/mozilla
 +
  $ ln -s ~/Private/mozilla ~/.mozilla
  
3) Make a "ecryptfs" Group:
+
=== Removal of encryption ===
groupadd ecryptfs
+
4) Add the user to it:
+
usermod -aG ecryptfs user
+
5) Load the ecryptfs module
+
modprobe ecryptfs
+
6) Change your /etc/pam.d/system-auth to look something like this (lines to add are bold):
+
#%PAM-1.0
+
+
auth      required  pam_env.so
+
auth      required  pam_unix.so    try_first_pass nullok
+
'''auth      required  pam_ecryptfs.so unwrap'''
+
auth      optional  pam_permit.so
+
+
account  required  pam_unix.so
+
account  optional  pam_permit.so
+
account  required  pam_time.so
+
+
'''password  required  pam_ecryptfs.so'''
+
password  required  pam_unix.so    try_first_pass nullok sha512 shadow
+
password  optional  pam_permit.so
+
+
'''session  required  pam_ecryptfs.so unwrap'''
+
session  required  pam_limits.so
+
session  required  pam_env.so
+
session  required  pam_unix.so
+
session  optional  pam_permit.so
+
  
 +
There are no special steps involved, if you want to remove your private directory. Make sure it is un-mounted and delete the respective lower directory (e.g. {{ic|~/.Private}}), along with all the encrypted files. After also removing the related encryption signatures and configuration in {{ic|~/.ecryptfs}}, all is gone.
  
6a) When using [[GDM]] < 3.2 to log in, edit /etc/pam.d/gdm like this:
+
If you were [[#Using the Ubuntu tools]] to setup a single directory encryption, you can directly follow the steps detailed by:  
#%PAM-1.0
+
auth            requisite      pam_nologin.so
+
auth            required        pam_env.so
+
auth            required        pam_unix.so
+
'''auth            optional        pam_ecryptfs.so unwrap'''
+
auth            optional        pam_gnome_keyring.so
+
account        required        pam_unix.so
+
session        required        pam_limits.so
+
session        required        pam_unix.so
+
'''session        optional        pam_ecryptfs.so unwrap'''
+
session        optional        pam_gnome_keyring.so auto_start
+
password        required        pam_unix.so
+
'''password        optional        pam_ecryptfs.so'''
+
  
6b) For [[GDM]] >= 3.2, make the following changes to /etc/pam.d/gdm-password (thanks to grawity for [https://bbs.archlinux.org/viewtopic.php?pid=998061#p998061 this]):
+
  $ ecryptfs-setup-private --undo
  #%PAM-1.0
+
auth            requisite      pam_nologin.so
+
auth            required        pam_env.so
+
auth            requisite      pam_unix.so nullok
+
'''auth            optional        pam_ecryptfs.so unwrap'''
+
auth            optional        pam_gnome_keyring.so
+
auth            sufficient      pam_succeed_if.so uid >= 1000 quiet
+
auth            required        pam_deny.so
+
account        required        pam_unix.so
+
password        required        pam_unix.so
+
'''password        optional        pam_ecryptfs.so'''
+
session        required        pam_loginuid.so
+
-session        optional        pam_systemd.so
+
session        optional        pam_keyinit.so '''force''' revoke
+
session        required        pam_limits.so
+
session        required        pam_unix.so
+
'''session        optional        pam_ecryptfs.so unwrap'''
+
session        optional        pam_gnome_keyring.so auto_start
+
  
6c) For [[KDM]], make the following changes to /etc/pam.d/kde:
+
and follow the instructions.
  
#%PAM-1.0
+
=== Backup ===
auth            required        pam_unix.so
+
'''auth            optional        pam_ecryptfs.so unwrap'''
+
auth            required        pam_nologin.so
+
account        required        pam_unix.so
+
'''password        optional        pam_ecryptfs.so'''
+
password        required        pam_unix.so
+
session        required        pam_unix.so
+
'''session        optional        pam_ecryptfs.so unwrap'''
+
session        required        pam_limits.so
+
  
6d) For [[LXDM]], make the following changes to /etc/pam.d/lxdm:
+
If you want to move a file out of the private directory just move it to the new destination while {{ic|~/Private}} is mounted.  
  
#%PAM-1.0
+
With eCryptfs the cryptographic metadata is stored in the header of the files. Setup variants explained in this article separate the directory with encrypted data from the mount point. The unencrypted mount point is fully transparent and available for a backup. Obviously this has to be considered for automated backups, if one has to avoid leaking sensitive unencrypted data into a backup.  
auth            requisite      pam_nologin.so
+
auth            required        pam_env.so
+
auth            required        pam_unix.so
+
'''auth            optional        pam_ecryptfs.so unwrap'''
+
account        required        pam_unix.so
+
session        required        pam_limits.so
+
session        required        pam_unix.so
+
'''session        optional        pam_ecryptfs.so unwrap'''
+
password        required        pam_unix.so
+
'''password        optional        pam_ecryptfs.so'''
+
  
6e) For [[LightDM]], make the following changes to /etc/pam.d/lightdm
+
You can do backups, or incremental backups, of the encrypted (e.g. {{ic|~/.Private}}) directory, treating it like any other directory.
  
#%PAM-1.0
+
Further points to note:
auth      required pam_nologin.so
+
auth      required pam_env.so
+
auth      required pam_unix.so
+
'''auth      optional pam_ecryptfs.so unwrap'''
+
account  required pam_unix.so
+
'''password  optional pam_ecryptfs.so'''
+
password  required pam_unix.so
+
session  required pam_unix.so
+
'''session  optional pam_ecryptfs.so unwrap'''
+
  
7) To be able to automatically mount your encrypted home directory on login using SSH, edit /etc/pam.d/sshd:
+
* If you used the Ubuntu tools for [[#Encrypting a home directory]], be aware the location of the lower directory with the encrypted files is ''outside'' the regular user's {{ic|$HOME}} at {{ic|/home/.ecryptfs/$USER/.Private}}.  
#%PAM-1.0
+
#auth          required        pam_securetty.so        #Disable remote root
+
auth            required        pam_unix.so
+
'''auth            optional        pam_ecryptfs.so unwrap'''
+
auth            required        pam_env.so
+
account        required        pam_nologin.so
+
account        required        pam_unix.so
+
account        required        pam_time.so
+
password        required        pam_unix.so
+
password        optional        pam_ecryptfs.so
+
'''session        optional        pam_ecryptfs.so unwrap'''
+
session        required        pam_unix_session.so
+
session        required        pam_limits.so
+
session        optional        pam_ck_connector.so nox11
+
  
8) Using Ubuntu defaults
+
* It should be ensured to include the eCryptfs setup files (located in {{ic|~/.ecryptfs}} usually) into the regular or a separate backup.
  
There's a method to automatically setup your HOME with AES and a 16 byte key. You could execute (it can take some while, it automatically encrypts your home files)
+
* If you use special filesystem mount options, for example {{ic|ecryptfs_xattr}}, do extra checks on restore integrity.
    ecryptfs-migrate-home -u user
+
  
...and follow the on screen instructions (Delete backup afterwards (/home/user.XXXXX) / Record the passphrase generated by ecryptfs -> ecryptfs-unwrap-passphrase / ...)
+
== See Also ==
  
9) Log in and check if everything worked correctly.
+
* [http://ecryptfs.org/documentation.html eCryptfs] - Manpages and project home
 
+
* [https://defuse.ca/audits/ecryptfs.htm Security audit] of eCryptfs by Taylor Hornby (January 22, 2014).
This is a working solution and ecryptfs is exactly used as in Ubuntu (10.04/10.10) - and is easy to set up.
+
* [http://sysphere.org/~anrxc/j/articles/ecryptfs/index.html eCryptfs and $HOME] by Adrian C. (anrxc) - Article with installation instructions and discussion of eCryptfs usage
Besides this, it has the advantage of auto-unmount at log-out, which shell profile files (ie. ~/.bash_logout) could have trouble doing, because there could still be open file-descriptors by the shell at the time of umount. To encrypt swap see: [[System_Encryption_with_LUKS#Encrypting_the_Swap_partition]] (some of the tools provided by ecryptfs, such as ecryptfs-setup-swap, only work in ubuntu).
+
* [http://www.chromium.org/chromium-os/chromiumos-design-docs/protecting-cached-user-data Chromium data protection] (November 2009) - Design document detailing encryption options for Chromium OS, including explanation on its eCryptfs usage
 
+
* [http://ecryptfs.sourceforge.net/ecryptfs.pdf eCryptfs design] by Michael Halcrow (May 2005) - Original design document detailing and discussing eCryptfs
== ecryptfs-simple ==
+
Use [http://xyne.archlinux.ca/projects/ecryptfs-simple/ ecryptfs-simple] if you just want to use eCryptfs to mount arbitrary directories the way you can with EncFS. ecryptfs-simple does not require root privileges or entries in fstab, nor is it limited to hard-coded directories such as ~/.Private. The package is available in the [https://aur.archlinux.org/packages.php?ID=59612 AUR] and in [http://xyne.archlinux.ca/repos/ Xyne's repos].
+
 
+
As the name implies, usage is simple:
+
# simple mounting
+
ecryptfs-simple /path/to/foo /path/to/bar
+
 
+
# automatic mounting: prompts for options on the first mount of a directory then reloads them next time
+
ecryptfs-simple -a /path/to/foo /path/to/bar
+
 
+
# unmounting by source directory
+
ecryptfs-simple -u /path/to/foo
+
 
+
# unmounting by mountpoint
+
ecryptfs-simple -u /path/to/bar
+

Latest revision as of 12:08, 29 May 2016

Related articles

This article describes basic usage of eCryptfs. It guides you through the process of creating a private and secure encrypted directory within your $HOME directory to store sensitive files and private data.

In implementation eCryptfs differs from dm-crypt, which provides a block device encryption layer, while eCryptfs is an actual file-system – a stacked cryptographic file system. For comparison of the two you can refer to this table and the Disk encryption#Comparison table. One distinguished feature is that the encryption is stacked on an existing filesystem; eCryptfs can be mounted onto any single existing directory and does not require a separate partition (or size pre-allocation).

Basics

As mentioned in the summary eCryptfs does not require special on-disk storage allocation effort, such as a separate partition or pre-allocated space. Instead, you can mount eCryptfs on top of any single directory to protect it. That includes, for example, a user's entire $HOME directory or single dedicated directories within it. All cryptographic metadata is stored in the headers of files, so encrypted data can be easily moved, stored for backup and recovered. There are other advantages, but there are also drawbacks, for instance eCryptfs is not suitable for encrypting complete partitions which also means you cannot protect swap space with it (but you can, of course, combine it with Dm-crypt/Swap encryption). If you are just starting to set up disk encryption, swap encryption and other points to consider are covered in Disk encryption#Preparation.

To familiarize with eCryptfs a few points:

  • As a stacked filesystem, a mounting of an eCryptfs directory refers to mounting a (stacked) encrypted directory to another unencrypted mount point (directory) at Linux kernel runtime.
  • It is possible to share an encrypted directory between users. However, the encryption is linked to one passphrase so this must be shared as well. It is also possible to share a directory with differently encrypted files (different passphrases).
  • A number of eCryptfs acronyms are used throughout the documentation:
    • The encrypted directory is referred to as the lower and the unencrypted as the upper directory throughout the eCryptfs documentation and this article. While not relevant for this article, the "overlay" filesystem introduced with Linux 3.18 uses (and explains) the same upper/lower nomenclatura for the stacking of filesystems.
    • the mount passphrase (or key) is what gives access to the encrypted files, i.e. unlocks the encryption. eCryptfs uses the term wrapped passphrase to refer to the cryptographically secured mount passphrase.
    • a FEFEK refers to a File's Encryption key Encryption Key (see kernel documentation).
    • a FNEK refers to a File Name Encryption Key, a key to (optionally) encrypt the filenames stored in the encrypted directory.

Before using eCryptfs, the following disadvantages should be checked for applicability.

Deficiencies

  • Ease of use
The ecryptfs-utils package provides several different ways of setting up eCryptfs. The high-level "Ubuntu tools" are the easiest to use, but they hard-code the lower directory path and other settings, limiting their usefulness. The package also includes low-level tools which are fully configurable, but they are somewhat more difficult to use compared to alternatives like EncFS.
  • Network storage mounts
eCryptfs has long-standing bugs when used on top of NFS and possibly other networked filesystems. It is always possible to use eCryptfs on a local directory and then copy the encrypted files from the local directory to a network host. However, if you want to set up eCryptfs directly on top of an NFS mount, with no local copy of the files, eCryptfs may crash or behave incorrectly. If in doubt, EncFS may be a better choice in this case.
  • Sparse files
Sparse files written to eCryptfs will produce larger, non-sparse encrypted files in the lower directory. For example, in an eCryptfs directory running truncate -s 1G file.img creates a 1GB encrypted file on the underlying filesystem, with the corresponding resource (disk space, data throughput) requirements. If the same file were created on an unencrypted filesystem or a filesystem using block device encryption, it would only take a few kilobytes.
This should be considered before encrypting large portions of the directory structure, though in most cases the disadvantages will be minor. If you need to use large sparse files, you can work around this issue by putting the sparse files in an unencrypted directory or using block device encryption for them.

Setup & mounting

Before starting, check the eCryptfs documentation. It is distributed with a very good and complete set of manual pages.

eCryptfs has been included in Linux since version 2.6.19. Start by loading the ecryptfs module:

# modprobe ecryptfs
Tip: If you use linux-grsec, auto-loading of cryptographic modules may fail when executing the ecryptfs-mount-private wrapper (as of November 2014). As a work-around, load the mentioned module manually; for example modprobe md5 as root and configure the system to load it at next boot.

To actually mount an eCryptfs filesystem, you need to use userspace tools provided by the package ecryptfs-utils available in the Official repositories. Unfortunately, due to the poor design of these tools, you must choose between three ways of setting up eCryptfs with different tradeoffs:

  1. Use the high-level tools, which set things up automatically but require the lower directory to be ~/.Private/, and allow only one encrypted filesystem per user.
  2. Use ecryptfs-simple, available from AUR, which is an easy way to mount eCryptfs filesystems using any lower directory and upper directory.
  3. #Manual setup, which involves separate steps for loading the passphrase and mounting eCryptfs, but allows complete control over the directories and encryption settings.

High-level tools (hardcoded paths)

Most of the user-friendly convenience tools installed by the ecryptfs-utils package assume a very specific eCryptfs setup, namely the one that is officially used by Ubuntu (where it can be selected as an option during distro installation). Unfortunately, these choices are not just default options but are actually hard-coded in the tools. If this set-up does not suit your needs, then you can not use the convenience tools and will have to follow the steps at #Manual setup instead.

The set-up used by these tools is as follows:

  • each user can have only one encrypted directory that is managed by these tools:
    • either full $HOME directory encryption, or
    • a single encrypted data directory (by default ~/Private/, but this can be customized).
  • the lower directory for each user is always ~/.Private/
    (in the case of full home dir encryption, this will be a symlink to the actual location at /home/.ecryptfs/$USER/.Private/)
  • the encryption options used are:
    • cipher: AES
    • key length: 16 bytes (128 bits)
    • key management scheme: passphrase
    • plaintext passthrough: enabled
  • the configuration / control info for the encrypted directory is stored in a bunch of files at ~/.ecryptfs/:
    (in the case of full home dir encryption, this will be a symlink to the actual location at /home/.ecryptfs/$USER/.ecryptfs/)
    • Private.mnt [plain text file] - contains the path where the upper directory should be mounted (e.g. /home/lucy or /home/lucy/Private)
    • Private.sig [plain text file] - contains the signature used to identify the mount passphrase in the kernel keyring
    • wrapped-passphrase [binary file] - the mount passphrase, encrypted with the login passphrase
    • auto-mount, auto-umount [empty files] - if they exist, the pam_ecryptfs.so module will (assuming it is loaded) automatically mount/unmount this encrypted directory when the user logs in/out

Encrypting a data directory

For a full $HOME directory encryption see #Encrypting a home directory

Before the data directory encryption is setup, decide whether it should later be mounted manually or automatically with the user log-in.

To encrypt a single data directory as a user and mount it manually later, run:

$ ecryptfs-setup-private --nopwcheck --noautomount 

and follow the instructions. The option --nopwcheck enables you to choose a passphrase different to the user login passphrase and the option --noautomount is self-explanatory. So, if you want to setup the encrypted directory automatically on log-in later, just leave out both options right away.

The script will automatically create the ~/.Private/ and ~/.ecryptfs/ directory structures as described in the box above. It will also ask for two passphrases:

login passphrase
This is the password you will have to enter each time you want to mount the encrypted directory. If you want auto-mounting on login to work, it has to be the same password you use to login to your user account.
mount passphrase
This is used to derive the actual file encryption master key. Thus, you should not enter a custom one unless you know what you are doing - instead press Enter to let it auto-generate a secure random one. It will be encrypted using the login passphrase and stored in this encrypted form in ~/.ecryptfs/wrapped-passphrase. Later it will automatically be decrypted ("unwrapped") again in RAM when needed, so you never have to enter it manually. Make sure this file does not get lost, otherwise you can never access your encrypted folder again! You may want to run ecryptfs-unwrap-passphrase to see the mount passphrase in unencrypted form, write it down on a piece of paper, and keep it in a safe (or similar), so you can use it to recover your encrypted data in case the wrapped-passphrase file is accidentally lost/corrupted or in case you forget the login passphrase.

The mount point ("upper directory") for the encrypted folder will be at ~/Private by default, however you can manually change this right after the setup command has finished running, by doing:

$ mv ~/Private /path/to/new/folder
$ echo /path/to/new/folder > ~/.ecryptfs/Private.mnt

To actually use your encrypted folder, you will have to mount it - see #Mounting below.

Encrypting a home directory

The wrapper script ecryptfs-migrate-home will set up an encrypted home directory for a user and take care of migrating any existing files they have in their not yet encrypted home directory.

To run it, the user in question must be logged out and own no processes. The best way to achieve this is to log the user out, log into a console as the root user, and check that ps -U username returns no output. You also need to ensure that you have rsync and lsof installed. Once the prerequisites have been met, run:

# modprobe ecryptfs
# ecryptfs-migrate-home -u username

and follow the instructions. After the wrapper script is complete, follow the instructions for auto-mounting - see #Auto-mounting below. It is imperative that the user logs in before the next reboot, to complete the process.

Once everything is working, the unencrypted backup of the users home directory, which is saved to /home/username.random_characters, can and should be deleted.

Mounting

Manually

Executing the wrapper

$ ecryptfs-mount-private 

and entering the passphrase is all needed to mount the encrypted directory to the above described upper directory ~/Private.

Likewise, executing

$ ecryptfs-umount-private

will unmount it again.

Tip: If it is not required to access the private data permanently during a user session, maybe define an alias to speed the manual step up.

The tools include another script that can be very handy to access an encrypted .Private data or home directory. Executing ecryptfs-recover-private as root will search the system (or an optional specific path) for the directory, interactively query the passphrase for it and mount the directory. It can, for example, be used from a live-CD or different system to access the encrypted data in case of a recovery. Note that if booting from an Arch Linux ISO you must first install the ecryptfs-utils to it. Further, it will only be able to mount .Private directories created with the Ubuntu tools.

Auto-mounting

The default way to auto-mount an encrypted directory is via PAM. See man pam_ecryptfs and - for more details - 'PAM MODULE' in:

/usr/share/doc/ecryptfs-utils/README

For auto-mounting it is required that the passphrase to access the encrypted directory is synchronised with the user log-in.

The following steps set it up:

1. Check if ~/.ecryptfs/auto-mount, ~/.ecryptfs/auto-umount and ~/.ecryptfs/wrapped-passphrase exist (these are automatically created by ecryptfs-setup-private).

2. Add ecryptfs to the pam-stack exactly as following to allow transparent unwrapping of the passphrase on login:

Open /etc/pam.d/system-auth and after the line containing auth required pam_unix.so add:

auth    required    pam_ecryptfs.so unwrap

Next, above the line containing password required pam_unix.so insert:

password    optional    pam_ecryptfs.so

And finally, after the line session required pam_unix.so add:

session    optional    pam_ecryptfs.so unwrap

3. Re-login and check output of mount which should now contain a mountpoint, e.g.:

/home/$USER/.Private on /home/$USER/Private type ecryptfs (...)

for the user's encrypted directory. It should be perfectly readable at ~$HOME/Private/.

The latter should be automatically unmounted and made unavailable when the user logs off.

Warning: Unfortunately the automatic unmounting is susceptible to break with systemd and bugs are filed against it.[1] [2] [3] [4] If you experience this problem, you can test it by commenting out -session optional pam_systemd.so in /etc/pam.d/system-login. However, this is no solution because commenting out will break other systemd functionalities.

ecryptfs-simple

Use ecryptfs-simple if you just want to use eCryptfs to mount arbitrary directories the way you can with EncFS. ecryptfs-simple does not require root privileges or entries in /etc/fstab, nor is it limited to hard-coded directories such as ~/.Private. The package is available to be installed as ecryptfs-simpleAUR and from Xyne's repos.

As the name implies, usage is simple:

# simple mounting
ecryptfs-simple /path/to/foo /path/to/bar
# automatic mounting: prompts for options on the first mount of a directory then reloads them next time
ecryptfs-simple -a /path/to/foo /path/to/bar
# unmounting by source directory
ecryptfs-simple -u /path/to/foo
# unmounting by mountpoint
ecryptfs-simple -u /path/to/bar

Manual setup

The following details instructions to set up eCryptfs encrypted directories manually. This involves two steps. First, the passphrase is processed and loaded into the kernel keyring. Second, the filesystem is actually mounted using the key from the keyring.

There are two ways to add the passphrase to the kernel keyring in the first step. The simpler option is ecryptfs-add-passphrase, which uses a single passphrase to encrypt the files. The disadvantage is that you cannot change the passphrase later. It works like this:

$ ecryptfs-add-passphrase
Passphrase: 
Inserted auth tok with sig [78c6f0645fe62da0] into the user session keyring

You can also pipe a passphrase into ecryptfs-add-passphrase -. Keep in mind that if you leave your passphrase in a file, it will usually defeat the purpose of using encryption.

As an alternative to a plain passphrase, you can use a "wrapped passphrase", where the files are encrypted using a randomly generated key, which is itself encrypted with your passphrase and stored in a file. In this case, you can change your passphrase by unwrapping the key file with your old passphrase and rewrapping it using your new passphrase.

In the following we do a generation similar to the source and then use ecryptfs-wrap-passphrase to wrap it with the password ("Arch") to ~/.ecryptfs/wrapped-passphrase:

$ printf "%s\n%s" $(od -x -N 100 --width=30 /dev/random | head -n 1 | sed "s/^0000000//" | sed "s/\s*//g") "Arch" | ecryptfs-wrap-passphrase /home/username/.ecryptfs/wrapped-passphrase

Next, we can enter our passphrase "Arch" to load the key into the keyring:

$ printf "%s" "Arch" | ecryptfs-insert-wrapped-passphrase-into-keyring /home/username/.ecryptfs/wrapped-passphrase -
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring

In either case, when you successfully add the passphrase to the kernel keyring, you will get a "key signature" like 78c6f0645fe62da0 which you will need in the next step.

There are two different ways of manually mounting eCryptfs, described in the following sections. The first way, using mount.ecryptfs_private, can be run as a regular user and involves setting up some configuration files. This method does not allow you to change the encryption settings, such as key size. The second way is to use a raw mount command, which gives you complete control over all settings, but requires you to either run it as root, or add an entry to /etc/fstab which lets a user mount eCryptfs.

Tip: The following examples use an encrypted directory (.secret) different to the default, hard-coded .Private in the Ubuntu tools. This is on purpose to avoid problems of erroneous #Auto-mounting when the system has PAM setup for it, as well as problems with other tools using the hard-coded defaults.

With configuration files

This method involves running mount.ecryptfs_private from the ecryptfs-utils package, after first loading your passphrase. This binary requires no root privileges to work by default.

First choose a name for your configuration files in ~/.ecryptfs and decide on the lower and upper directories. In this example we use secret for the configuration files, put in encrypted data in ~/.secret, and mount the decrypted files at ~/secret. Create the required directories:

$ mkdir ~/.secret ~/secret ~/.ecryptfs

Now specify the directories in ~/.ecryptfs/secret.conf, using full paths. Its format looks like the one in /etc/fstab without the mount options:

$ echo "$HOME/.secret $HOME/secret ecryptfs" > ~/.ecryptfs/secret.conf

Write the key signature you got from ecryptfs-add-passphrase or ecryptfs-insert-wrapped-passphrase-into-keyring (see above) into ~/.ecryptfs/secret.sig:

$ echo 78c6f0645fe62da0 > ~/.ecryptfs/secret.sig

If you also want to enable filename encryption, add a second passphrase to the keyring (or reuse the first passphrase) and append its key signature to ~/.ecryptfs/secret.sig:

 $ echo 326a6d3e2a5d444a >> ~/.ecryptfs/secret.sig

Finally, mount ~/.secret on ~/secret:

$ mount.ecryptfs_private secret

When you're done, unmount it:

$ umount.ecryptfs_private secret

Raw mount command

By running the actual mount command manually, you get complete control over the encryption options. The disadvantage is that you need to either run mount as root, or add an entry to /etc/fstab for each eCryptfs directory so users can mount them.

First create your private directories. In this example, we use the same ones as the previous section:

$ mkdir -m 700 ~/.secret
$ mkdir -m 500 ~/secret

To summarize:

  • Actual encrypted data will be stored in the lower ~/.secret directory
  • While mounted, decrypted data will be available in ~/secret directory
    • While not mounted nothing can be written to this directory
    • While mounted it has the same permissions as the lower directory

Now, supposed you have created the wrapped keyphrase above, you need to insert the encryption key once to the root user's keyring:

# printf "%s" "Arch" | ecryptfs-insert-wrapped-passphrase-into-keyring /home/username/.ecryptfs/wrapped-passphrase -
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring

so that the followng mount command succeeds:

# mount -i -t ecryptfs ~/.secret ~/secret -o ecryptfs_sig=7c5d3dd8a1b49db0,ecryptfs_fnek_sig=7c5d3dd8a1b49db0,ecryptfs_cipher=aes,ecryptfs_key_bytes=32,ecryptfs_unlink_sigs
  • ecryptfs_sig sets the data passphrase key signature.
  • ecryptfs_fnek_sig sets the filename passphrase key signature; you can omit this option if you do not want to encrypt filenames.
  • ecryptfs_key_bytes can be 16, 24, or 32 to change the encryption key size.
  • ecryptfs_unlink_sigs will remove the passphrase(s) from the keyring when you unmount, so you have to add the passphrase(s) back again in order to re-mount the filesystem.
  • There are a few other options listed in the ecryptfs man page.
Tip: There is a mount.ecryptfs tool, which you can run as root to enter the mount settings interactively. Once you've used it to mount eCryptfs, you can check /etc/mtab to find out what options it used.

Once you've chosen the right mount options, you can add an entry to /etc/fstab so regular users can mount eCryptfs on these directories. Copy the mount options to a new /etc/fstab entry and add the options user and noauto. The full entry will look similar to (bold entries added):

/etc/fstab
/home/username/.secret /home/username/secret ecryptfs noauto,user,ecryptfs_sig=7c5d3dd8a1b49db0,ecryptfs_fnek_sig=7c5d3dd8a1b49db0,ecryptfs_cipher=aes,ecryptfs_key_bytes=32,ecryptfs_unlink_sigs 0 0
  • The noauto option is important, because otherwise systemd will error trying to mount the entry directly on boot.
  • The user option enables to mount the directory as a user.
    • The user mount will default to option noexec. If you want to have at least executable files in your private directory, you can add exec to the fstab options.

The setup is now complete and the directory should be mountable by the user.

Mounting

To mount the encrypted directory as the user, the passphrase must be unwrapped and made available in the user's keyring. Following above section example:

$ ecryptfs-insert-wrapped-passphrase-into-keyring /home/username/.ecryptfs/wrapped-passphrase
Passphrase: 
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring 

Now the directory can be mounted without the mount helper questions:

$ mount -i /home/username/secret

and files be placed into the secret directory. The above two steps are necessary every time to mount the directory manually.

To unmount it again:

$ umount /home/username/secret

To finalize, the preliminary passphrase to wrap the encryption passphrase may be changed:

$ ecryptfs-rewrap-passphrase /home/username/.ecryptfs/wrapped-passphrase
Old wrapping passphrase: 
New wrapping passphrase: 
New wrapping passphrase (again):

The un-mounting should also clear the keyring, to check the user's keyring or clear it manually:

$ keyctl list @u
$ keyctl clear @u
Note: One should remember that /etc/fstab is for system-wide partitions only and should not generally be used for user-specific mounts
Auto-mounting

Different methods can be employed to automount the previously defined user-mount in /etc/fstab on login. As a first general step, follow point (1) and (2) of #Auto-mounting.

Then, if you login via console, a simple way is to specify the user-interactive mount and umount in the user's shell configuration files, for example Bash#Configuration files.

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason:
- the section should be more generic than it is now
- the described method does not work for users, for encountered problems: (Discuss in Talk:ECryptfs##Automounting)

Another method is to automount the eCryptfs directory on user login using pam_mount. To configure this method, add the following lines to /etc/security/pam_mount.conf.xml:

<luserconf name=".pam_mount.conf.xml" />
<mntoptions require="" /> 
<lclmount>mount -i %(VOLUME) "%(before=\"-o\" OPTIONS)"</lclmount> 

Please prefer writing manually these lines instead of simply copy/pasting them (especially the lclmount line), otherwise you might get some corrupted characters. Explanation:

  • the first line indicates where the user-based configuration file is located (here ~/.pam_mount.conf.xml)
  • the second line overwrites the default required mount options which are unnecessary ("nosuid,nodev")
  • the last line indicates which mount command to run (eCryptfs needs the -i switch).

Then set the volume definition, preferably to ~/.pam_mount.conf.xml:

<pam_mount>
    <volume noroot="1" fstype="ecryptfs" path="/home/user/.secret/" mountpoint="/home/user/secret/"/>
</pam_mount>

"noroot" is needed because the encryption key will be added to the user's keyring.

Finally, edit /etc/pam.d/login as described in the pam_mount article.

Optional step

To avoid wasting time needlessly unwrapping the passphrase you can create a script that will check pmvarrun to see the number of open sessions:

#!/bin/sh
#
#    /usr/local/bin/doecryptfs

exit $(/usr/sbin/pmvarrun -u$PAM_USER -o0)

With the following line added before the eCryptfs unwrap module in your PAM stack:

auth    [success=ignore default=1]    pam_exec.so     quiet /usr/local/bin/doecryptfs
auth    required                      pam_ecryptfs.so unwrap

The article suggests adding these to /etc/pam.d/login, but the changes will need to be added to all other places you login, such as /etc/pam.d/kde.

Usage

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Content that still may to be covered:

- point to the above "Setup & Mounting" section for how to mount and unmount [this section here will cover all other (i.e. setup-independent) usage info]
- reference ecryptfs tools not used/mentioned in the prior sections (e.g. with a short link to the online manpages and mention of the other tools usage, as it seems useful (not covered yet are, e.g. ecryptfs-stat, ecryptfs-find, ecryptfs-rewrite-file.)
- mention the options to share an encrypted folder between users and to place non-encrypted files or folders in the encrypted container ("pass-through") (references for the points: [5] and (maybe) [6])

(Discuss in Talk:ECryptfs#Major_restructuring/rewrite)

Symlinking into the encrypted directory

Besides using your private directory as storage for sensitive files, and private data, you can also use it to protect application data. Firefox for example has an internal password manager, but the browsing history and cache can also be sensitive. Protecting it is easy:

 $ mv ~/.mozilla ~/Private/mozilla
 $ ln -s ~/Private/mozilla ~/.mozilla

Removal of encryption

There are no special steps involved, if you want to remove your private directory. Make sure it is un-mounted and delete the respective lower directory (e.g. ~/.Private), along with all the encrypted files. After also removing the related encryption signatures and configuration in ~/.ecryptfs, all is gone.

If you were #Using the Ubuntu tools to setup a single directory encryption, you can directly follow the steps detailed by:

$ ecryptfs-setup-private --undo

and follow the instructions.

Backup

If you want to move a file out of the private directory just move it to the new destination while ~/Private is mounted.

With eCryptfs the cryptographic metadata is stored in the header of the files. Setup variants explained in this article separate the directory with encrypted data from the mount point. The unencrypted mount point is fully transparent and available for a backup. Obviously this has to be considered for automated backups, if one has to avoid leaking sensitive unencrypted data into a backup.

You can do backups, or incremental backups, of the encrypted (e.g. ~/.Private) directory, treating it like any other directory.

Further points to note:

  • If you used the Ubuntu tools for #Encrypting a home directory, be aware the location of the lower directory with the encrypted files is outside the regular user's $HOME at /home/.ecryptfs/$USER/.Private.
  • It should be ensured to include the eCryptfs setup files (located in ~/.ecryptfs usually) into the regular or a separate backup.
  • If you use special filesystem mount options, for example ecryptfs_xattr, do extra checks on restore integrity.

See Also

  • eCryptfs - Manpages and project home
  • Security audit of eCryptfs by Taylor Hornby (January 22, 2014).
  • eCryptfs and $HOME by Adrian C. (anrxc) - Article with installation instructions and discussion of eCryptfs usage
  • Chromium data protection (November 2009) - Design document detailing encryption options for Chromium OS, including explanation on its eCryptfs usage
  • eCryptfs design by Michael Halcrow (May 2005) - Original design document detailing and discussing eCryptfs