readme

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

Written by Jari Ruusu <[e-mail]>, October 25 2007

Copyright 2001-2007 by Jari Ruusu.
Redistribution of this file is permitted under the GNU Public License.


Table of Contents
~~~~~~~~~~~~~~~~~
1.    Loop device primer
2.    General information
2.1.  Key setup and IV modes
2.2.  Use of journaling file systems on loop device
2.3.  Use of offsets and sizelimits
2.4.  Use of software suspend
2.5.  File system soft block sizes
2.6.  Compatibility with earlier versions
2.7.  Other loop ciphers - twofish, serpent, and blowfish
2.8.  Compatibility with other loop encryption implementations
3.    Instructions for building loop.o driver
4.    Instructions for building new mount, umount, losetup, swapon and swapoff
5.    Instructions for building new gpg
6.    Testing the loop.o driver and losetup program
7.    Examples
7.1.  Example 1 - Encrypting swap on 2.4 and newer kernels
7.2.  Example 2 - Partition backed loop with gpg encrypted key file
7.3.  Example 3 - Encrypted partition that multiple users can mount
7.4.  Example 4 - Encrypting /tmp partition with random keys
7.5.  Example 5 - Encrypting root partition
7.6.  Example 6 - Boot from CD-ROM + encrypted root partition
7.7.  Example 7 - Boot from USB-stick + encrypted root partition
7.8.  Example 8 - Encrypted partition using serpent cipher
8.    Security levels
9.    Performance tuning for 2.4 and newer kernels
10.   Files
11.   Credits


1. Loop device primer
~~~~~~~~~~~~~~~~~~~~~
Loop devices are block devices that do not store any data directly but loop
all reads and writes to underlying block device or file, possibly encrypting
and decrypting data in the process. Normally you don't write to a loop
device directly, but set up a file system on it. The file system will then
read from and write to loop device.

By default, 8 loop devices are available: /dev/loop0, /dev/loop1 ...
/dev/loop7 (on devfs /dev/loop/0 ... /dev/loop/7). All devices are
identical, and each can be tied to one real block device or one file on some
file system. You have to decide and allocate which loop to use for which
purpose.

losetup(8) program is used to make and tear down the connection between a
loop device and underlying device or file. You don't have to specify type of
underlying device as loop driver detects that automatically. mount(8),
umount(8), swapon(8) and swapoff(8) programs can also set up and tear down
loop devices.

File backed loops may deadlock under some kernel + file system combinations.
So, if you can choose between device backed and file backed, choose device
backed even if it means that you have to re-partition your disks.


2. General information
~~~~~~~~~~~~~~~~~~~~~~
This package provides loadable Linux kernel module (loop.o or loop.ko on 2.6
kernels) that has AES cipher built-in. The AES cipher can be used to encrypt
local file systems and disk partitions.

Loop device encrypts data but does not authenticate ciphertext. In other
words, it delivers data privacy, but does not guarantee that data has not
been tampered with. Admins setting up encrypted file systems should ensure
that neither ciphertext, nor tools used to access ciphertext (kernel +
kernel modules, mount, losetup, and other utilities) can be trojaned or
tampered.

This package does *not* modify your kernel in any way, so you are free to
use kernels of your choice, with or without cool patches. This package works
with 2.0.x, 2.2.x, 2.4.x (2.4.7 or later) and 2.6.x kernels.

Latest version of this package can be found at:

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

New versions are announced to linux-crypto mailing list:

    http://mail.nl.linux.org/linux-crypto/
    http://www.spinics.net/lists/crypto/

List-subscribe: <mailto:[e-mail]?Subject=subscribe>


2.1. Key setup and IV modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The AES cipher is used in CBC (cipher block chaining) mode. Data is
encrypted and decrypted in 512 byte chains. Three key setup modes are
supported; single-key, multi-key-v2 and multi-key-v3 modes. Single-key mode
uses simple sector IV and one AES key to encrypt and decrypt all sectors in
the loop device. Multi-key-v2 mode uses cryptographically more secure MD5 IV
and 64 different AES keys to encrypt and decrypt sectors in the loop device.
In multi-key mode first key is used for first sector, second key for second
sector, and so on. Multi-key-v3 is same as multi-key-v2 except that it uses
one extra 65th key as additional input to MD5 IV computation.

Recommended key setup mode is multi-key-v3, which is based on gpg encrypted
key files. In this mode, the passphrase is protected against optimized
dictionary attacks via salting and key iteration of gpg. Passphrase length
should be 20 characters or more.

If encryption type is specified as AES128 or AES, gpg decrypted key strings
are hashed with SHA-256, and 128 bit AES encryption is used. If encryption
type is specified as AES192, gpg decrypted key strings are hashed with
SHA-384, and 192 bit AES encryption is used. If encryption type is specified
as AES256, gpg decrypted key strings are hashed with SHA-512, and 256 bit
AES encryption is used.


2.2. Use of journaling file systems on loop device
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Don't use a journaling file system on top of file backed loop device. Device
backed loop device can be used with journaling file systems as device backed
loops guarantee that writes reach disk platters in order required by
journaling file system (write caching must be disabled on the disk drive, of
course). With file backed loop devices, correct write ordering may extend
only to page cache (which resides in RAM) of underlying file system. VM can
write such pages to disk in any order it wishes, and thus break write order
expectation of journaling file system.


2.3. Use of offsets and sizelimits
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
losetup and mount programs support using offset to underlying device or
file. 2.4.x and later kernels also support use of sizelimit that limit size
of device to some subset of full underlying device or file size. Both offset
and sizelimit are specified in bytes. If no offset is specified, zero offset
is used. If no sizelimit is specified, full device/file size is used. If you
do use nonzero offsets, make sure offset is integer multiple of 512 bytes.
Nonzero offsets that are not integer multiple of 512 bytes are NOT supported
as they may be nonportable and/or nonworking.


2.4. Use of software suspend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Encryption keys are kept in kernel RAM while loop is active. Key is
immediately erased when loop is deactivated. Use of suspend-to-disk while
there are active encrypted loops should be used with caution: it would be
really bad security wise because encryption keys are written to disk when
kernel RAM is saved to disk. Once key is written to disk it may be
recoverable from that disk pretty much forever. Security of data encrypted
with such recoverable key is void.


2.5. File system soft block sizes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you intend to move encrypted file system to some other device (CD-ROM for
example), be sure to create file system with soft block size that is integer
multiple of device hard sector size. CD-ROMs have 2048 byte sectors. File
system with 1024 byte soft block size is not going to work with all CD-ROM
drives and/or drivers.


2.6. Compatibility with earlier versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This version is compatible with on-disk formats of all previous relased
versions. This version is compatible with recommended mount, losetup and
swapon command line syntax and /etc/fstab option syntax since
loop-AES-v1.1b.

Unhashed encryption type as created using ancient loop-AES-v1.0c, now needs
'mount -o phash=unhashed1' or 'losetup -H unhashed1' options.

Mount and losetup programs from loop-AES-v2.0g and older accepted unlimited
long passphrase when passphrase was read from a file descriptor using '-p 0'
option. To prevent abuse of mlock()ed RAM by non-root users, mount and
losetup programs from loop-AES-v2.1a and newer limit max passphrase length
to 4094 bytes.

Loop-AES supports three different on-disk formats: v1, v2 and v3. v1 is from
old loop-AES-v1.X versions and it uses a single key to encrypt all data
sectors. v2 is from loop-AES-v2.X versions and it uses 64 keys to encrypt
data sectors. v3 is from loop-AES-v3.X versions and it uses 65 keys, first
64 are used to encrypt data sectors and 65th key is used as additional input
to MD5 IV computation.

So how does loop-AES auto-detect what on-disk format needs to be used? mount
and losetup programs count the keys in encrypted key file:

 1 line of key data    ->  1 key    ->  v1 on-disk format
 64 lines of key data  ->  64 keys  ->  v2 on-disk format
 65 lines of key data  ->  65 keys  ->  v3 on-disk format

Mount and losetup programs from loop-AES-v1.X versions only understand 1 key
keyfiles. Mount and losetup programs from loop-AES-v2.X versions understand
1 or 64 key keyfiles. Mount and losetup programs from loop-AES-v3.X versions
understand 1 or 64 or 65 key keyfiles.

SUPPORTED ON-DISK FORMATS WITH    |      kernel module from loop-AES
DIFFERENT USERPACE/KERNEL VERSIONS|          v1.X   v2.X    v3.X
----------------------------------+---------------------------------
mount+losetup from loop-AES-v1.X  | on-disk-  v1     v1      v1
mount+losetup from loop-AES-v2.X  | on-disk-  v1    v1,v2   v1,v2       
mount+losetup from loop-AES-v3.X  | on-disk-  v1    v1,v2  v1,v2,v3


2.7. Other loop ciphers - twofish, serpent, and blowfish
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These cipher modules work with linux kernel versions 2.2 or later. Twofish
and serpent ciphers can be used in either multi-key or single-key mode, but
blowfish cipher can be used only in single-key mode.

Cipher names that are available to losetup and mount programs:

loop_twofish.o   :  twofish128   twofish160   twofish192   twofish256
loop_blowfish.o  :  blowfish128  blowfish192  blowfish256
loop_serpent.o   :  serpent128   serpent192   serpent256

2.6 kernels use .ko extension for kernel modules, so module names will be
loop_twofish.ko, loop_blowfish.ko and loop_serpent.ko on those kernels.

These extra cipher modules are built only if EXTRA_CIPHERS=y parameter
is present on make command line (see section 3).


2.8. Compatibility with other loop encryption implementations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use serpent, AES, twofish, or blowfish disk images encrypted using
kerneli.org 512-byte-IV version (which uses RIPE-MD160 as password hash),
use commands like these:

    losetup -e twofish128 -H rmd160 /dev/loop0 /dev/hda9
      or                  ^^^^^^^^^
    mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=twofish128,phash=rmd160
                                                                ^^^^^^^^^^^^
Serpent module interprets loinit=2 option as "big-endian" flag. To use
incorrect big-endian serpent disk images, use commands like these:

    losetup -e serpent128 -I 2 /dev/loop0 /dev/hda9
      or                  ^^^^
    mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=serpent128,loinit=2
                                                                ^^^^^^^^
Blowfish module interprets loinit=1 option as "bug-compatible" flag. To use
mutated-little-endian blowfish disk images encrypted using kerneli.org
512-byte-IV version, use commands like these:

    losetup -e blowfish128 -H rmd160 -I 1 /dev/loop0 /dev/hda9
      or                   ^^^^^^^^^ ^^^^
    mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=blowfish128,phash=rmd160,loinit=1
                                                                 ^^^^^^^^^^^^ ^^^^^^^^
Twofish module interprets loinit=1 option as "SUSE-compatible" flag. To use
twofish disk images encrypted using SUSE-kernel-twofish version (which uses
constant IV for each 512 byte sector), use commands like these:

    losetup -e twofish160 -H rmd160 -I 1 /dev/loop0 /dev/hda9
      or    ^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^
    mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=twofish160,phash=rmd160,loinit=1
                                          ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^


3. Instructions for building loop.o driver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you attempt to build loop.o driver (loop.ko on 2.6 kernels), you
*must* configure, compile and install new kernel so that CONFIG_MODULES=y
and CONFIG_BLK_DEV_LOOP=n. Also, CONFIG_KMOD=y is recommended but not
required (kernel 2.0 doesn't have CONFIG_KMOD, set CONFIG_KERNELD=y
instead). Configuring your kernel so that loop driver is built-in
(CONFIG_BLK_DEV_LOOP=y) or module (CONFIG_BLK_DEV_LOOP=m) will *not* work.
After building and installing your new kernel, do not attempt to clean
kernel tree, or rename path to kernel sources.

(Re)configuring and (re)compiling your kernel are required for following
reasons: (1) to disable loop driver in your kernel, (2) to get your kernel
sources to match your running kernel, (3) to get your kernel .config to
match your running kernel, (4) to set up configure time generated links
properly, (5) to generate compile time created header files properly to
match your kernel configuration. Failure to fulfill *all* above requirements
may cause loop.o driver compilation to fail or generate incorrectly
operating code. If you are just upgrading existing loop-AES with newer
version, there is no need to recompile kernel or reboot. Just unmount all
file systems using old loop driver, and remove loop driver from kernel with
rmmod command before compiling new loop driver.

This is how loop.o is compiled and installed:

2.2 and older kernels:  Makefile copies your kernel's loop.c to this
                        directory. Then, Makefile patches that copy with a
                        kernel version specific patch. If patching a copy of
                        your kernel's loop.c fails, then a local copy of
                        known-to-work and patch-able loop.c-2.X.original is
                        used instead.

2.4 and newer kernels:  Makefile copies pre-patched loop.c-2.X.patched to
                        file called patched-loop.c.

Resulting patched-loop.c along with other source files is then compiled and