Contents of /upstream/ciphers/current/README

Written by Jari Ruusu <jariruusu@users.sourceforge.net>, May 8 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 v2.0b or later and linux kernel versions 2.2 or later.

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`/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.

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 64 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 2880 /dev/random | uuencode -m - | head -n 65 | tail -n 64 \
        | 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.

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