readme

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

linked to form a new loop.o driver (loop.ko on 2.6 kernels) that is
installed in /lib/modules/`uname -r`/block (2.4 and older kernels) or
/lib/modules/`uname -r`/extra (2.6 kernels) directory. AES cipher is
permanently glued to loop.o driver so that when loop.o is loaded it
automagically has AES support built in. There is no need to define any
aliases in /etc/modules.conf file.

To compile and install loop.o driver, as root, use commands:

    cd /PATH/TO/LOOP-AES
    make clean
    make

Makefile tries to locate running kernel source directory, steal definitions
from kernel Makefile, and build a version that matches your running kernel.
Following directories are tried, in this order:

    /lib/modules/`uname -r`/source
    /lib/modules/`uname -r`/build
    /usr/src/linux
    /usr/src/linux-`uname -r`
    /usr/src/kernel-source-`uname -r`

You can override automatic kernel source directory detection by specifying
LINUX_SOURCE like this:  make LINUX_SOURCE=/usr/src/linux-2.4.22aa1

Both LINUX_SOURCE and KBUILD_OUTPUT must be specified when compiling for
2.6.x kernel with separate object directory.

You can disable automatic module installation and creation of module
dependencies by specifying MODINST=n on make command line.

Automatic kernel source directory detection is not foolproof. For best
results, always specify LINUX_SOURCE, especially if loop.o module appears to
compile for wrong kernel. Observe last five lines of make output for clues.

If you are upgrading your kernel and you need loop.o module during boot, you
probably need to build new version of loop.o module that matches your new
kernel *before* you boot the new kernel. To build loop.o module for other
kernel than running kernel, you *must* specify LINUX_SOURCE parameter to
make.

You can override default installation root directory by specifying
INSTALL_MOD_PATH like this:  make INSTALL_MOD_PATH=/path/to/destination/root

Makefile detects processor type from kernel configuration. If selected
processor type is x86 processor or AMD64 processor, optimized assembler
implementations of AES and MD5 are used instead of C implementations. If you
want to unconditionally disable x86 assembler AES and MD5 implementations,
specify X86_ASM=n on make command line. If you want to unconditionally
disable AMD64 assembler AES and MD5 implementations, specify AMD64_ASM=n on
make command line.

If you want to enable AES encryption key scrubbing, specify KEYSCRUB=y on
make command line. Loop encryption key scrubbing moves and inverts key bits
in kernel RAM so that the thin oxide which forms the storage capacitor
dielectric of DRAM cells is not permitted to develop detectable property.
For more info, see Peter Gutmann's paper:
http://www.cypherpunks.to/~peter/usenix01.pdf

If you want enable VIA padlock hardware AES xcrypt instructions, specify
PADLOCK=y on make command line. If enabled, presence of VIA padlock
instructions is detected at run time, but code still works on non-padlock
processors too.

Twofish, serpent, and blowfish loop cipher modules are also available, but
they are not built by default. Add EXTRA_CIPHERS=y parameter to make command
line if you want them built and installed. Prior to loop-AES-v3.2a, these
modules were on separate 'ciphers' package. Due to versioned symbol build
difficulties on 2.6 kernels involving two separately built kernel module
packages, these modules are now merged to loop-AES, and are now built from
one package. If you have applied loop-AES kernel patch to your kernel
sources and have loop driver built-in to your kernel and want to build only
twofish serpent and blowfish ciphers without building a new loop driver,
then you can add BUILD_LOOP=n parameter to make command. Currently, twofish
serpent and blowfish don't do encryption key scrubbing, so KEYSCRUB=y make
parameter has no effect on them.

Note: If your patch program is very old, it may not understand the --dry-run
option, and may puke lengthy error messages. Even if that happens, the build
process should still produce a working loop driver.


4. Instructions for building new mount, umount, losetup, swapon and swapoff
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to support AES and other ciphers, mount, umount, losetup, swapon
and swapoff need to be patched and recompiled. A patch is included. Mount,
umount, losetup, swapon and swapoff sources are in util-linux package which
you can get from:

    http://www.kernel.org/pub/linux/utils/util-linux/

Or alternatively, if your distro is using util-linux-ng version:

    http://www.kernel.org/pub/linux/utils/util-linux-ng/

Do *not* install all the utilities in the util-linux package without
thinking. You may ruin your system if you do that. Read the INSTALL file
provided with util-linux tarball.

These commands, as root user, will recompile and install mount, umount,
losetup, swapon, swapoff and their man pages:

    bzip2 -d -c util-linux-2.12r.tar.bz2 | tar xvf -
    cd util-linux-2.12r
    patch -p1 </PATH/TO/LOOP-AES/util-linux-2.12r.diff
    CFLAGS=-O2 ./configure
    make SUBDIRS="lib mount"

Or alternatively, if your distro is using util-linux-ng version:

    bzip2 -d -c util-linux-ng-2.13.0.1.tar.bz2 | tar xvf -
    cd util-linux-ng-2.13.0.1
    patch -p1 </PATH/TO/LOOP-AES/util-linux-ng-2.13.0.1.diff
    CFLAGS="-O2 -Wall" ./configure
    make SUBDIRS=mount

For either version of util-linux:

    cd mount
    install -m 4755 -o root mount umount /bin
    install -m 755 losetup swapon /sbin
    rm -f /sbin/swapoff && ( cd /sbin && ln -s swapon swapoff )
    rm -f /usr/share/man/man8/{mount,umount,losetup,swapon,swapoff}.8.gz
    install -m 644 mount.8 umount.8 losetup.8 /usr/share/man/man8
    install -m 644 swapon.8 swapoff.8 /usr/share/man/man8
    rm -f /usr/share/man/man5/fstab.5.gz
    install -m 644 fstab.5 /usr/share/man/man5
    mandb
    cd ../..

Debian users may want to put mount package on hold like this:

    echo mount hold | dpkg --set-selections


5. Instructions for building new gpg
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When gpg encrypts data with symmetric cipher only or when gpg encrypts
secret keyring keys with secret passphrase, gpg uses seeded (salted) and
iterated key setup. However, default amount of iteration is tuned for slow
processors and can be increased for better resistance against dictionary
attacks. Larger key iteration makes key setup much slower, but also makes
dictionary attacks much slower too.

Included optional gpg patch makes default gpg password iteration 128 times
slower. gpg stores new iteration value along with seed bytes into symmetric
cipher encrypted output file or secret keyring, so unpatched gpg versions
will read and decrypt the data just fine.

If you are using gpg version 1.4.6 or later you achieve same increased
password iteration effect without recompiling new gpg binary by setting this
option in your options file ~/.gnupg/gpg.conf

    s2k-count 8388608

Or alternatively... You can use this gpg command line parameter:

    --s2k-count 8388608

gpg sources are available from:

    ftp://ftp.gnupg.org/gcrypt/gnupg/

These commands, as root user, will recompile and install gpg and gpgv and
their man pages:

    bzip2 -d -c gnupg-1.4.7.tar.bz2 | tar xvf -
    cd gnupg-1.4.7
    patch -p1 </PATH/TO/LOOP-AES/gnupg-1.4.7.diff
    CFLAGS="-O2" LDFLAGS="-static -s" ./configure --prefix=/usr --enable-static-rnd=linux
    make
    rm -f /usr/share/man/man1/{gpg,gpgv}.1.gz
    make install
    chown root:root /usr/bin/gpg
    chmod 4755 /usr/bin/gpg
    cd ..

Note: Above instructions create statically linked version of gpg. Static
linking is necessary if you ever decide to encrypt your root partition.

If /usr/bin directory is not on your root partition, then it is necessary to
move gpg to /bin directory on your root partition:

    cd /usr/bin
    mv gpg ../../bin
    ln -s ../../bin/gpg gpg

Debian users may want to put gnupg package on hold like this:

    echo gnupg hold | dpkg --set-selections


6. Testing the loop.o driver and losetup program
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run these commands, as root, and Makefile will run series of tests.

    cd /PATH/TO/LOOP-AES
    make tests

By default, 'make tests' command uses /dev/loop7 device to test loop driver.
If that device is not available and/or you want to specify different
default, you can add TLD=/dev/loop0 parameter to make command.

If you chose to build twofish, serpent, and blowfish ciphers, and want to
test them in addition to AES cipher, then add EXTRA_CIPHERS=y parameter to
'make tests' command line. Like this:

    cd /PATH/TO/LOOP-AES
    make tests EXTRA_CIPHERS=y

Makefile will display "*** Test results ok ***" message if tests are
completed successfully. If tests fail, do not use the driver as it is
broken.

If gpg isn't available, then tests that involve decrypting gpg encrypted key
files will fail. You can skip gpg key file tests by specifying
TEST_GPG_TYPES=n on make command line.


7. Examples
~~~~~~~~~~~
Many of following examples depend on gpg encrypted key file. gpg appears to
prevent its own keys from being leaked to swap, but does not appear to
prevent data handled by it from being leaked to swap. In gpg encrypted key
file cases, the data handled by gpg are loop encryption keys, and they may
leak to swap. Therefore, use of gpg encrypted key file depends on encrypted
swap.

When using gpg encrypted key file, the password that is used to encrypt the
key file is the password that losetup and mount programs want. losetup and
mount programs run gpg to decrypt the key file, and pipe the password to
gpg. gpg then decrypts the file and pipes the real loop keys back to losetup
or mount program.

Many of following examples need uuencode program. Not all boxes have it
installed by default. If you need to install uuencode program, it is usually
part of sharutils package.

Many of following examples attempt to use loop in multi-key-v3 mode and thus
*require* losetup/mount programs from loop-AES-v3.0a or later. Setting up
multi-key-v3 gpg key-file and using that key-file with old single-key or
multi-key-v2 aware losetup/mount programs is *dangerous*. In multi-key loop
cases "losetup -a" command run by root user should output "multi-key-v3"
indicating that loop is really in multi-key-v3 mode. If no "multi-key-v3"
string shows up, your loop setup is a time bomb. If you later upgrade your
losetup/mount programs to version that can understand multi-key-v3 mode,
those new losetup/mount programs will correctly setup loop in multi-key-v3
mode instead of single-key or multi-key-v2 mode, and you may not be able to
access your data any more. New losetup/mount programs are compatible with
old single-key and multi-key-v2 key-files. New losetup/mount programs will
recognize single-key or multi-key-v2 key-files and set up loop in
appropriate mode in those cases. Old single-key or multi-key-v2 aware
losetup/mount programs need old examples. None of the following gpg key-file
examples are such.


7.1. Example 1 - Encrypting swap on 2.4 and newer kernels
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Device backed (partition backed) loop is capable of encrypting swap on 2.4
and newer kernels. File backed loops can't be used for swap.

First, run "swapoff -a" to turn off swap devices in your /etc/fstab file.
Second, add "loop=/dev/loop?" and "encryption=AES128" options to swap lines
in your /etc/fstab file. Example:

 /dev/hda666   none   swap   sw,loop=/dev/loop6,encryption=AES128   0   0
                                ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Third, there may be old unencrypted data on your swap devices, in which case
you can try to overwrite that data with command like this:

    dd if=/dev/zero of=/dev/hda666 bs=64k conv=notrunc
    mkswap /dev/hda666

Fourth, run "swapon -a" and "rm -rf /var/log/ksymoops" and you are done.

Running "swapon -a" will set up loop devices using random keys, run mkswap
on them, and enable encrypted swap on specified loop devices. Usually your
distro's startup scripts will run the "swapon -a" command so you don't need
to change your startup scripts at all. As expected, "swapoff -a" will tear
down such loop devices.

Removing /var/log/ksymoops directory is often required because some versions
of modprobe (part of modutils package) try to log loaded modules to
/var/log/ksymoops/*.log files. This is bad because swap is often enabled
(and loop.o modprobe'd to kernel) before any partitions are mounted
writable. Without /var/log/ksymoops directory on root partition, modprobe
will not try to log loaded modules, and you won't see annoying error
messages.

Note: If you are using encrypted swap and you are upgrading your kernel, you
probably need to build new version of loop.o module that matches your new
kernel *before* you boot the new kernel. See "Instructions for building
loop.o driver" section for more details.