Encryption of partitions

These are some helper tools to make use of the device mapper crypt target which is available in the Linux kernel 2.6.4 and later. I wrote them mainly for my personal use, so they are especially designed for my needs, but perhaps you'll find them similarly useful.

The device mapper is used by LVM2 (logical volume management version 2), but can be utilized without it. It makes it possible to map sections of block devices (e.g. partitions) to new block devices, whose nodes normally will be created in /dev/mapper. dm-crypt encrypts and decrypts the data during the mapping using a specified algorithm (all ciphers of the kernel can be used) and a given key.


I don't give any warranties. (See the GPLv2 for details about warranties.) However I use it daily for encrypting my swap and ext3 partitions (even my root partition) without any problems so far. But be careful and backup your data!

This encryption only protects against data acess after the computer has been powered off (e.g. after being stolen, simply shut down or being confiscated). If the computer was turned on and the password for decryption was given, an attacker can access the data like you. Everybody who can become root can also read out your key. So there have to be further security measures to prevent this (e.g. firewalls, regular updates).


You need a kernel with the device mapper compiled in or as a module. (Kernel 2.6 has it and there is a patch available for kernel 2.4 - for example in the Debian package kernel-patch-device-mapper.) The kernel should also know the sysfs filesystem.

The following libraries are required: libdevmapper, libgcrypt11 and libxml2.

Mount sysfs on /sys with e.g. the following /etc/fstab entries:

    sysfs	/sys		sysfs	defaults		0	0

To encrypt the root filesystem initramfs-tools are recommended.


Extract the tarball and execute as root 'make install'. (On a Debian system install the .deb package instead.)

Encrypting filesystems

cryptfs allows you to encrypt some filesystems and offers a simple form of logical volume management.

All information about the encrypted filesystems have to be provided in a xml file. An example with explanations is provided in example/cryptfs.xml or on Debian systems in /usr/share/doc/dmcryptfs/cryptfs.xml.gz. A simple setup with one encrypted filesystem would be:

    <?xml version="1.0" encoding="UTF-8"?>
        <!-- For the first setup these options can be overriden with
	     the -m option to be able to create a filesystem on it. -->
        <option name="fsck" value="yes"/>
        <option name="mount" value="yes"/>
        <storage device="/dev/hda6">
            <entry name="home" cipher="aes256-cbc-essiv:sha256"/>
        <action name="boot">
            <key type="passphrase" retry="2">
		/home filesystem encryption
            <map name="home"/>

As you can see this xml file consists of three parts:

  1. some options,
  2. the definition of the storage for the encrypted data and
  3. the definition of actions (i.e. asking for a key, decrypting the data, fscking and mounting the filesystem).

A complete description of these parts is given in example/cryptfs.xml resp. /usr/share/doc/dmcryptfs/cryptfs.xml.gz.

This xml file should be saved as /etc/cryptfs.xml. A call of 'cryptfs boot' will then activate this encrypted filesystem. ("boot" is the name of the action in the xml file.)

There is an init script called cryptfs, which will call 'cryptfs boot' during boot if there is such an action available. (On Debian systems this script will be installed automatically. So don't name your actions "boot" unless they should be started at boot time.)

If run for the first time you should call cryptfs with the -m option. The will prevent cryptfs from checking and mounting the filesystem (because there is none yet, only garbage). Then you can create the filesystem (using mke2fs and similar tools) in the corresponding devices in /dev/mapper/.

Root Filesystem

This does also work for the root filesystem. Cryptfs comes with some scripts for initramfs-tools, which will call the "root" action (if there is one) at boot time before the root filesystem is mounted.

Because the cryptfs.xml has to be included in the initramfs image each time you modify the xml file you have to call 'update-initramfs -u'. If there exists a /boot/cryptfs.key it will also be included in the initramfs image as /etc/cryptfs.key (to allow two factor authentication, see below).

Note that /etc/passwd, /etc/groups and the name service switch libraries are usually not present in the initramfs, so all "uid" and "gid" options won't work and will yield an error instead.


My primary goal was to make it play nicely with hotplugging to implement two factor authentication (that means, that authentication is based on two things: something you have (e.g. an usb-stick) and something you know (your passphrase)). With udev you can easily call cryptfs with a rule like:

    BUS=="scsi", SYSFS{vendor}=="USB", SYSFS{model}=="Flash Disk", \
	KERNEL=="sd?1", SYMLINK+="usbstick", \
	RUN+="/sbin/cryptfs usbstick"

In /etc/cryptfs.xml you need an action rule like this:

    <action name="usbstick">
        <key id="general" type="composite" length="256">
            <key type="file">
                    mount /media/usbstick


                <postexec onstate="always" ignorestatus="yes">
                    umount /media/usbstick
            <key type="passphrase" needtty="yes">
		Filesystem encryption: Please enter the password.
        <map name="home"/>

It creates a key from the bits in /media/usbstick/key (it should contain 32 random bytes) and the given password.

Encrypting a swap partition

A swap partition is encrypted the same way as the filesystems are. But instead of checking and mounting the filesystem we have to activate it as a swap partition.

First you have to specify where to store the swap data, for example in hda5:

    <storage device="/dev/hda5">
        <entry name="swap"  cipher="twofish-cbc-essiv:sha256"/>

Be careful to write the correct device name in there. The contents of this device will be overwritten every time it is activated!

Then create an action called swap (or any other name you like):

    <action name="swap">
        <key type="composite">
            <key type="file" length="256">/dev/hda5</key>
            <key type="file" length="256">/dev/random</key>

        <map name="swap" fsck="no" mount="no">
            <postexec onmode="map">
                /sbin/mkswap /dev/mapper/swap
                /sbin/swapon /dev/mapper/swap

This action uses a random key (256 bits from /dev/random and 256 encrypted bits from /dev/hda5, which should also be fairly random), sets up an encrypted block device /dev/mapper/swap and finally creates and activates a swap area in this block device.

Now all you need is an init script, that calls '/sbin/cryptfs swap' every reboot. /etc/init.d/cryptfs does that, so just link it in the corresponding rc directory. (For example in Debian this would be a symlink from /etc/rcS.d/S37cryptfs to ../init.d/cryptfs, but the .deb package will already take care of this.)

Either reboot, or deactivate your swap partition and start '/sbin/cryptfs swap' manually.


If you have questions, found bugs, have ideas for improvements, more features or if you just like it, please tell me. (Or if you like to write a better documentation. ;-)

My mail address is:


Thanks to Christophe Saout for the device mapper crypt target and for very fast bug fixing on New Year's eve.