From ArchWiki
Revision as of 20:13, 3 October 2011 by Evilandi666 (talk | contribs) (You forgot to bold "force" which is the important part, it does not work without it on gdm 3.2 ;))
Jump to navigation Jump to search

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی


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, where you can store all your sensitive files and private data. If you are wondering "Why should I use encryption?" then start with the first section of the dm-crypt article, which answers some basic questions on theory and security.

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 to be exact. For comparison of the two you can refer to this table .

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 i.e. 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).


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:

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.

Login password

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 for more information.


eCryptfs is a part of Linux since version 2.6.19. But to work with it you will need the userspace tools provided by Template:Package AUR (available in the AUR).

Once you install those packages you can load the ecryptfs module and continue with the setup:

# modprobe ecryptfs

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.

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.


First create your private directories, in this example we will call them exactly that: Private

$ su -
# mkdir -m 700 /home/username/.Private
# mkdir -m 500 /home/username/Private
# chown username:username /home/username/{.Private,Private}

Let's summarize

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

# 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:

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 passphrase is your mount passphrase which will be salted, hashed and loaded into the kernel keyring.
    • 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 Template:Filename.

Since our later goal is to be able to mount without root priviledges, we will now move the eCryptfs configuration directory to your own home and transfer the ownership to you:

# 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. Before you do anything else you should inspect your Template:Filename file, the ecryptfs entry in particular – we will discuss the importance of it a few lines below.

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 – encrypted. That was cool you say, but how do I get them back... and that brings us to:


When ever 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. First solution is that you provide all the options to the mount command (this is where the mtab line comes in) except for your passphrase for which you will be prompted:

$ sudo mount -t ecryptfs /home/username/.Private /home/username/Private -o ecryptfs_cipher=aes,ecryptfs_key_bytes=16,key=passphrase

Second (and recommended) solution is to create an entry in the Template:Filename file for this mount point:

# eCryptfs mount points
/home/username/.Private /home/username/Private ecryptfs rw,user,noauto,ecryptfs_sig=XY,ecryptfs_cipher=aes,ecryptfs_key_bytes=16,ecrypfs_unlink_sigs 0 0


Let's summarize

  • 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)
  • Notice the ecryptfs_sig option, replace XY with your own key signature (as seen in the mtab line earlier and in Template:Filename)
  • 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:

When the key is inserted you can mount the directory:

$ ecryptfs-add-passphrase
  Passphrase: ThisIsAVeryWeakPassphrase

$ mount -i /home/username/Private

You will notice that we used the Template:Codeline option this time. It disables invoking the mount helper. Speaking of which, using Template:Codeline 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.

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:

$ keyctl list @u
$ keyctl clear @u


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


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.


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.

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.


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

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.

Article: eCryptfs and $HOME by Adrian C. (anrxc).

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 here, they could help a lot as you're coming up with your own strategy.

PAM Mount

Warning: As of March 28, 2011 I tested this several times, this does not work anymore - seems that ecryptfs/pam-mount had some changes. PAM fails to mount your $Home at Login. See new method below!

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. As eCryptfs needs the Template:Codeline switch, the lclmount setting will need to be changed. I use the following in Template:Filename:

<lclmount>mount -i %(VOLUME) "%(before=\"-o\" OPTIONS)"</lclmount>

Remember to also set the volume definition (preferably to Template:Filename and uncomment luserconf).

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

noroot is needed (at least in my configuration) because the encryption key will be added to the user's keyring.

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

#    /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]     quiet /usr/local/bin/doecryptfs
auth    required             unwrap

The article suggests adding these to Template:Filename, but the changes will need to be added to all other places you login, such as Template:Filename.

PAM Mount [New Method]

As descried here [1] you have to do the following steps:

1) For your understanding and preparation, read the guide mentioned above. [2]

2) Install keyutils, and ecryptfs-utils and pam_mount from AUR

[Do the following steps as root!]

3) Make a "ecryptfs" Group:

groupadd ecryptfs

4) Add the user to it:

usermod -aG ecryptfs user

5) Load the ecryptfs module

modprobe ecryptfs

5) Change your /etc/pam.d/login to look something like this (lines to add are bold):

auth            required
auth            requisite
auth            required nullok
auth            optional unwrap
auth            required onerr=succeed file=/var/log/faillog
# use this to lockout accounts for 10 minutes after 3 failed attempts
#auth           required deny=2 unlock_time=600 onerr=succeed file=/var/log/faillog
account         required
account         required
account         required
#password       required difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
password        optional
#password       required md5 shadow use_authtok
session         required
session         optional unwrap
session         required
session         required
session         required
session         optional dir=/var/spool/mail standard
session         optional

6a) When using GDM < 3.2 to log in, edit /etc/pam.d/gdm like this:

auth            requisite
auth            required
auth            required
auth            optional unwrap
auth            optional
account         required
session         required
session         required
session         optional unwrap
session         optional auto_start
password        required
password        optional

6b) For GDM >= 3.2, make the following changes to /etc/pam.d/gdm-password (thanks to grawity for this):

auth            requisite
auth            required
auth            requisite nullok
auth            optional unwrap
auth            optional
auth            sufficient uid >= 1000 quiet
auth            required
account         required
password        required
password        optional
session         required
-session        optional
session         optional force revoke
session         required
session         required
session         optional unwrap
session         optional auto_start

7) To be able to automatically mount your encrypted home directory on login using SSH, edit /etc/pam.d/sshd:

#auth           required        #Disable remote root
auth            required
auth            optional unwrap
auth            required
account         required
account         required
account         required
password        required
password        optional
session         optional unwrap
session         required
session         required
session         optional nox11

8) Execute (it can take some while, it automatically encrypts your home files)

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

9) Log in and check if everything worked correctly.

This is a working solution and ecryptfs is exactly used as in Ubuntu (10.04/10.10) - and is easy to set up. Besides this, it has the advantage of auto-unmount at log-out, anrxc's solution does not provide this. You can also encrypt swap with the tools provides by ecryptfs, just use ecryptfs-setup-swap.