[ciphers modules have been moved to loop-AES package on 2007-05-15. See loop-AES source and README files for more up to date information.] Written by Jari Ruusu , February 23 2007 Copyright 2002-2007 by Jari Ruusu. Redistribution of this file is permitted under the GNU Public License. Table of Contents ~~~~~~~~~~~~~~~~~ 1. General information 2. Instructions for building loop cipher modules 3. Testing loop cipher modules 4. Cipher names that are available to losetup and mount programs 5. Example 6. Compatibility with other loop encryption implementations 7. Files 1. General information ~~~~~~~~~~~~~~~~~~~~~~ These cipher modules are intended to be used in combination with loop-AES version v3.0a or later and 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. 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: 2. Instructions for building loop cipher modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To compile and install loop cipher modules, as root, use commands: make clean make Makefile tries to locate running kernel source directory, steal definitions from kernel Makefile, and build versions that match 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.2.20aa1 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 RUNDM=n on make command line. Automatic kernel source directory detection is not foolproof. For best results, always specify LINUX_SOURCE, especially if modules appear to compile for wrong kernel. Observe last five lines of make output for clues. You can override default installation root directory by specifying INSTALL_MOD_PATH like this: make INSTALL_MOD_PATH=/path/to/destination/root 3. Testing loop cipher modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Run this command, as root, and Makefile will run series of tests. make tests Makefile will display "*** Test results ok ***" message if tests are completed successfully. If tests fail, do not use these modules as they are 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. 4. 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. 5. Example ~~~~~~~~~~ This example shows how to create an ext2 file system on encrypted hard disk partition. This example uses a fictious partition /dev/hda666 for storage and fictious 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 2925 /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 6. 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 ^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^ 7. Files ~~~~~~~~ ChangeLog History of changes and public releases. Makefile Makefile to build and install loop cipher modules. README This README file. dkms.conf Configuration file for Dynamic Kernel Module Support. http://linux.dell.com/dkms/dkms.html for more info. gpgkey[123].asc gpg encrypted key files that are used by Makefile when "make tests" command is run. These key files are encrypted with symmetric cipher using 12345678901234567890 password. loop_blowfish.c Loop cipher module that provides blowfish encryption. loop_serpent.c Loop cipher module that provides serpent encryption. loop_twofish.c Loop cipher module that provides twofish encryption.