readme

Fast and transparent file system and swap encryption package for linux. No source code changes to li

    module in /boot/modules-KERNELRELEASE/ directory for every kernel you
    intend to use.

8)  If your boot scripts automatically run "umount /initrd" and "blockdev
    --flushbufs /dev/ram0" commands, you may want to disable those commands.
    If you don't disable them, you may see annoying error messages when
    booting to encrypted root partition.

    Root partition loop device node is inside initrd, and that device node
    will remain busy forever. This means that encrypted root initrd can't be
    unmounted and RAM used by initrd file system can't be freed. This
    unable-to-unmount side effect is the reason why initrd is intentionally
    made as small as possible.

9)  Create 65 random encryption keys and encrypt those keys using gpg.
    Reading from /dev/random may take indefinitely long if kernel's random
    entropy pool is empty. If that happens, do some other work on some other
    console (use keyboard, mouse and disks). Use of gpg encrypted key file
    depends on encrypted swap.

        umask 077
        head -c 3705 /dev/random | uuencode -m - | head -n 66 | tail -n 65 \
            | gpg --symmetric -a >/boot/rootkey.gpg

10) Edit build-initrd.sh to match your setup. Set BOOTDEV, BOOTTYPE,
    CRYPTROOT and ROOTTYPE variables to correct values. If you are using 2.2
    or older kernels, set USEPIVOT=0 because 2.2 and older kernels do not
    have pivot_root functionality. You may also want to set
    LOADNATIONALKEYB=1 and manually copy your uncompressed national keyboard
    layout file (in "loadkeys" format) to /boot/default.kmap

    loadkeys configuration files for some popular distros:

    Debian:     /etc/console/boottime.kmap.gz
    Mandrake:   /usr/lib/kbd/keymaps/i386/qwert[yz]/*.kmap.gz
    Red Hat:    /lib/kbd/keymaps/i386/qwert[yz]/*.kmap.gz
    SUSE:       /usr/lib/kbd/keymaps/i386/qwert[yz]/*.map.gz
    Slackware:  /usr/share/kbd/keymaps/i386/qwert[yz]/*.map.gz

    Or alternatively, you can create keyboard map using your current
    keyboard layout. Like this:

        dumpkeys >/boot/default.kmap
    
    If your distro has set your keyboard to UTF-8 mode, then you may want to
    set UTF8KEYBMODE=1 in build-initrd.sh configuration. Running 'kbd_mode'
    command in text console shows current keyboard mode: default (ASCII), or
    unicode (UTF-8). If it says raw (scancode), then you are running
    kbd_mode command in X windows, not text console.

    devfs enabled kernel users (CONFIG_DEVFS_FS=y and CONFIG_DEVFS_MOUNT=y
    in kernel configuration) need to pay special attention to comments above
    these build-initrd.sh options: USEDEVFS, BOOTDEV, CRYPTROOT and
    EXTERNALGPGDEV.

11) Edit /etc/lilo.conf (or whatever) and set root= initrd= and append= as
    explained in comments at beginning of build-initrd.sh script.

12) Build a new /boot/initrd.gz

        ./build-initrd.sh

    Note: /boot/initrd.gz is supposed to be small (2 KB to 3 KB). All other
    utilities (loop.o module, insmod, losetup, loadkeys, gpg and possibly
    libraries) are copied to /boot directory. Libraries are not copied if
    programs are statically linked.

13) Run lilo (or whatever)

        lilo

14) Reboot your computer from rescue floppy/CD-ROM or other partition, so
    that the partition you are about to encrypt is *not* mounted.

15) Now you should be running a shell from rescue floppy/CD-ROM or other
    partition. This example assumes that /dev/hda1 is your /boot partition
    and /dev/hda2 is your root partition. Temporarily mount your root
    partition under /mnt

        mount -t ext2 /dev/hda2 /mnt

16) Edit root partition entry in /mnt/etc/fstab file. Replace old /dev/hda2
    with /dev/loop5 or whatever loop you are using for root partition. Loop
    device number must match ROOTLOOPINDEX= in build-initrd.sh
    configuration. The default in build-initrd.sh is 5, meaning /dev/loop5.

    Old /etc/fstab line:
      /dev/hda2    /       ext2   defaults   0   1
    New /etc/fstab line:
      /dev/loop5   /       ext2   defaults   0   1

    devfs enabled kernel users (CONFIG_DEVFS_FS=y and CONFIG_DEVFS_MOUNT=y
    in kernel configuration) need to substitute /dev/loop5 with /dev/loop/5

17) If you are using a distro that uses udev to manage /dev/* devices, you
    need to check that your root partition has /dev/console /dev/null
    /dev/zero devices as on-disk nodes.

        ls -l /mnt/dev/console /mnt/dev/null /mnt/dev/zero

    If one or more of above devices are missing, you may need to create them
    manually.

        mknod -m 600 /mnt/dev/console c 5 1
        mknod -m 666 /mnt/dev/null c 1 3
        mknod -m 666 /mnt/dev/zero c 1 5

18) Unmount your root partition (and sync for extra safety).

        umount /mnt
        sync

19) Mount your normal /boot partition under /mnt so that you can use
    previously built statically linked aespipe and gpg programs and read gpg
    encrypted key file 'rootkey.gpg'. Statically linked gpg program was
    copied there by build-initrd.sh script.

        mount -r -t ext2 /dev/hda1 /mnt

20) Use dd program to read your root partition contents, pipe that data
    through aespipe program, and finally write encrypted data back to same
    partition with another dd program. This is going to take a while if
    partition is large.

        dd if=/dev/hda2 bs=64k \
            | /mnt/aespipe -e AES128 -K /mnt/rootkey.gpg -G / \
            | dd of=/dev/hda2 bs=64k conv=notrunc

    aespipe program tries to run gpg from obvious locations on your rescue
    floppy/CD-ROM file system, but if it can't find gpg from those obvious
    locations, aespipe finally tries to run gpg from same directory that
    aespipe was run from (/mnt/) and should find statically linked gpg
    program there.

21) Clean up and reboot your computer.

        umount /mnt
        sync
        reboot

If you are upgrading kernel of a system where root partition is already
encrypted, only steps 5 to 7 and 13 are needed. /boot/initrd.gz is kernel
independent and there is no need to re-create it for each kernel. However,
if you are upgrading from 2.4 kernel to 2.6 kernel, new insmod may need to
be copied to /boot directory by running step 12 before running step 13.

If you want to fsck and mount partitions automatically and are indeed
encrypting root partition, it may be easier to just losetup required
partitions early in init scripts (before partitions are fsck'ed and
mounted). Don't losetup root partition again, as root partition has already
been losetup'ed by /linuxrc program in the "initrd" ram-disk.

Init scripts reside on root partition and encryption keys within such init
scripts are protected by root partition encryption. Of course, init scripts
containing sensitive keys must be readable only by root user:

    -rwx------  1 root   root   162 Nov 24 19:23 /etc/rcS.d/S07losetup.sh

Here is an example of /etc/rcS.d/S07losetup.sh Debian init script. Other
distros may store such init scripts in different directory under different
name. On SUSE, /etc/init.d/boot.d/S01losetup.sh may be more appropriate.

#!/bin/sh
echo "Pd1eXapMJk0XAJnNSIzE" | losetup -p 0 -e AES128 -K /etc/swapkey.gpg /dev/loop6 /dev/hda666
echo "D0aZNSNnu6FdAph+zrHt" | losetup -p 0 -e AES128 -K /etc/homekey.gpg /dev/loop4 /dev/hdd666

Above partitions use gpg encrypted key files. Having encrypted files on
encrypted partition may seem little bit silly, but currently -K option is
the easiest way to activate multi-key-v3 mode with more secure MD5 IV
computation.

Here are example lines of /etc/fstab file. It's not necessary to give
"loop=/dev/loop4,encryption=AES128" mount options as loop devices are
already losetup'ed and there is no need for mount program to do that again.

    /dev/loop5   /       ext2   defaults   0   1
    /dev/loop6   none    swap   sw         0   0
    /dev/loop4   /home   ext2   defaults   0   2

In above example, device /dev/hda666 is used as encrypted swap with fixed
key. If you set up swap with fixed key like in above example, don't forget
to initialize swap space by running "mkswap /dev/loop6" once. /dev/hdd666 is
used as encrypted /home partition. /dev/loop5 is encrypted root partition,
and it set up by /linuxrc program in "initrd" ram-disk.


7.6. Example 6 - Boot from CD-ROM + encrypted root partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is slight variation of above 'encrypting root partition' instructions.
Computer gets booted from read-only CD-ROM and there is no need for any
unencrypted partitions on the hard disk. Boot CD-ROM is not used after boot
and can be removed from CD drive. This example uses isolinux bootloader
(http://www.kernel.org/pub/linux/utils/boot/syslinux/)

1-6) Same as above 'encrypting root partition' steps 1-6.

7)  Copy kernel version specific loop.o or loop.ko module to CD-ROM source
    directory

        rm -r -f /boot/iso/modules-*
        mkdir -p /boot/iso/modules-2.4.22aa1
                                   ^^^^^^^^^
        cp -p /lib/modules/2.4.22aa1/block/loop.o /boot/iso/modules-2.4.22aa1/
                           ^^^^^^^^^                                ^^^^^^^^^
    OR
        rm -r -f /boot/iso/modules-*
        mkdir -p /boot/iso/modules-2.6.21.1
                                   ^^^^^^^^
        cp -p /lib/modules/2.6.21.1/extra/loop.ko /boot/iso/modules-2.6.21.1/
                           ^^^^^^^^                                 ^^^^^^^^
8-9) Same as above 'encrypting root partition' steps 8-9, with exception
    that in step 9 you must write rootkey.gpg to /boot/iso directory instead
    of /boot directory.

10a) Contents of /boot/initrd.conf configuration file are below.

    BOOTDEV=/dev/hdc                    # CD-ROM device
    BOOTTYPE=iso9660
    CRYPTROOT=/dev/hda2
    ROOTTYPE=ext2
    CIPHERTYPE=AES128
    DESTINATIONPREFIX=/boot/iso
    INITRDGZNAME=initrd.gz
    LOADNATIONALKEYB=1

    devfs enabled kernel users (CONFIG_DEVFS_FS=y and CONFIG_DEVFS_MOUNT=y
    in kernel configuration) need to pay special attention to comments above
    these build-initrd.sh options: USEDEVFS, BOOTDEV, CRYPTROOT and
    EXTERNALGPGDEV.

10b) Copy your national keyboard layout to CD-ROM source directory in
    uncompressed form.

        dumpkeys >/boot/iso/default.kmap

11) Contents of /boot/iso/isolinux.cfg configuration file are below.
    isolinux.cfg is the configuration file for isolinux. For your
    convenience you can pass instructions to isolinux via isolinux.cfg
    instead of typing them when booting.

    default linux
    timeout 100
    prompt 1
    label linux
    kernel vmlinuz
    append initrd=initrd.gz root=100 init=/linuxrc rootfstype=minix

12) Build new /boot/iso/initrd.gz

        ./build-initrd.sh /boot/initrd.conf

13a) Copy isolinux bootloader to CD-ROM source directory. This example uses
    version 3.08 that was extracted to /usr/src directory earlier, but there
    is no special reason to use that version. Use another version if you
    prefer.

        cp /usr/src/syslinux-3.08/isolinux.bin /boot/iso

13b) Copy kernel to CD-ROM source directory.

        cp /boot/vmlinuz /boot/iso

13c) Create boot CD-ROM image

        mkisofs -b isolinux.bin -c boot.cat -no-emul-boot -boot-load-size 4 \
            -r -boot-info-table /boot/iso >/boot/bootcdimage.iso

13d) Burn /boot/bootcdimage.iso to CD-R. Resulting CD-ROM is your boot
    CD-ROM that you use to boot to encrypted root, not the rescue CD-ROM
    referred to in above 'encrypting root partition' step 14.

    You may want to burn two copies or at least archive bootcdimage.iso to
    some unencrypted partition so that you can burn new copy if original
    CD-ROM gets damaged.

13e) Temporarily disable swap partitions and put a "temporary file system on
    swap" into one of swap partitions. This example assumes that /dev/hda3
    is such swap partition. The 'dd' command clears first 64KB of that
    partition so that dangerously buggy rescue floppies/CD-ROMs don't enable
    swap on it.

        swapoff -a -v
        dd if=/dev/zero of=/dev/hda3 bs=64k count=1 conv=notrunc
        mkfs -t ext2 /dev/hda3
        mount -t ext2 /dev/hda3 /mnt

13f) Copy statically linked aespipe and gpg programs and rootkey.gpg file to
    "temporary file system on swap" partition.

        cp -p /boot/aespipe /boot/iso/rootkey.gpg /usr/bin/gpg /mnt
        umount /mnt

14-20) Same as above 'encrypting root partition' steps 14-20, with exception
    that in step 19 you must rw mount (no -r option to mount) "temporary