Contents of /upstream/ciphers/current/README

Written by Jari Ruusu <jariruusu@users.sourceforge.net>, May 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 v2.0b 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`/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

You can disable automatic module installation and creation of module
dependencies by specifying MODINST=n RUNDM=n on make command line.

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