Contents of /upstream/ciphers/current/README

Written by Jari Ruusu <jariruusu@users.sourceforge.net>, November 27 2004

Copyright 2002,2003,2004 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://members.tiscali.fi/ce6c8edf/      (limited downloads)

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:linux-crypto-request@nl.linux.org?Subject=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.
1	max	479	Written by Jari Ruusu <jariruusu@users.sourceforge.net>, November 27 2004
2	max	30
3	max	174	Copyright 2002,2003,2004 by Jari Ruusu.
4	max	30	Redistribution of this file is permitted under the GNU Public License.
5
6
7			Table of Contents
8			~~~~~~~~~~~~~~~~~
9			1. General information
10			2. Instructions for building loop cipher modules
11			3. Testing loop cipher modules
12			4. Cipher names that are available to losetup and mount programs
13			5. Example
14			6. Compatibility with other loop encryption implementations
15	max	36	7. Files
16	max	30
17
18			1. General information
19			~~~~~~~~~~~~~~~~~~~~~~
20			These cipher modules are intended to be used in combination with loop-AES
21	max	479	version v3.0a or later and linux kernel versions 2.2 or later.
22	max	30
23	max	319	Twofish and serpent ciphers can be used in either multi-key or single-key
24			mode, but blowfish cipher can be used only in single-key mode.
25
26	max	30	Latest version of this package can be found at:
27
28			http://loop-aes.sourceforge.net/
29	max	174	http://members.tiscali.fi/ce6c8edf/ (limited downloads)
30	max	30
31	max	36	New versions are announced to linux-crypto mailing list:
32	max	30
33			http://mail.nl.linux.org/linux-crypto/
34	max	281	http://www.spinics.net/lists/crypto/
35	max	30
36	max	281	List-subscribe: <mailto:linux-crypto-request@nl.linux.org?Subject=subscribe>
37	max	30
38	max	281
39	max	30	2. Instructions for building loop cipher modules
40			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41			To compile and install loop cipher modules, as root, use commands:
42
43			make clean
44			make
45
46			Makefile tries to locate running kernel source directory, steal definitions
47			from kernel Makefile, and build versions that match your running kernel.
48			Following directories are tried, in this order:
49
50	max	357	/lib/modules/`uname -r`/source
51	max	30	/lib/modules/`uname -r`/build
52			/usr/src/linux
53			/usr/src/linux-`uname -r`
54			/usr/src/kernel-source-`uname -r`
55
56			You can override automatic kernel source directory detection by specifying
57			LINUX_SOURCE like this: make LINUX_SOURCE=/usr/src/linux-2.2.20aa1
58
59	max	357	Both LINUX_SOURCE and KBUILD_OUTPUT must be specified when compiling for
60			2.6.x kernel with separate object directory.
61
62	max	319	You can disable automatic module installation and creation of module
63			dependencies by specifying MODINST=n RUNDM=n on make command line.
64
65	max	30	Automatic kernel source directory detection is not foolproof. For best
66			results, always specify LINUX_SOURCE, especially if modules appear to
67			compile for wrong kernel. Observe last five lines of make output for clues.
68
69			You can override default installation root directory by specifying
70			INSTALL_MOD_PATH like this: make INSTALL_MOD_PATH=/path/to/destination/root
71
72
73			3. Testing loop cipher modules
74			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75			Run this command, as root, and Makefile will run series of tests.
76
77			make tests
78
79			Makefile will display "* Test results ok *" message if tests are
80			completed successfully. If tests fail, do not use these modules as they are
81			broken.
82
83	max	36	If gpg isn't available, then tests that involve decrypting gpg encrypted key
84			files will fail. You can skip gpg key file tests by specifying
85			TEST_GPG_TYPES=n on make command line.
86	max	30
87	max	36
88	max	30	4. Cipher names that are available to losetup and mount programs
89			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90			loop_twofish.o : twofish128 twofish160 twofish192 twofish256
91			loop_blowfish.o : blowfish128 blowfish192 blowfish256
92			loop_serpent.o : serpent128 serpent192 serpent256
93
94	max	36	2.6 kernels use .ko extension for kernel modules, so module names will be
95			loop_twofish.ko, loop_blowfish.ko and loop_serpent.ko on those kernels.
96	max	30
97	max	36
98	max	30	5. Example
99			~~~~~~~~~~
100			This example shows how to create an ext2 file system on encrypted hard disk
101			partition. This example uses a fictious partition /dev/hda666 for storage
102	max	36	and fictious directory /mnt666 as mount point.
103	max	30
104	max	479	Create 65 random encryption keys and encrypt those keys using gpg. Reading
105	max	36	from /dev/random may take indefinitely long if kernel's random entropy pool
106			is empty. If that happens, do some other work on some other console (use
107			keyboard, mouse and disks). Use of gpg-encrypted key file depends on
108			encrypted swap.
109
110			umask 077
111	max	479	head -c 2925 /dev/random \| uuencode -m - \| head -n 66 \| tail -n 65 \
112	max	36	\| gpg --symmetric -a >/etc/fskey2.gpg
113
114			Fill the partition with random looking data. "dd" command may take a while
115			to execute if partition is large.
116
117			head -c 15 /dev/urandom \| uuencode -m - \| head -n 2 \| tail -n 1 \
118			\| losetup -p 0 -e AES128 /dev/loop0 /dev/hda666
119			dd if=/dev/zero of=/dev/loop0 bs=4k conv=notrunc 2>/dev/null
120	max	30	losetup -d /dev/loop0
121
122			Add this to your /etc/fstab file:
123
124	max	36	/dev/hda666 /mnt666 ext2 defaults,noauto,loop=/dev/loop0,encryption=serpent128,gpgkey=/etc/fskey2.gpg 0 0
125	max	30
126	max	36	The "losetup -F" command asks for passphrase to unlock your key file.
127			Losetup -F option reads loop related options from /etc/fstab. Partition name
128			/dev/hda666, encryption=serpent128 and gpgkey=/etc/fskey2.gpg come from
129			/etc/fstab.
130
131			modprobe loop_serpent
132			losetup -F /dev/loop0
133			mkfs -t ext2 /dev/loop0
134			losetup -d /dev/loop0
135			mkdir /mnt666
136
137	max	30	Now you should be able to mount the file system like this. The "mount"
138			command asks for your encryption password.
139
140	max	36	modprobe loop_serpent
141	max	30	mount /mnt666
142
143			And unmount it like this:
144
145			umount /mnt666
146
147			Or without modifying /etc/fstab, you can mount and and unmount file system
148			like this:
149
150	max	36	modprobe loop_serpent
151			mount -t ext2 /dev/hda666 /mnt666 -o loop=/dev/loop0,encryption=serpent128,gpgkey=/etc/fskey2.gpg
152	max	30	umount /mnt666
153
154			Or fsck, mount and unmount like this. Losetup -F option reads loop related
155	max	36	options from /etc/fstab. Partition name /dev/hda666, encryption=serpent128
156			and gpgkey=/etc/fskey2.gpg come from /etc/fstab.
157	max	30
158	max	36	modprobe loop_serpent
159			losetup -F /dev/loop0
160	max	30	fsck -t ext2 -f -y /dev/loop0
161			mount -t ext2 /dev/loop0 /mnt666
162			umount /mnt666
163			losetup -d /dev/loop0
164
165
166			6. Compatibility with other loop encryption implementations
167			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168	max	36	To use serpent, AES, twofish, or blowfish disk images encrypted using
169			kerneli.org 512-byte-IV version (which uses RIPE-MD160 as password hash),
170			use commands like these:
171	max	30
172			losetup -e twofish128 -H rmd160 /dev/loop0 /dev/hda9
173			or ^^^^^^^^^
174			mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=twofish128,phash=rmd160
175			^^^^^^^^^^^^
176	max	36	Serpent module interprets loinit=2 option as "big-endian" flag. To use
177			incorrect big-endian serpent disk images, use commands like these:
178	max	30
179	max	36	losetup -e serpent128 -I 2 /dev/loop0 /dev/hda9
180	max	30	or ^^^^
181	max	36	mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=serpent128,loinit=2
182	max	30	^^^^^^^^
183			Blowfish module interprets loinit=1 option as "bug-compatible" flag. To use
184			mutated-little-endian blowfish disk images encrypted using kerneli.org
185			512-byte-IV version, use commands like these:
186
187			losetup -e blowfish128 -H rmd160 -I 1 /dev/loop0 /dev/hda9
188			or ^^^^^^^^^ ^^^^
189			mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=blowfish128,phash=rmd160,loinit=1
190			^^^^^^^^^^^^ ^^^^^^^^
191	max	479	Twofish module interprets loinit=1 option as "SUSE-compatible" flag. To use
192			twofish disk images encrypted using SUSE-kernel-twofish version (which uses
193	max	30	constant IV for each 512 byte sector), use commands like these:
194
195			losetup -e twofish160 -H rmd160 -I 1 /dev/loop0 /dev/hda9
196			or ^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^
197			mount -t ext2 /dev/hda9 /mnt9 -o loop,encryption=twofish160,phash=rmd160,loinit=1
198			^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^
199
200	max	36	7. Files
201	max	30	~~~~~~~~
202			ChangeLog History of changes and public releases.
203
204			Makefile Makefile to build and install loop cipher
205			modules.
206
207			README This README file.
208
209	max	357	dkms.conf Configuration file for Dynamic Kernel Module
210			Support. http://linux.dell.com/dkms/dkms.html
211			for more info.
212
213	max	479	gpgkey[123].asc gpg encrypted key files that are used by
214	max	36	Makefile when "make tests" command is run. These
215			key files are encrypted with symmetric cipher
216			using 12345678901234567890 password.
217
218	max	30	loop_blowfish.c Loop cipher module that provides blowfish
219			encryption.
220
221			loop_serpent.c Loop cipher module that provides serpent
222			encryption.
223
224			loop_twofish.c Loop cipher module that provides twofish
225			encryption.