Contents of /upstream/ciphers/current/README

Written by Jari Ruusu <jariruusu@users.sourceforge.net>, November 29 2003

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

New versions are announced to linux-crypto mailing list:                       

    http://mail.nl.linux.org/linux-crypto/
    http://marc.theaimsgroup.com/?l=linux-crypto


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