About
-----
These are some helper tools to make use of the device mapper crypt
target. I wrote them mainly for my personal use, so they are
especially designed for my needs, but perhaps you'll find
them similarly useful.


WARNING:
--------
Although I use this program for encrypting all my ext3 filesystems
(even root) myself, I cannot guarantee its correctness.
So be careful and backup your data!


Prerequisites
-------------
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 entry:

    sysfs	/sys		sysfs	defaults		0	0

To encrypt the root filesystem initramfs-tools are recommended.


Installation
------------
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"?>
    <dmcrypt>
        <!-- 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"/>
        </storage>
    
	<action name="boot">
	    <key type="passphrase">
		/home filesystem encryption
	    </key>
	    <map name="home"/>
	</action>
    </dmcrypt>

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.


Hotplugging
-----------
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">
                <preexec>
                    mount /media/usbstick
                </preexec>

                /media/usbstick/key

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

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"/>
    </storage>

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>
	</key>

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

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.


A few words about security
--------------------------
This encryption protects your data against physical theft of
the harddisc (maybe with the PC or laptop attached to it).
Be it by a normal thief or governmental power. Because once
the computer is turned off, it doesn't know the key anymore
and without the key, the data can't be decrypted
(if you have chosen a good cipher like twofish or aes).

However this encryption does not help against intruders into
the running system. Everybody who can become root can read
the data in the decrypted block devices and can also read out
the keys ('dmsetup table' gives it away). So make sure
that your system is also secure in these regards.


Contact
-------
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: a.motzkau@web.de

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