readme

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

    file system on swap" /dev/hda3 instead of /boot partition.

21) Clean up and reboot your computer. The 'dd' command attempts to
    overwrite gpg encrypted root partition key file and 'mkswap' command
    restores "temporary file system on swap" /dev/hda3 back to swap usage.

        dd if=/dev/zero of=/mnt/rootkey.gpg bs=64k count=1 conv=notrunc
        umount /mnt
        sync
        mkswap /dev/hda3
        sync
        reboot

If you are upgrading kernel of a system where root partition is already
encrypted, only steps 5 to 7 and 13a to 13d are needed. However, if you are
upgrading from 2.4 kernel to 2.6 kernel, new insmod may need to be copied to
/boot/iso directory by running step 12 before running step 13a.


7.7. Example 7 - Boot from USB-stick + encrypted root partition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is slight variation of above 'encrypting root partition' instructions.
This example, originally from Peter Land, shows how to prepare an USB-stick
to boot an encrypted root partition. Kernel, keyfiles and other files needed
to access encrypted root partition are stored on removable USB-stick. All
hard disk partitions can be encrypted. This example uses syslinux bootloader
(http://www.kernel.org/pub/linux/utils/boot/syslinux/) and FAT formatted
USB-stick.

In this example, many files are written to /boot directory which can be on
encrypted root partition. In later step, files are copied from /boot to
USB-stick so that USB-stick can be removed after booting has completed.

0)  Check your mainboard user's manual. Make sure that your BIOS is able to
    boot from USB-sticks. Make sure that you have a 16 MB or larger
    USB-stick. Both USB 1.1 and USB 2.0 versions should work. Plug in the
    stick, turn on the PC and inspect your BIOS. Try to specify your
    USB-stick as boot device. Turning on "USB device legacy support" in BIOS
    setup may help to make it work.

1-9) Same as above 'encrypting root partition' steps 1-9, except that on
    step 5, kernel has to fulfill all prerequisites from normal loop-aes
    plus those for accessing USB storage devices and FAT filesystems. Kernel
    config items of interest: 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_SCSI=y
    CONFIG_BLK_DEV_SD=y CONFIG_USB=y CONFIG_USB_STORAGE=y CONFIG_FAT_FS=y
    CONFIG_MSDOS_FS=y CONFIG_VFAT_FS=y

    Depending on your USB hardware enable one or more of these. If unsure,
    enable all of them: CONFIG_USB_UHCI=y (or CONFIG_USB_UHCI_HCD=y)
    CONFIG_USB_OHCI=y (or CONFIG_USB_OHCI_HCD=y) CONFIG_USB_EHCI_HCD=y

    All kernel subsystems needed by root file system (IDE drivers,
    ext2/ext3/reiserfs/whatever) must be compiled directly into kernel. They
    can't be modules. FAT file system needs these: CONFIG_NLS_CODEPAGE_437=y
    CONFIG_NLS_CODEPAGE_850=y CONFIG_NLS_ISO8859_1=y CONFIG_NLS_ISO8859_15=y
    and these, if available on your kernel: CONFIG_FAT_DEFAULT_CODEPAGE=850
    CONFIG_FAT_DEFAULT_IOCHARSET=iso8859-15

    Accessing files on USB-stick will fail if correct codepage is not
    included in the kernel. For kernel and initrd file names, use short
    MSDOS compliant file names on the USB-stick with no capitals and no
    special characters. Short MSDOS names is syslinux limitation.

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

    BOOTDEV=/dev/sda            # partitionless USB-stick device
    BOOTTYPE=vfat
    CRYPTROOT=/dev/hda2
    ROOTTYPE=ext2
    CIPHERTYPE=AES128
    LOADNATIONALKEYB=1
    INITIALDELAY=3

    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 /boot directory in uncompressed
    form.

        dumpkeys >/boot/default.kmap

11) Contents of /boot/syslinux.cfg configuration file are below.
    syslinux.cfg is the configuration file for syslinux. For your
    convenience you can pass instructions to syslinux via syslinux.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/initrd.gz

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

13a) Prepare USB-stick to act as boot device. For some reason syslinux fails
    to write boot code to MBR on partitioned device. This example uses
    partitionless /dev/sda USB-stick device so that syslinux actually ends
    up writing boot code to MBR. If your USB-stick has pre-existing boot
    code on its MBR, then partitioned device may boot normally without
    syslinux actually writing anything to MBR. Warning: Partitionless
    USB-stick may be unreadable in MS-Windows operating systems.

    First, make sure that the USB-stick is not mounted.

        umount /dev/sda1
        umount /dev/sda

    If it wasn't mounted, just ignore error messages.

13b) Wipe clear first 5 MB of USB-stick device. This clears out existing
    MBR, partition table and beginning of existing file system.

        dd if=/dev/zero of=/dev/sda bs=1024k count=5 conv=notrunc

13c) Write a FAT16 file system to USB-stick device.

        mkfs -t vfat -I /dev/sda

    Syslinux will not work with FAT32 file system.

13d) Copy files from /boot to USB-stick device.

        mount -t vfat /dev/sda /mnt
        cp -pR /boot/* /mnt
        umount /mnt

    If you choose to copy only some of the /boot/* files, copy at least
    these files: vmlinuz (your kernel) initrd.gz syslinux.cfg default.kmap
    rootkey.gpg, and these programs: insmod* loadkeys losetup gpg aespipe,
    and their libraries (lib* ld-linux*), and modules-*/loop.*o file for
    your kernel. The "./build-initrd.sh /boot/initrd.conf" run in earlier
    step showed what files that script copied to /boot. Same files are
    needed on the USB-stick.

13e) Install syslinux on FAT16 formatted USB-stick device.

        syslinux /dev/sda
        sync

14-21) Same as above 'encrypting root partition' steps 14-21, with exception
    that in step 19 you must mount your USB-stick /dev/sda (file system type
    is vfat) instead of /boot partition.

If you are upgrading kernel of a system where root partition is already
encrypted, only steps 5 to 7 and 13d to 13e are needed. 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 13d.


7.8. Example 8 - Encrypted partition using serpent cipher
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example shows how to create an ext2 file system on serpent encrypted
hard disk partition. This example uses a fictitious partition /dev/hda666
for storage and fictitious directory /mnt666 as mount point.

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 >/etc/fskey2.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

Add this to your /etc/fstab file:

 /dev/hda666 /mnt666 ext2 defaults,noauto,loop=/dev/loop0,encryption=serpent128,gpgkey=/etc/fskey2.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=serpent128 and gpgkey=/etc/fskey2.gpg come from
/etc/fstab.

    modprobe loop_serpent
    losetup -F /dev/loop0
    mkfs -t ext2 /dev/loop0
    losetup -d /dev/loop0
    mkdir /mnt666

Now you should be able to mount the file system like this. The "mount"
command asks for your encryption password.

    modprobe loop_serpent
    mount /mnt666

And unmount it like this:

    umount /mnt666

Or without modifying /etc/fstab, you can mount and and unmount file system
like this:

    modprobe loop_serpent
    mount -t ext2 /dev/hda666 /mnt666 -o loop=/dev/loop0,encryption=serpent128,gpgkey=/etc/fskey2.gpg
    umount /mnt666

Or fsck, mount and unmount like this. Losetup -F option reads loop related
options from /etc/fstab. Partition name /dev/hda666, encryption=serpent128
and gpgkey=/etc/fskey2.gpg come from /etc/fstab.

    modprobe loop_serpent
    losetup -F /dev/loop0
    fsck -t ext2 -f -y /dev/loop0
    mount -t ext2 /dev/loop0 /mnt666
    umount /mnt666
    losetup -d /dev/loop0


8. Security levels
~~~~~~~~~~~~~~~~~~
Loop encryption key can be set up in different ways. Just in case it isn't
obvious how these different ways rank security wise, here is a list of
security levels from 1 (highest security) to 4 (lowest security).

1)  gpg encrypted multi-key-v3 or multi-key-v2 key file and/or gpg
    public+private keys are stored on separate removable USB-stick that is
    not available to attacker. If USB-stick and its key files are available
    to attacker, security level is equivalent to level 2. (Examples 2 and 7)

2)  gpg encrypted multi-key-v3 or multi-key-v2 key file and gpg
    public+private keys are stored on disk that is available to attacker.
    This assumes that included gpg patch is applied to gpg and symmetric
    cipher encrypted key file or private keyring password was
    created/changed with patched version. (Example 3)

3)  Loop is used in single-key mode. Random password seed and iteration
    count are used to slow down optimized dictionary attacks. This level is
    vulnerable to watermark attacks. Watermarked files contain special bit
    patterns that can be detected without decryption.

4)  Loop is used in single-key mode. Neither password seed nor gpg encrypted
    key file are used. This level is vulnerable to optimized dictionary
    attacks as well as watermark attacks. (mainline linux cryptoloop is
    example of this type of backdoored crypto)


9. Performance tuning for 2.4 and newer kernels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Loop-AES driver for 2.4 and newer kernels understand two additional options:
lo_prealloc and lo_nice. First number of 'lo_prealloc' is the default number
of RAM pages to pre-allocate for each device backed (partition backed) loop.
Every configured device backed loop pre-allocates this amount of RAM pages
unless later 'lo_prealloc' numbers provide an override. 'lo_prealloc'
overrides are defined in pairs: loop_index,number_of_pages. If 'lo_prealloc'
is undefined, all pre-allocations default to 125 pages. A maximum of four
overrides (four number pairs) can be used.

This example line added to your /etc/modules.conf file (2.4 kernels) or
/etc/modprobe.conf file (2.6 kernels) means that each device backed loop
device pre-allocates 100 pages of RAM at losetup/mount time, except that
/dev/loop6 allocates 200 pages, and /dev/loop5 allocates 250 pages.

    options loop lo_prealloc=100,6,200,5,250

On x86 systems page size is 4 Kbytes, some other architectures have 8 Kbyte
page size.

lo_nice option sets scheduler nice for loop helper threads. Values between 0
(low priority) to -20 (high priority) can be used. If loop transfers are
disk transfer rate limited, lowering loop thread priority may improve
performance. If loop transfers are CPU processing power limited, increasing
loop thread priority may improve performance. renice(8) command can be used
to alter nice values of loop helper threads while loop is being used.
Example /etc/modules.conf or /etc/modprobe.conf line:

    options loop lo_nice=-4

If lo_nice is not set, default nice value for kernels with old scheduler is
-20. For kernels with O(1) scheduler, default nice value is -1.

2.6 kernels include anticipatory, CFQ and deadline I/O schedulers. Deadline
I/O scheduler may improve performance of device backed loop devices.燩lease
read kernel's Documentation/block/as-iosched.txt file for more information.

Soft block size of loop device has negative effect on efficiency and
performance if that soft block size is too small. On recent kernels, default
soft block size is set to such value that full device can be accessed using
X amount of such soft block size chunks. If device size is integer multiple