https://wiki.archlinux.org/api.php?action=feedcontributions&user=Blucell&feedformat=atomArchWiki - User contributions [en]2024-03-29T06:34:53ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=ECryptfs&diff=393548ECryptfs2015-08-24T17:06:16Z<p>Blucell: Replacing 'FEKEK' with 'FEFEK'</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Encryption]]<br />
[[Category:File systems]]<br />
[[fr:Encryption avec eCryptfs]]<br />
[[it:System Encryption with eCryptfs]]<br />
[[ru:ECryptfs]]<br />
{{Related articles start}}<br />
{{Related|Disk encryption}}<br />
{{Related articles end}}<br />
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.<br />
<br />
In implementation eCryptfs differs from [[dm-crypt]], which provides a ''block device encryption layer'', while eCryptfs is an actual file-system &ndash; a [http://en.wikipedia.org/wiki/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). <br />
<br />
{{Note|The article is in the process of being re-structured. If you need to find information that might not be in its place yet again, the revision before the restructuring is [https://wiki.archlinux.org/index.php?title&#61;ECryptfs&oldid&#61;291214 here].}}<br />
<br />
== Basics ==<br />
<br />
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]].<br />
<br />
To familiarize with eCryptfs a few points: <br />
* 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. <br />
* 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). <br />
* A number of eCryptfs acronyms are used throughout the documentation: <br />
** 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. <br />
** 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.<br />
** 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]). <br />
** 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.<br />
<br />
Before using eCryptfs, the following disadvantages should be checked for applicability. <br />
<br />
=== Deficiencies ===<br />
<br />
* Hard-coded variables <br />
:The best usability of eCryptfs is achieved by relying on the so-called "Ubuntu tools" of the {{Pkg|ecryptfs-utils}} package. A considerable downside is that a lot of variables (encryption options, lower directory path) are hard-coded into the tools. Changing them infers considerable manual configuration to achieve similar integration. <br />
* Network storage mounts<br />
:eCryptfs has long-standing [https://bugs.launchpad.net/ecryptfs/+bug/277578 bugs] and/or feature requests relating to networked storage. Replicating a content backup of an encrypted directory to a network backup storage is always possible. However, if you want to employ ecryptfs to store the encrypted directory directly on a network storage and mount it locally, you should search for working solutions of the respective network tools (NFS, Samba, etc.) first. If in doubt, [[EncFS]] may be a better choice for such application.<br />
<br />
* Sparse files<br />
:eCryptfs does not handle [https://en.wikipedia.org/wiki/Sparse_file sparse files]. This is sometimes referred to as a bug, but likewise is a consequence of the design as a [[Disk encryption#Stacked filesystem encryption|stacked filesystem encryption]]. For example, in an eCryptfs directory a {{ic|truncate -s 1G file.img}} creates 1GB encrypted data and passes it to the underlying filesystem to store; with the corresponding resource (disk space, data throughput) requirements. Unencrypted, the same file can be allocated efficiently as sparse file space by the filesystem; with a [[Disk_encryption#Block device encryption|block device encryption]] only the respective filesystem output would be encrypted. <br />
<br />
:This should be considered before encrypting large portions of the directory structure. For most intents and purposes this deficiency does not pose a problem. One workaround is to place sparse files in an unencrypted {{ic|.Public}} directory (as opposed to the standard eCryptfs {{ic|.Private}} directory, explained below). Another method is to use a ''dm-crypt'' [[Dm-crypt/Encrypting_a_non-root_file_system#Loop_device|container]] in {{ic|.Public}} for such.<br />
<br />
== Setup example overview ==<br />
<br />
The following [[#Setup_.26_Mounting|#Setup & mounting]] section describes alternatives using eCryptfs to encrypt a data directory. The alternatives start with [[#Using the Ubuntu tools]], which make eCryptfs usage particularly easy and also safe against user errors. This also applies to [[#Encrypting a home directory]] with the tools. During setup, instructions are given on the console by the scripts. The [[#Using ecryptfs-simple]] section then introduces an alternative package to aide using eCryptfs. The [[#Manual setup]] section then describes the setup using the {{ic|ecryptfs}} filesystem directly. The first subsection ([[#With ecryptfs-utils]]) still uses one more script and is suggested to read to familiarize with the setup of the manual options before using them [[#Without ecryptfs-utils]]. <br />
<br />
The alternatives include <br />
# the setup step for the encrypted directory structures <br />
# the setup to mount, unmount the directory at runtime manually and/or automatically at user login<br />
Each of the described alternative examples can be removed after setup very easily, so do not refrain from testing which suits your needs best.<br />
<br />
== Setup & mounting ==<br />
<br />
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]].<br />
<br />
Once you have installed that package you can load the {{ic|ecryptfs}} module and continue with the setup:<br />
# modprobe ecryptfs<br />
<br />
Before starting, check the eCryptfs documentation. It is distributed with a very good and complete set of [http://ecryptfs.org/documentation.html manual pages].<br />
<br />
{{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.}}<br />
<br />
=== Using the Ubuntu tools ===<br />
<br />
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.<br />
<br />
The set-up used by these tools is as follows:<br />
{| class="wikitable" style="margin-left: 2em; margin-right: 2em; margin-bottom: 0.8em;"<br />
|<br />
* each user can have '''only one encrypted directory''' that is managed by these tools:<br />
** either full {{ic|$HOME}} directory encryption, or <br />
** a single encrypted data directory (by default {{ic|~/Private/}}, but this can be customized).<br />
* 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><br />
* the '''encryption options''' used are:<br />
** ''cipher:'' AES<br />
** ''key length:'' 16 bytes (128 bits)<br />
** ''key management scheme:'' passphrase<br />
** ''plaintext passthrough:'' enabled<br />
* 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><br />
** {{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}})<br />
** {{ic|Private.sig}} ''[plain text file]'' - contains the signature used to identify the mount passphrase in the kernel keyring<br />
** {{ic|wrapped-passphrase}} ''[binary file]'' - the mount passphrase, encrypted with the login passphrase<br />
** {{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<br />
|}<br />
<br />
==== Encrypting a data directory ====<br />
For a full {{ic|$HOME}} directory encryption see [[#Encrypting a home directory]]<br />
<br />
Before the data directory encryption is setup, decide whether it should later be mounted manually or automatically with the user log-in. <br />
<br />
To encrypt a single data directory as a user and mount it manually later, run:<br />
$ ecryptfs-setup-private --nopwcheck --noautomount <br />
<br />
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. <br />
<br />
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:<br />
<br />
;'''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. <br />
<br />
;'''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.<br />
<br />
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:<br />
<br />
$ mv ~/Private /path/to/new/folder<br />
$ echo /path/to/new/folder > ~/.ecryptfs/Private.mnt<br />
<br />
To actually use your encrypted folder, you will have to mount it - see [[#Mounting]] below.<br />
<br />
==== Encrypting a home directory ====<br />
<br />
The following wrapper script will set up an encrypted {{ic|$HOME}} directory for a user and take care of migrating any existing files they have in their not yet encrypted home directory. Ensure that the user in question ''owns no processes'' and is ''logged out''. You also need to ensure that you have {{pkg|rsync}} and {{pkg|lsof}} installed. Once the prerequisites have been met, run:<br />
<br />
# ecryptfs-migrate-home -u ''username''<br />
<br />
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.<br />
<br />
==== Mounting ====<br />
<br />
===== Manually =====<br />
<br />
Executing the wrapper <br />
$ ecryptfs-mount-private <br />
and entering the passphrase is all needed to mount the encrypted directory to the [[#Using_the_Ubuntu_tools|above]] described ''upper directory'' {{ic|~/Private}}. <br />
<br />
Likewise, executing<br />
$ ecryptfs-umount-private<br />
will unmount it again. <br />
<br />
{{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.}}<br />
<br />
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.<br />
<br />
===== Auto-mounting ===== <br />
<br />
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:<br />
/usr/share/doc/ecryptfs-utils/README<br />
<br />
For auto-mounting it is required that the passphrase to access the encrypted directory is synchronised with the user log-in. <br />
<br />
The following steps set it up: <br />
<br />
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'').<br />
<br />
2. Add ''ecryptfs'' to the pam-stack exactly as following to allow transparent unwrapping of the passphrase on login:<br />
<br />
Open {{ic|/etc/pam.d/system-auth}} and ''after'' the line containing {{ic|auth required pam_unix.so}} add:<br />
auth required pam_ecryptfs.so unwrap<br />
Next, ''above'' the line containing {{ic|password required pam_unix.so}} insert:<br />
password optional pam_ecryptfs.so<br />
And finally, ''after'' the line {{ic|session required pam_unix.so}} add:<br />
session optional pam_ecryptfs.so<br />
<br />
3. Re-login and check output of ''mount'' which should now contain a mountpoint, e.g.:<br />
/home/$USER/.Private on /home/$USER/Private type ecryptfs (...)<br />
for the user's encrypted directory. It should be perfectly readable at {{ic|~$HOME/Private/}}. <br />
<br />
The latter should be automatically unmounted and made unavailable when the user logs off. <br />
<br />
{{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] <br />
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.}}<br />
<br />
=== Using ecryptfs-simple ===<br />
<br />
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].<br />
<br />
As the name implies, usage is simple:<br />
# simple mounting<br />
ecryptfs-simple /path/to/foo /path/to/bar<br />
<br />
# automatic mounting: prompts for options on the first mount of a directory then reloads them next time<br />
ecryptfs-simple -a /path/to/foo /path/to/bar<br />
<br />
# unmounting by source directory<br />
ecryptfs-simple -u /path/to/foo<br />
<br />
# unmounting by mountpoint<br />
ecryptfs-simple -u /path/to/bar<br />
<br />
=== Manual setup ===<br />
<br />
The following details instructions to set up eCryptfs encrypted directories manually. The first section still relies on one extra script from the {{Pkg|ecryptfs-utils}} package. It may be an easier start and can be tried without any root rights. The [[#Without ecryptfs-utils|second]] then sets up an encrypted directory with other encryption options than the default tools. <br />
<br />
{{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.}} <br />
<br />
==== With ecryptfs-utils ====<br />
<br />
Alternatively to using the scripts {{ic|ecryptfs-setup-private}} and {{ic|ecryptfs-mount-private}} to setup and mount eCryptfs, the same can be done directly with the binaries (which those scripts use) {{ic|ecryptfs-add-passphrase}} and {{ic|mount.ecryptfs_private}} from the {{Pkg|ecryptfs-utils}} package. Those binaries require no root privileges to work by default.<br />
<br />
First choose an ALIAS as you like. Through this section, ALIAS will be {{ic|secret}}. Create the required directories/files:<br />
$ mkdir ~/.secret ~/secret ~/.ecryptfs<br />
$ touch ~/.ecryptfs/secret.conf ~/.ecryptfs/secret.sig<br />
<br />
The {{ic|~/.secret}} directory will hold the encrypted data. The {{ic|~/secret}} directory is the mount point where {{ic|~/.secret}} will be mounted as an ecryptfs filesystem.<br />
<br />
In the next command, replace USER with the name of the current user's home directory. Note that you should write full paths to {{ic|~/.ecryptfs/secret.conf}}. Its format looks like the one in {{ic|/etc/fstab}} without the mount options:<br />
$ echo "/home/USER/.secret /home/USER/secret ecryptfs" > ~/.ecryptfs/secret.conf<br />
<br />
A mount passphrase must be added to the keyring:<br />
$ ecryptfs-add-passphrase<br />
Passphrase: <br />
Inserted auth tok with sig [78c6f0645fe62da0] into the user session keyring<br />
<br />
Write the output signature ({{ic|ecryptfs_sig}}) from the previous command to {{ic|~/.ecryptfs/secret.sig}}:<br />
$ echo 78c6f0645fe62da0 > ~/.ecryptfs/secret.sig<br />
<br />
A second passphrase for filename encryption may be used. If you choose so, add it to the keyring:<br />
$ ecryptfs-add-passphrase<br />
Passphrase: <br />
Inserted auth tok with sig [326a6d3e2a5d444a] into the user session keyring<br />
<br />
If you run the command above, '''append''' its output signature ({{ic|ecryptfs_fnek_sig}}) to {{ic|~/.ecryptfs/secret.sig}}:<br />
$ echo 326a6d3e2a5d444a >> ~/.ecryptfs/secret.sig<br />
<br />
Finally, to mount {{ic|~/.secret}} on {{ic|~/secret}}:<br />
$ mount.ecryptfs_private secret<br />
<br />
An eCryptfs filesystem will be mounted with the following options:<br />
rw,nosuid,nodev,relatime,ecryptfs_fnek_sig=326a6d3e2a5d444a,ecryptfs_sig=78c6f0645fe62da0,ecryptfs_cipher=aes,ecryptfs_key_bytes=16,ecryptfs_unlink_sigs<br />
<br />
Except for {{ic|ecryptfs_sig}} and {{ic|ecryptfs_fnek_sig}}, the options are hard-coded. {{ic|ecryptfs_fnek_sig}} will exist only if you choose filename encryption.<br />
<br />
To unmount {{ic|~/.secret}}:<br />
$ umount.ecryptfs_private secret<br />
<br />
==== Without ecryptfs-utils ====<br />
<br />
The ecryptfs-utils package is distributed with a few helper scripts which will help you with key management and similar tasks. If one wants, for example, make a choice about the encryption cipher, some of those scripts cannot be used. In this section we setup an encrypted data directory diverting from those defaults. <br />
<br />
First create your private directories, in this example we will call them analogous to the previous section: {{ic|secret}}<br />
$ mkdir -m 700 /home/username/{.secret,.ecryptfs}<br />
$ mkdir -m 500 /home/username/secret<br />
<br />
To summarize:<br />
* Actual encrypted data will be stored in the lower {{ic|~/.secret}} directory <br />
* While mounted, decrypted data will be available in {{ic|~/secret}} directory <br />
** While not mounted nothing can be written to this directory<br />
** While mounted it has the same permissions as the lower directory<br />
<br />
Second we create the mount-passphrase ("file encryption key, encryption key", or '''fekek''') for the directory. It has to be very secure and cannot be changed easily. The ''ecryptfs-setup-private'' script offers the option to generate it from {{ic|/dev/urandom}}. 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 an extra password ("Arch"): <br />
<br />
$ 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<br />
<br />
The advantages of the above step are: the mount passphrase is generated from a random source and secured by extra hashing before it is stored on disk. Further, the wrap-passphrase can be changed later. <br />
<br />
Next, we test the passphrase by loading it into the kernel keyring: <br />
<br />
$ printf "%s" "Arch" | ecryptfs-insert-wrapped-passphrase-into-keyring /home/username/.ecryptfs/wrapped-passphrase -<br />
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring<br />
and manually copy the signature into the configuration: <br />
$ echo "7c5d3dd8a1b49db0" > ~/.ecryptfs/secret.sig<br />
<br />
Now we continue to setup the encryption options for the directory and prepare an user-mountable entry for {{ic|/etc/fstab}}. If you already know the eCryptfs options to use in it, you can skip the following ''mount'' and create an entry with the above signature already. <br />
<br />
The ''mount.ecryptfs'' command needs root and does not allow for piping the passphrase unfortunately. The mount helper will ask questions about the options we want to choose ("Key type": passphrase - choose any, we only do this to generate the options to use), but let it mount: <br />
<br />
# mount -t ecryptfs /home/username/.secret /home/username/secret<br />
Passphrase: yes<br />
Cipher: aes<br />
Key byte: 32<br />
Plaintext passtrough: no<br />
Filename encryption: no<br />
Add signature to cache: yes <br />
<br />
To summarize the parameters: <br />
* The above chosen {{ic|32}} "key bytes" result in a 256 bit AES encryption (the helper scripts are hard-coded to AES with 128 bit).<br />
* Plaintext passtrough enables to store and work with '''un-encrypted''' files stored in the lower directory.<br />
* In eCryptfs terms the key used to protect filenames is known as "filename encryption key", or '''fnek'''<br />
* '''fekek''' and '''fnek''' can be the same key or different ones at choice <br />
<br />
To create the mount point for the user in [[fstab]], find the current mount and copy it. For example ({{ic|XY}} are placeholders here): <br />
<br />
{{hc|# mount|2=/home/username/.secret on /home/username/secret type ecryptfs (... ecryptfs_fnek_sig=XY,ecryptfs_sig=XY,ecryptfs_cipher=aes,ecryptfs_key_bytes=32,ecryptfs_unlink_sigs, user)}}<br />
<br />
Or, alternatively, append it into {{ic|/etc/fstab}} to edit it: <br />
<br />
# mount | grep secret >> /etc/fstab <br />
<br />
Before continuing, we can already un-mount the temporary mount we used to generate the options: <br />
# umount /home/username/secret<br />
<br />
Now the mount line has to be edited into the correct format, the mount options {{ic|nosuid,nodev,noexec,relatime}} before the first ''ecryptfs'' option are default and can be left out. But what we need to add is the correct signatures for the passphrases to replace the ones of the current mount: <br />
# cat /home/username/.ecryptfs/secret.sig <br />
7c5d3dd8a1b49db0 <br />
<br />
We also need to add the options {{ic|user}} and {{ic|noauto}}. After the edit, the entry will look similar to (bold entries added): <br />
<br />
{{hc|/etc/fstab|2=/home/username/.secret /home/username/secret ecryptfs '''noauto''','''user''',ecryptfs_fnek_sig='''7c5d3dd8a1b49db0''',ecryptfs_sig='''7c5d3dd8a1b49db0''',ecryptfs_cipher=aes,ecryptfs_key_bytes=32,ecryptfs_unlink_sigs '''0 0'''}}<br />
<br />
Some options to note: <br />
* The {{ic|ecryptfs_fnek_sig}} option will be only listed if you enabled filename encryption <br />
* The second last option {{ic|ecryptfs_unlink_sigs}} ensures that the keyring is cleared every time the directory is un-mounted<br />
* The bold options have been added: <br />
** The {{ic|user}} option enables to mount the directory as a user <br />
** The {{ic|noauto}} option is important, because otherwise systemd will error trying to mount the entry directly on boot. <br />
* 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.<br />
<br />
The setup is now complete and directory should be mountable by the user. <br />
<br />
===== Mounting =====<br />
<br />
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: <br />
<br />
$ ecryptfs-insert-wrapped-passphrase-into-keyring /home/username/.ecryptfs/wrapped-passphrase<br />
Passphrase: <br />
Inserted auth tok with sig [7c5d3dd8a1b49db0] into the user session keyring <br />
<br />
Now the directory can be mounted without the mount helper questions: <br />
$ mount -i /home/username/secret<br />
<br />
and files be placed into the {{ic|secret}} directory. The above two steps are necessary every time to mount the directory manually. <br />
<br />
To unmount it again: <br />
<br />
$ umount /home/username/secret<br />
<br />
To finalize, the preliminary passphrase to wrap the encryption passphrase may be changed: <br />
$ ecryptfs-rewrap-passphrase /home/username/.ecryptfs/wrapped-passphrase<br />
Old wrapping passphrase: <br />
New wrapping passphrase: <br />
New wrapping passphrase (again):<br />
<br />
The un-mounting should also clear the keyring, to check the user's keyring or clear it manually: <br />
$ keyctl list @u<br />
$ keyctl clear @u<br />
<br />
{{Note|One should remember that {{ic|/etc/fstab}} is for system-wide partitions only and should not generally be used for user-specific mounts}}<br />
<br />
===== Auto-mounting =====<br />
<br />
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]]. <br />
<br />
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]]. <br />
<br />
{{Accuracy|<br>- the section should be more generic than it is now<br><br />
- the described method does not work for users, for encountered problems:|section=#Automounting}}<br />
<br />
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}}:<br />
<br />
<luserconf name=".pam_mount.conf.xml" /><br />
<mntoptions require="" /> <!-- Default required mount options are ; this clears them --><br />
<lclmount>mount -i %(VOLUME) "%(before=\"-o\" OPTIONS)"</lclmount> <!-- --><br />
<br />
Please prefer writing manually these lines instead of simply copy/pasting them (especially the lclmount line), otherwise you might get some corrupted characters.<br />
Explanation:<br />
* the first line indicates where the user-based configuration file is located (here {{ic|~/.pam_mount.conf.xml}})<br />
* the second line overwrites the default required mount options which are unnecessary ("nosuid,nodev")<br />
* the last line indicates which mount command to run (eCryptfs needs the {{Ic|-i}} switch).<br />
<br />
Then set the volume definition, preferably to {{ic|~/.pam_mount.conf.xml}}:<br />
<pam_mount><br />
<volume noroot="1" fstype="ecryptfs" path="/home/user/.secret/" mountpoint="/home/user/secret/"/><br />
</pam_mount><br />
<br />
"noroot" is needed because the encryption key will be added to the user's keyring.<br />
<br />
Finally, edit {{ic|/etc/pam.d/login}} as described in [[pam_mount]]'s article.<br />
<br />
====== Optional step ======<br />
<br />
To avoid wasting time needlessly unwrapping the passphrase you can create a script that will check ''pmvarrun'' to see the number of open sessions:<br />
#!/bin/sh<br />
#<br />
# /usr/local/bin/doecryptfs<br />
<br />
exit $(/usr/sbin/pmvarrun -u$PAM_USER -o0)<br />
<br />
With the following line added before the eCryptfs unwrap module in your PAM stack:<br />
auth [success=ignore default=1] pam_exec.so quiet /usr/local/bin/doecryptfs<br />
auth required pam_ecryptfs.so unwrap<br />
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}}.<br />
<br />
== Usage ==<br />
<br />
{{Expansion|Content that still needs to be covered:<br />
- 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><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><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")<br />
|section=Major_restructuring/rewrite}}<br />
<br />
=== Symlinking into the encrypted directory ===<br />
<br />
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:<br />
$ mv ~/.mozilla ~/Private/mozilla<br />
$ ln -s ~/Private/mozilla ~/.mozilla<br />
<br />
=== Removal of encryption ===<br />
<br />
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. <br />
<br />
If you were [[#Using the Ubuntu tools]] to setup a single directory encryption, you can directly follow the steps detailed by: <br />
<br />
$ ecryptfs-setup-private --undo<br />
<br />
and follow the instructions.<br />
<br />
=== Backup ===<br />
<br />
If you want to move a file out of the private directory just move it to the new destination while {{ic|~/Private}} is mounted. <br />
<br />
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. <br />
<br />
You can do backups, or incremental backups, of the encrypted (e.g. {{ic|~/.Private}}) directory, treating it like any other directory. <br />
<br />
Further points to note: <br />
<br />
* 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}}. <br />
<br />
* It should be ensured to include the eCryptfs setup files (located in {{ic|~/.ecryptfs}} usually) into the regular or a separate backup.<br />
<br />
* If you use special filesystem mount options, for example {{ic|ecryptfs_xattr}}, do extra checks on restore integrity.<br />
<br />
== See Also ==<br />
<br />
* [http://ecryptfs.org/documentation.html eCryptfs] - Manpages and project home <br />
* [https://defuse.ca/audits/ecryptfs.htm Security audit] of eCryptfs by Taylor Hornby (January 22, 2014).<br />
* [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 <br />
* [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<br />
* [http://ecryptfs.sourceforge.net/ecryptfs.pdf eCryptfs design] by Michael Halcrow (May 2005) - Original design document detailing and discussing eCryptfs</div>Blucell