readme

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

7.2. Example 2 - Partition backed loop with gpg encrypted key file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example, originally from Michael H. Warfield, shows how to create an
ext2 file system on encrypted hard disk partition, and creates 65 random
encryption keys that are encrypted using gpg. Store the key file where ever
you like, on separate removable media, USB-stick, or on a smart card if you
like. You have to have both your passphrase and that key file in order to
mount that file system.

This example uses a fictitious partition /dev/hda666 for storage and
fictitious directory /mnt666 as mount point. A removable USB-stick is
assumed to be (auto-)mounted at /a/usbstick directory.

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.

    head -c 3705 /dev/random | uuencode -m - | head -n 66 | tail -n 65 \
        | gpg --symmetric -a >/a/usbstick/keyfile.gpg

Fill the partition with random looking data. "dd" command may take a while
to execute if partition is large.

    head -c 15 /dev/urandom | uuencode -m - | head -n 2 | tail -n 1 \
        | losetup -p 0 -e AES128 /dev/loop3 /dev/hda666
    dd if=/dev/zero of=/dev/loop3 bs=4k conv=notrunc 2>/dev/null
    losetup -d /dev/loop3

Add this to your /etc/fstab file:

 /dev/hda666 /mnt666 ext2 defaults,noauto,loop=/dev/loop3,encryption=AES128,gpgkey=/a/usbstick/keyfile.gpg 0 0

The "losetup -F" command asks for passphrase to unlock your key file.
Losetup -F option reads loop related options from /etc/fstab. Partition name
/dev/hda666, encryption=AES128 and gpgkey=/a/usbstick/keyfile.gpg come from
/etc/fstab.

    losetup -F /dev/loop3
    mkfs -t ext2 /dev/loop3
    losetup -d /dev/loop3
    mkdir /mnt666

Now you should be able to mount the file system like this. The "mount"
command asks for passphrase to unlock your key file.
    
    mount /mnt666

Check that loop is really in multi-key-v3 mode. Losetup -a output should
include string "multi-key-v3" indicating that loop is really in multi-key-v3
mode. If no "multi-key-v3" string shows up, you somehow managed to mess up
gpg key file generation part or you are trying to use old losetup/mount
programs that only understand single-key or multi-key-v2 modes.

    losetup -a

You can unmount partition like this:

    umount /mnt666

Unmounted filesystem can be fsck'ed like this. -F option reads loop related
options from /etc/fstab. Partition name /dev/hda666, encryption=AES128 and
gpgkey=/a/usbstick/keyfile.gpg come from /etc/fstab.

    losetup -F /dev/loop3
    fsck -t ext2 -f -y /dev/loop3
    losetup -d /dev/loop3

Although mount point directory is not a symbolic link, it should be thought
of as changing symbolic link, where mounting and unmounting changes target
of symbolic link. It matters whether mount point path name is referenced
before or after mount operation. Commands "cd /mnt666 ; mount /mnt666 ; ls"
will show you contents of unencrypted mount point directory, and commands
"mount /mnt666 ; cd /mnt666 ; ls" will show you contents of encrypted file
system directory.


7.3. Example 3 - Encrypted partition that multiple users can mount
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example shows how to create encrypted partition that multiple non-root
users can mount, each with their own gpg key. Non-root users don't have
access to file system keys that are actually used to encrypt data. Root can
add or remove user's permission to mount encrypted partition at any time.
This example uses a fictitious partition /dev/hda666 for storage and
fictitious directory /secret1 as mount point.

Create 65 random file system keys and encrypt those keys using root's gpg
public key. 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 -e -a -r "Superuser" > /root/masterkey-secret1.gpg

Fill the partition with random looking data. "dd" command may take a while
to execute if partition is large.

    head -c 15 /dev/urandom | uuencode -m - | head -n 2 | tail -n 1 \
        | losetup -p 0 -e AES128 /dev/loop0 /dev/hda666
    dd if=/dev/zero of=/dev/loop0 bs=4k conv=notrunc 2>/dev/null
    losetup -d /dev/loop0

Use file system keys to setup /dev/loop0 to partition /dev/hda666 and create
encrypted ext2 file system. The "losetup -e" command asks for root's gpg
passphrase to unlock root's secret gpg key.

    losetup -e AES128 -K /root/masterkey-secret1.gpg /dev/loop0 /dev/hda666
    mkfs -t ext2 /dev/loop0
    losetup -d /dev/loop0
    mkdir /secret1

Add mount information to /etc/fstab file. Something like this:

 /dev/hda666 /secret1 ext2 defaults,user,noauto,encryption=AES128,loop=/dev/loop0,gpgkey=/etc/userkey-secret1.gpg 0 0
                                    ^^^^
You may want to check non-obvious side effects of above "user" mount option.
It's all explained in mount man page.
                                    
Create root-only-readable /etc/userkey-secret1.gpg file which contains file
system key encrypted with each user's public key. List all users as
recipient who should be able to mount /secret1 encrypted partition. Repeat
this every time you want to add or remove users.

    umask 077
    gpg --decrypt < /root/masterkey-secret1.gpg | gpg -e -a --always-trust \
        -r "Superuser" -r "John Doe" -r "Tea Lipton" > /etc/userkey-secret1.gpg

Users can mount encrypted partition like this. mount asks for gpg passphrase
to unlock user's secret gpg key. Each user can use their own gpg key.

    mount /secret1

Root user can check that loop is really in multi-key-v3 mode. Losetup -a
output should include string "multi-key-v3" indicating that loop is really
in multi-key-v3 mode. If no "multi-key-v3" string shows up, you somehow
managed to mess up gpg key file generation part or you are trying to use old
losetup/mount programs that only understand single-key or multi-key-v2
modes.

    losetup -a

You can unmount partition like this:

    umount /secret1

Root user can fsck unmounted filesystem like this. -F option reads loop
related options from /etc/fstab. Partition name /dev/hda666,
encryption=AES128 and gpgkey=/etc/userkey-secret1.gpg come from /etc/fstab.

    losetup -F /dev/loop0
    fsck -t ext2 -f -y /dev/loop0
    losetup -d /dev/loop0


7.4. Example 4 - Encrypting /tmp partition with random keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When mount passphrase hash function is specified as random, mount does not
ask for password but sets up 65 random keys and attempts to put loop to
multi-key mode and creates new file system on that encrypted loop device
before that file system is mounted.

First, unmount your existing /tmp partition by running "umount /tmp". There
may be open files in there, so you may have to do this from single user
mode.

Second, add loop= encryption= and phash=random mount options to /etc/fstab
file. The sixth /etc/fstab field (fs_passno) must be zero so that fcsk will
not attempt to check this partition.

 /dev/hda555 /tmp ext2 defaults,loop=/dev/loop2,encryption=AES128,phash=random/1777 0 0
                                ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^   ^
Third, run "mount /tmp" command and you are done.

Octal digits after phash=random/ mount option specify initial permissions of
file system root directory that gets created on the loop device. 1777 means
read+write+search permissions for all and sticky bit set. Type "man 2 stat"
for more info about what each bit stands for.

Encryption keys and plaintext data on above type mount vanish on unmount or
power off. Using journaled file system in such case does not make much
sense, because file system is re-created with different encryption keys on
each mount, and file system jounal is never used.


7.5. Example 5 - Encrypting root partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Encrypting root partition requires a small unencrypted /boot partition.
Everything else (root, swap and other partitions) can be encrypted. Kernels
and tools required to boot kernels reside in the /boot partition. Included
build-initrd.sh script builds a small "initrd" ram-disk that works with 2.2
2.4, and 2.6 kernels. build-initrd.sh script depends on having minix file
system support in the kernel and working mkfs.minix program binary.
Util-linux includes source for mkfs.minix if you don't have it and need to
build it yourself. You need to temporarily boot from rescue floppy/CD-ROM or
other partition to do the actual encrypting work. The rescue floppy/CD-ROM
or other partition kernel doesn't need to support loop crypto, so just about
anything that boots will work.

1)  build-initrd.sh script needs dietlibc. Dietlibc source is available
    from:

    http://www.fefe.de/dietlibc/
    ftp://ftp.kernel.org/pub/linux/libs/dietlibc/
 
    To compile and install dietlibc, follow instructions in the dietlibc
    README file. For example, on a x86 box, do this:

        make
        install bin-i386/diet /usr/local/bin

2)  You need to use aespipe program (v2.3a or later) with your rescue
    floppy/CD-ROM or other partition. aespipe source is available from:

    http://loop-aes.sourceforge.net/
    http://koti.tnnet.fi/jari.ruusu/linux/

    Download latest version of aespipe-*.tar.bz2

    Dynamically linked aespipe program may have library dependency problems
    with rescue floppy/CD-ROM or other partition C library. To avoid such
    trouble, aespipe program needs to be linked statically. Static linking
    with glibc makes aespipe much bigger (hundreds of kilobytes), and may
    also create link warning about 'getpwuid'. Big program size and link
    warning can be ignored here.

    Compile aespipe program like this:

        CFLAGS="-O2" LDFLAGS="-static -s" ./configure
        make
        make tests
            
    Copy statically linked aespipe program to /boot partition.

        cp -p aespipe /boot

3)  If you followed advise about recompiling and statically linking gpg
    program, you don't need to do that again. However, if you don't have
    statically linked gpg, you need to do that now because later steps in
    root partition encryption depend on it.

4)  Backup all important data before proceeding with root partition
    encryption.

5)  Recompile your kernel. These are required: CONFIG_BLK_DEV_RAM=y
    CONFIG_BLK_DEV_RAM_SIZE=4096 CONFIG_BLK_DEV_INITRD=y CONFIG_MINIX_FS=y
    CONFIG_PROC_FS=y CONFIG_CRAMFS=n (or CONFIG_CRAMFS=m)

    CONFIG_BLK_DEV_{RAM,INITRD}=y are needed because kernel needs to support
    initial ramdisk. CONFIG_MINIX_FS=y is needed because file system on
    initrd is minix. CONFIG_CRAMFS=n is needed because cramfs code may
    incorrectly detect initrd's compressed minix file system as cramfs file
    system. If cramfs must be built-in, then build-initrd.sh must be
    configured with USEPIVOT=1, and kernel parameter "rootfstype=minix" must
    be added to bootloader configuration file. 2.2.x and older kernels have
    neither CONFIG_CRAMFS nor cramfs, so that kernel configuration setting
    can be ignored on those kernels.

    All kernel subsystems needed by root and /boot file systems (IDE
    drivers, ext2/ext3/reiserfs/whatever) must be compiled directly into
    kernel. They can't be modules.

        cd /usr/src/linux-2.4.22aa1
        cp .config ../somewhere/somename.config
        make distclean
        cp ../somewhere/somename.config .config
        make config
        make dep && make clean && make bzImage
        make modules && make modules_install
        cat arch/i386/boot/bzImage >/boot/vmlinuz
        cp System.map /boot/System.map-2.4.22aa1

6)  Compile loop-AES loop.o module for your kernel.

        cd ../loop-AES-*
        make LINUX_SOURCE=/usr/src/linux-2.4.22aa1

7)  Copy kernel version specific loop.o (2.4 and older kernels) or loop.ko
    (2.6 kernels) to /boot/modules-KERNELRELEASE/

        mkdir /boot/modules-2.4.22aa1
                            ^^^^^^^^^
        cp -p /lib/modules/2.4.22aa1/block/loop.o /boot/modules-2.4.22aa1/
                           ^^^^^^^^^                            ^^^^^^^^^
    OR
        mkdir /boot/modules-2.6.21.1
                            ^^^^^^^^
        cp -p /lib/modules/2.6.21.1/extra/loop.ko /boot/modules-2.6.21.1/
                           ^^^^^^^^                             ^^^^^^^^
    Note: You need to have a kernel version specific loop.o or loop.ko