LDP/LDP/howto/docbook/Encrypted-Root-Filesystem-HOWTO.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
     "http://docbook.org/xml/4.2/docbookx.dtd" []>

<article class="whitepaper" id="Encrypted-Root-Filesystem-HOWTO">

<articleinfo>

    <title>Encrypted Root Filesystem HOWTO</title>

    <author>
        <firstname>Christophe</firstname>
        <surname>Devine</surname>
    </author>

    <abstract>
        <para>
This document explains how to make your personal data secure
by encrypting your Linux root filesystem using strong cryptography.
        </para>
    </abstract>

    <legalnotice>
        <para>
This HOWTO is released under the GNU Free Documentation License
Version 1.2.
        </para>
    </legalnotice>

    <revhistory id="revhistory">

        <revision>
            <revnumber>v1.3</revnumber>
            <date>2005-03-13</date>
            <authorinitials>cd</authorinitials>
            <revremark>Updated the packages version.</revremark>
        </revision>

        <revision>
            <revnumber>v1.2</revnumber>
            <date>2004-10-20</date>
            <authorinitials>cd</authorinitials>
            <revremark>Updated the packages version.</revremark>
        </revision>

        <revision>
            <revnumber>v1.1</revnumber>
            <date>2003-12-01</date>
            <authorinitials>cd</authorinitials>
            <revremark>Added support for GRUB.</revremark>
        </revision>

        <revision>
            <revnumber>v1.0</revnumber>
            <date>2003-09-24</date>
            <authorinitials>cd</authorinitials>
            <revremark>Initial release, reviewed by LDP.</revremark>
        </revision>

        <revision>
            <revnumber>v0.9</revnumber>
            <date>2003-09-11</date>
            <authorinitials>cd</authorinitials>
            <revremark>Updated and converted to DocBook XML.</revremark>
        </revision>

    </revhistory>

</articleinfo>

<sect1 id="preparing-system">
    <title>Preparing the system</title>

    <sect2 id="partition-layout">
        <title>Setting up the partition layout</title>
        <para>
Your hard disk (hda) should contain at least three partitions:
        <itemizedlist>
            <listitem><para>
hda1: this small unencrypted partition will ask for
a password in order to mount the encrypted root filesystem.
            </para></listitem>
            <listitem><para>
hda2: this partition will contain your encrypted root filesystem;
make sure it is large enough.
            </para></listitem>
            <listitem><para>
hda3: this partition holds the current GNU/Linux system.
            </para></listitem>
        </itemizedlist>
        </para><para>
At this point, both hda1 and hda2 are unused. hda3 is where your
Linux distribution is currently installed; /usr and /boot must
<emphasis>not</emphasis> be separated from this partition.
        </para><para>
Here's an example of what your partition layout might look like:
        </para><para>
<screen># fdisk -l /dev/hda

Disk /dev/hda: 255 heads, 63 sectors, 2432 cylinders
Units = cylinders of 16065 * 512 bytes

   Device Boot    Start       End    Blocks   Id  System
/dev/hda1             1         1      8001   83  Linux
/dev/hda2             2       263   2104515   83  Linux
/dev/hda3           264       525   2104515   83  Linux
/dev/hda4           526      2047  12225465   83  Linux</screen>
        </para>
    </sect2>

    <sect2 id="debian-packages">
        <title>Required packages</title>
        <para>
If you use Debian, the following packages are mandatory:
        </para><para>
<screen>apt-get install gcc make libncurses5-dev patch bzip2 wget</screen>
        </para><para>
To make copy &amp; paste easier, you should also install:
        </para><para>
<screen>apt-get install lynx gpm</screen>
        </para>
    </sect2>

    <sect2 id="install-kernel-2.4">
        <title>Installing Linux-2.4.29</title>
        <para>
There are two main projects which add loopback encryption support in the
kernel: cryptoloop and loop-AES. This howto is based on loop-AES, since it
features an extremely fast and highly optimized implementation of Rijndael
in assembly language, and therefore provides maximum performance if
you have an IA-32 (x86) CPU. Besides, there are some
<ulink url="http://groups.google.com/groups?selm=1emrG-1Ck-25%40gated-at.bofh.it">security concerns</ulink>
about cryptoloop.
        </para><para>
First of all, download and unpack the loop-AES package:
        </para><para>
<screen>cd /usr/src
wget http://loop-aes.sourceforge.net/loop-AES/loop-AES-v3.0b.tar.bz2
tar -xvjf loop-AES-v3.0b.tar.bz2</screen>
        </para><para>
Then you must download and patch the kernel source:
        </para><para>
<screen>wget http://ftp.kernel.org/pub/linux/kernel/v2.4/linux-2.4.29.tar.bz2
tar -xvjf linux-2.4.29.tar.bz2
cd linux-2.4.29
rm include/linux/loop.h drivers/block/loop.c
patch -Np1 -i ../loop-AES-v3.0b/kernel-2.4.28.diff</screen>
        </para><para>
Setup the keyboard map:
        </para><para>
<screen>dumpkeys | loadkeys -m - > drivers/char/defkeymap.c</screen>
        </para><para>
Next, configure your kernel; make sure the following options are set:
        </para><para>
<screen>make menuconfig

    Block devices  ---&gt;

        &lt;*&gt; Loopback device support
        [*]   AES encrypted loop device support (NEW)

        &lt;*&gt; RAM disk support
        (4096)   Default RAM disk size (NEW)
        [*]   Initial RAM disk (initrd) support

    File systems  ---&gt;

        &lt;*&gt; Ext3 journalling file system support
        &lt;*&gt; Second extended fs support

(important note: do not enable /dev file system support)</screen>
        </para><para>
Compile the kernel and install it:
        </para><para>
<screen>make dep bzImage
make modules modules_install
cp arch/i386/boot/bzImage /boot/vmlinuz</screen>
        </para><para>
If grub is your bootloader, update /boot/grub/menu.lst
or /boot/grub/grub.conf:
        </para><para>
<screen>cat &gt; /boot/grub/menu.lst &lt;&lt; EOF
default 0
timeout 10
color green/black light-green/black
title Linux
    root (hd0,2)
    kernel /boot/vmlinuz ro root=/dev/hda3
EOF</screen>
        </para><para>
Otherwise, update /etc/lilo.conf and run lilo:
        </para><para>
<screen>cat &gt; /etc/lilo.conf &lt;&lt; EOF
lba32
boot=/dev/hda
prompt
timeout=60
image=/boot/vmlinuz
    label=Linux
    read-only
    root=/dev/hda3
EOF
lilo</screen>
        </para><para>
You may now restart the system.
        </para>
    </sect2>

    <sect2 id="install-kernel-2.6">
        <title>Installing Linux-2.6.10</title>
        <para>
Proceed as described in the previous section, using loop-aes'
<emphasis>kernel-2.6.10.diff</emphasis> patch instead, and make
sure cryptoloop support is <emphasis>not</emphasis> activated.
Note that modules support require that you have the module-init-tools
package installed.
        </para>
    </sect2>

    <sect2 id="install-util-linux">
        <title>Installing util-linux-2.12p</title>
        <para>
The losetup program, which is part of the util-linux package, must be
patched and recompiled in order to add strong cryptography support.
Download, unpack and patch util-linux:
        </para><para>
<screen>cd /usr/src
wget http://ftp.kernel.org/pub/linux/utils/util-linux/util-linux-2.12p.tar.bz2
tar -xvjf util-linux-2.12p.tar.bz2
cd util-linux-2.12p
patch -Np1 -i ../loop-AES-v3.0b/util-linux-2.12p.diff</screen>
        </para><para>
To use passwords that are less than 20 characters, enter:
        </para><para>
<screen>CFLAGS=&quot;-O2 -DLOOP_PASSWORD_MIN_LENGTH=8&quot;; export CFLAGS</screen>
        </para><para>
Security is certainly your major concern. For this reason, please do not
enable passwords shorter than 20 characters. Data privacy is not free,
one has to 'pay' in form of long passwords.
        </para><para>
Compile losetup and install it as root:
        </para><para>
<screen>./configure &amp;&amp; make lib mount
mv -f /sbin/losetup /sbin/losetup~
rm -f /usr/share/man/man8/losetup.8*
cd mount
gzip losetup.8
cp losetup /sbin
cp losetup.8.gz /usr/share/man/man8/
chattr +i /sbin/losetup</screen>
        </para>
    </sect2>
</sect1>

<sect1 id="encrypt-root-filesystem">
    <title>Creating the encrypted root filesystem</title>
    <para>
Fill the target partition with random data:
    </para><para>
<screen>shred -n 1 -v /dev/hda2</screen>
    </para><para>
Setup the encrypted loopback device:
    </para><para>
<screen>losetup -e aes256 -S xxxxxx /dev/loop0 /dev/hda2</screen>
    </para><para>
To prevent optimized dictionary attacks, it is recommended to add
the -S xxxxxx option, where "xxxxxx" is your randomly chosen
seed (for example, you might choose "gPk4lA"). Write down your seed on
a piece of paper so that you don't loose it afterwards. Also, in order
to avoid boot-time problems with the keyboard map, do not use non-ASCII
characters (accents, etc.) in your password. The
<ulink url="http://www.diceware.com/">Diceware</ulink> site offers
a simple way to create strong, yet easy to remember, passphrases.
    </para><para>
Now create the ext3 filesystem:
    </para><para>
<screen>mke2fs -j /dev/loop0</screen>
    </para><para>
Check that the password you entered is correct:
    </para><para>
<screen>losetup -d /dev/loop0
losetup -e aes256 -S xxxxxx /dev/loop0 /dev/hda2</screen>
    </para><para>
<screen>mkdir /mnt/efs
mount /dev/loop0 /mnt/efs</screen>
    </para><para>
You can compare the encrypted and unencrypted data:
    </para><para>
<screen>xxd /dev/hda2  | less
xxd /dev/loop0 | less</screen>
    </para><para>
It's time to install your encrypted Linux system. If you use a GNU/Linux
distribution (such as Debian, Slackware, Gentoo, Mandrake, RedHat/Fedora,
SuSE, etc.), run the following command:
    </para><para>
<screen>cp -avx / /mnt/efs</screen>
    </para><para>
If you use the Linux From Scratch book, proceed as described in
the manual, with the modifications below:
        <itemizedlist>
            <listitem>
<para>Chapter 6 - Installing util-linux:</para>
<para>Apply the loop-AES patch after unpacking the sources.</para>
                </listitem><listitem>
<para>Chapter 8 - Making the LFS system bootable:</para>
<para>Refer to the next section (Setting up the boot device).</para>
            </listitem>
        </itemizedlist>
    </para>
</sect1>

<sect1 id="setup-boot-device">
    <title>Setting up the boot device</title>
    <sect2 id="initial-ramdisk">
    <title>Creating the ramdisk</title>
        <para>
To begin with, chroot inside the encrypted partition and create
the boot device mount point:
        </para><para>
<screen>chroot /mnt/efs
mkdir /loader</screen>
        </para><para>
Then, create the initial ramdisk (initrd), which will be needed
afterwards:
        </para><para>
<screen>cd
dd if=/dev/zero of=initrd bs=1k count=4096
mke2fs -F initrd
mkdir ramdisk
mount -o loop initrd ramdisk</screen>
        </para><para>
If you're using grsecurity, you may get a "Permission denied" error
message; in this case you'll have to run the mount command outside chroot.
        </para><para>
Create the filesystem hierarchy and copy the required files in it:
    </para><para>
<screen>mkdir ramdisk/{bin,dev,lib,mnt,sbin}
cp /bin/{bash,mount} ramdisk/bin/
ln -s bash ramdisk/bin/sh
mknod -m 600 ramdisk/dev/console c 5 1
mknod -m 600 ramdisk/dev/hda2    b 3 2
mknod -m 600 ramdisk/dev/loop0   b 7 0
cp /lib/{ld-linux.so.2,libc.so.6,libdl.so.2} ramdisk/lib/
cp /lib/{libncurses.so.5,libtermcap.so.2}    ramdisk/lib/
cp /sbin/{losetup,pivot_root} ramdisk/sbin/</screen>
    </para><para>
It's ok if you see a message like "/lib/libncurses.so.5: No such file
or directory", or "/lib/libtermcap.so.2: No such file or directory";
bash only requires one of these two libraries. You can check which one
is actually required with:
    </para><para>
<screen>ldd /bin/bash</screen>
    </para><para>
Compile the sleep program, which will prevent the password prompt
being flooded by kernel messages (such as usb devices being registered).
    </para><para>
<screen>cat &gt; sleep.c &lt;&lt; &quot;EOF&quot;
#include &lt;unistd.h&gt;
#include &lt;stdlib.h&gt;

int main( int argc, char *argv[] )
{
    if( argc == 2 )
        sleep( atoi( argv[1] ) );

    return( 0 );
}
EOF

gcc -s sleep.c -o ramdisk/bin/sleep
rm sleep.c</screen>
    </para><para>
Create the init script:
    </para><para>
<screen>cat &gt; ramdisk/sbin/init &lt;&lt; &quot;EOF&quot;
#!/bin/sh

/bin/sleep 3

echo -n "Enter seed value: "
read SEED

/sbin/losetup -e aes256 -S $SEED /dev/loop0 /dev/hda2
/bin/mount -r -n -t ext3 /dev/loop0 /mnt

while [ $? -ne 0 ]
do
    /sbin/losetup -d /dev/loop0
    /sbin/losetup -e aes256 -S $SEED /dev/loop0 /dev/hda2
    /bin/mount -r -n -t ext3 /dev/loop0 /mnt
done

cd /mnt
/sbin/pivot_root . loader
exec /usr/sbin/chroot . /sbin/init
EOF

chmod 755 ramdisk/sbin/init</screen>
    </para><para>
Umount the loopback device and compress the initrd:
    </para><para>
<screen>umount -d ramdisk
rmdir ramdisk
gzip initrd
mv initrd.gz /boot/</screen>
    </para>
    </sect2>
    <sect2 id="bootable-cd">
    <title>Booting from a CD-ROM</title>
        <para>
I strongly advise you to start your system with a read-only
media, such as a bootable CD-ROM.
        </para><para>
Download and unpack syslinux:
        </para><para>
<screen>wget http://ftp.kernel.org/pub/linux/utils/boot/syslinux/syslinux-3.07.tar.bz2
tar -xvjf syslinux-3.07.tar.bz2</screen>
        </para><para>
Configure isolinux:
        </para><para>
<screen>mkdir bootcd
cp /boot/{vmlinuz,initrd.gz} syslinux-3.07/isolinux.bin bootcd
echo &quot;DEFAULT /vmlinuz initrd=initrd.gz ro root=/dev/ram0&quot; \
    &gt; bootcd/isolinux.cfg</screen>
        </para><para>
Create and burn the bootable cd-rom iso image:
        </para><para>
<screen>mkisofs -o bootcd.iso -b isolinux.bin -c boot.cat \
        -no-emul-boot -boot-load-size 4 -boot-info-table \
        -J -hide-rr-moved -R bootcd/

cdrecord -dev 0,0,0 -speed 4 -v bootcd.iso

rm -rf bootcd{,.iso}</screen>
        </para>
    </sect2>

    <sect2 id="boot-partition">
    <title>Booting from a HD partition</title>
        <para>
The boot partition can come in handy if you happen to lose your bootable
CD. <emphasis>Remember that hda1 is a writable media and is thus insecure;
use it only in case of emergency!</emphasis>
        </para><para>
Create and mount the ext2 filesystem:
        </para><para>
<screen>dd if=/dev/zero of=/dev/hda1 bs=8192
mke2fs /dev/hda1
mount /dev/hda1 /loader</screen>
        </para><para>
Copy the kernel and the initial ramdisk:
        </para><para>
<screen>cp /boot/{vmlinuz,initrd.gz} /loader</screen>
        </para><para>
If you use grub:
        </para><para>
<screen>mkdir /loader/boot
cp -av /boot/grub /loader/boot/
cat &gt; /loader/boot/grub/menu.lst &lt;&lt; EOF
default 0
timeout 10
color green/black light-green/black
title Linux
    root (hd0,0)
    kernel /vmlinuz ro root=/dev/ram0
    initrd /initrd.gz
EOF
grub-install --root-directory=/loader /dev/hda
umount /loader</screen>
        </para><para>
If you use lilo:
        </para><para>
<screen>mkdir /loader/{boot,dev,etc}
cp /boot/boot.b /loader/boot/
mknod -m 600 /loader/dev/hda  b 3 0
mknod -m 600 /loader/dev/hda1 b 3 1
mknod -m 600 /loader/dev/hda2 b 3 2
mknod -m 600 /loader/dev/hda3 b 3 3
mknod -m 600 /loader/dev/hda4 b 3 4
mknod -m 600 /loader/dev/ram0 b 1 0
cat &gt; /loader/etc/lilo.conf &lt;&lt; EOF
lba32
boot=/dev/hda
prompt
timeout=60
image=/vmlinuz
    label=Linux
    initrd=/initrd.gz
    read-only
    root=/dev/ram0
EOF
lilo -r /loader
umount /loader</screen>
        </para>
    </sect2>
</sect1>

<sect1 id="final-steps">
    <title>Final steps</title>
    <para>
Still inside chroot, modify /etc/fstab so that it contains:
    </para><para>
<screen>/dev/loop0      /               ext3    defaults       0       1</screen>
    </para><para>
Delete /etc/mtab and exit from chroot. Finally, run "umount -d /mnt/efs"
and reboot. If something goes wrong, you can still boot your unencrypted
partition by entering "Linux root=/dev/hda3" at the LILO: prompt.
    </para><para>
If everything went well, you can now re-partition your disk and encrypt
hda3 as well as hda4. In the following scripts, we assume that hda3 will
hold the swap device and hda4 will contain /home; you should initialize
both partitions first:
    </para><para>
<screen>shred -n 1 -v /dev/hda3
shred -n 1 -v /dev/hda4
losetup -e aes256 -S xxxxxx /dev/loop1 /dev/hda3
losetup -e aes256 -S xxxxxx /dev/loop2 /dev/hda4
mkswap /dev/loop1
mke2fs -j /dev/loop2</screen>
    </para><para>
Then create a script in the system startup directory and update fstab:
    </para><para>
<screen>cat &gt; /etc/init.d/loop &lt;&lt; &quot;EOF&quot;
#!/bin/sh

if [ "`/usr/bin/md5sum /dev/hda1`" != \
     "5671cebdb3bed87c3b3c345f0101d016  /dev/hda1" ]
then
    echo -n "WARNING! hda1 integrity verification FAILED - press enter."
    read
fi

echo &quot;1st password chosen above&quot; | \
    /sbin/losetup -p 0 -e aes256 -S xxxxxx /dev/loop1 /dev/hda3

echo &quot;2nd password chosen above&quot; | \
    /sbin/losetup -p 0 -e aes256 -S xxxxxx /dev/loop2 /dev/hda4

/sbin/swapon /dev/loop1

for i in `seq 0 63`
do
    echo -n -e "\33[10;10]\33[11;10]" > /dev/tty$i
done

EOF

chmod 700 /etc/init.d/loop
ln -s ../init.d/loop /etc/rcS.d/S00loop
vi /etc/fstab
...
/dev/loop2      /home           ext3    defaults       0       2</screen>
    </para>
</sect1>

<sect1 id="about">
    <title>About this HOWTO</title>
    <para>
The Encrypted Root Filesystem HOWTO was first written in november 2002 for the
<ulink url="http://www.linuxfromscratch.org/lfs/news.html">Linux From Scratch</ulink>
project. I'd like to thank the many people who have since contributed to
this document (in reverse chronological order): Micha Borrmann,
Dennis Lemckert, Oleg Vyushin, Ellen Bokhorst, Daczi L<>szl<7A>, Gaetano Zappulla,
Guillaume Lehmann, Claude Thomassin, Jean-Philippe Gu<47>rard, Luc Vo Van,
Jacobus Brink, Ernesto P<>rez Est<73>vez, Matthew Ploessel, Mike Lorek,
Lars Bungum, Michael Shields, Julien Perrot, Grant Stephenson, Cary W. Gilmer,
James Howells, Pedro Baez, Josh Purinton, Jari Ruusu and Zibeli Aton.
    </para><para>
This HOWTO has been translated in various languages:
    <itemizedlist>
        <listitem><para><ulink url="http://www.traduc.org/docs/HOWTO/lecture/Encrypted-Root-Filesystem-HOWTO.html">French</ulink></para></listitem>
        <listitem><para><ulink url="http://www.linux.it/~gaetano/erfs/">Italian</ulink></para></listitem>
        <listitem><para><ulink url="http://tldp.fsf.hu/HOWTO/Encrypted-Root-Filesystem-HOWTO-hu/">Hungarian</ulink></para></listitem>
        <listitem><para><ulink url="http://doc.nl.linux.org/HOWTO/Encrypted-Root-Filesystem-HOWTO-NL/article.html">Dutch</ulink></para></listitem>
    </itemizedlist>
    </para><para>
Please send any comment to
<ulink url="http://www.cr0.net:8040/about/">Christophe Devine</ulink>.
    </para>
</sect1>

</article>