			REQUIREMENTS

The area of applicability of this early version of the script is rather
narrom. Among them are:

	* cryptoswap.sh was written for Debian releases, but I suppose it
	  could be modified to work in other environments if you are 
	  knowledgeable.

	* It assumes that loop, crypto-loop and any cipher used is
	  compiled in, ie is NOT a module.

	* It assumes devfs is present at boot time, however devfs may
	  be either compiled in or a module.

	* It assumes certain programs are available, but the least
	  standard of these is uuencode and that's not a very
	  unusual package.


			INSTALLATION

To install this manually you should do the following

	* build an international crypto enabled kernel with the loop-jari patch

	* Install the script
		cp -a cryptoswap.sh /etc/init.d
		chown root.root /etc/init.d/cryptoswap.sh
		chmod 755 /etc/init.d/cryptoswap.sh
		cd /etc/rcS.d
		ln -s ../init.d/cryptoswap.sh S09cryptoswap
		cd /etc/rc0.d
		ln -s ../init.d/cryptoswap.sh S09cryptoswap
		cd /etc/rc6.d
		ln -s ../init.d/cryptoswap.sh S91cryptoswap

	* Change your swap file entry in /etc/fstab after
	  reading the section below about the cryptoswap
	  options.

	* If you are running devfsd on a nonmodular kernel,
	  disable MODLOAD as discussed below in the section
	  on devfs.



		WHERE TO PLACE IT IN THE BOOT SEQUENCE

During the boot process, cryptoswap.sh must run after devfsd has started but 
before the swapon in checkroot. Since it requires the use of /dev/urandom 
and urandom is not seeded until much later in the rcS boot sequence, we have
to do it ourselves. I've been told it is perfectly safe for the seed file to
be fed to it twice. We can't move the position of rcS.d/S55urandom because
that script has to write back to files in /var/lib/urandom but the root disk
is not yet mounted write-enabled. The write-enable occurs in S10checkroot
after the root drive has been fsck'd. S10checkroot *also* does a swapon -a
because the fsck can be very swap-space hungry.

These facts limit our choices. For security we must have cryptoswap running
before checkroot because otherwise normal swap will be used and fsck will
write cleartext into swap.

We need to remove our softlink and undo any losetup's before shutdown's so
we also have entries late in the sequence of the halt (rc0.d) and reboot
(rc6.d) init levels:

		BOOT:		rcS.d/S09cryptoswap
		HALT:		rc0.d/K91cryptoswap
		REBOOT:		rc6.d/K91cryptoswap


			THE PASSWORD

Not only is the swap space under strong crypto; the password used for it
is also:
		* cryptographically strong
		* used only one time
		* never recorded. The user couldn't give it away if their
		  very life depended on it.

Once the swap space is dismounted, it can never be viewed again. The
next boot will start with a clean slate and a new one time password.


			COEXISTING WITH DEVFS

If you are running devfsd on a non-modular kernel, you will see a whole bunch
of error messages during boot, among which will be this one:

	QM_MODULES: Function not implemented

If you see that you have a kernel built with modules disabled and devfs
is trying to find and load drivers for your /dev/swapN devices. You can
shut devfsd up by editing /etc/devfs/devfsd.conf and disabling automagic
loading of device modules. Look for these lines:

	# Enable module autoloading. You may comment this out if you don't use
	# autoloading
	LOOKUP          \*              IGNORE
	LOOKUP                .*              MODLOAD

and comment out the one with the MODLOAD in it. The next boot should clear
up most of the error messages you saw.

If on the other hand, you are using modules, you will have to tell devfsd to
not attempt to look up a driver for /dev/swapN. Just add the line shown
below.

	# Enable module autoloading. You may comment this out if you don't use
	# autoloading
	LOOKUP          \*              IGNORE
	LOOKUP          ^swap*          IGNORE  # Cryptoswap device
	LOOKUP          .*              MODLOAD

Devfs is not started at boot time by the default configuration. So cryptoswap
will not work until you change /etc/default/devfsd

	MOUNT=no

to

	MOUNT=yes


		EXTENSIONS TO THE /etc/fstab FILE FORMAT

We introduce modifications to the options part of the swap file type. These changes
are ignored by all other swap applications so they have no impact on utilities like
swapon and swapoff.

We introduce a pseudo device, /dev/swapN, where N is any number you want. This device
will just be a softlink created at boot time and removed at halt or reboot. Anything
named /dev/swap* is "owned" by cryptoswap.sh and may use the full range of cryptoswap
options. Let's start with an example line:

 <file system> <mount point> <type> <options>                                                           <dump> <pass>
 /dev/swap0       none         swap  sw,swapfile=/dev/hda2,cipher=aes,keysize=256,loop=6,wipe=1,fallback  0      0

This line will create a crypto swap device named /dev/swap0 that will link to the "loop"
device /dev/loop6. In turn, /dev/loop6 will use the aes "cipher" with a 256 bit "keysize"
and will map on top of the "swapfile"E device /dev/hda2. When /dev/swap0 is removed at
halt or reboot, the entirety of /dev/hda2 will be "wipe"ed once with zeroes. If for
some reason a crypto loopback cannot be created, a "fallback" to a non crypto swap
will occur. In that case /dev/swap0 will link directly to the underlying "swapfile"
/dev/hda2. That device will still be "wipe"ed once on shutdown, but "cipher", "keysize"
and "loop" will be ignored.

"sw" is a standard swap option and is not examined by cryptoswap.


Option		Description
======================================================================================
swapfile	Required option. It can be either a swap partition or a swap file, 
		exactly as you would normally place under the "<file system>" column 
		in an /etc/fstab. There is no default. If this entry is missing,
		it is an error.

cipher		Defaults to aes. It can be any valid encryption method listed in
		your losetup man page. If there aren't any listed there, you probably
		don't have a crypto enabled system, or at the very least haven't
		an crypto enabled util_linux package.

keysize		Defaults to 128. It can be any valid keysize for the selected cipher.

loop		No default. The loopback device number. Linux kernels with loopback 
		enabled currently only allow 0-7. This corresponds to 
		/dev/loop0 - /dev/loop7. If not present cryptoswap will fail unless
		fallback is set, in which case you will have an unencrypted partition
		on swapfile.

fallback	If this keywoard is not present, it defaults to DISABLED. Adding this
		keyword is useful if you are running other kernels that do not have
		encryption. When you boot into one of them you will get a non-crypto
		swap space of the same name as the crypto one would have been. If
		you are actually working on a secure system, this option should NOT
		be used as it is a blatent and wide open security breach.

wipe		WARNING! WARNING! Don't even think of using this option unless you
		really understand what is going on. It intentionally destroys all
		data on the specified partition or file with hopes of it being
		unrecoverable. It's a very bad thing to do a mkswap on your data
		disk; it's even worse to write zeroes on the whole thing.

		If this option is not present or is wipe=0, the swap space is not
		wiped on shutdown. If it is any other value, the ENTIRE SWAP SPACE
		is overwritten with zeroes the specified number of times. This
		could be exceedingly time consuming and is here for the use of the
		terminally paranoid or those who have al Qaeda chasing them. For
		convenience, this is the only option that will also be applied to
		non-cryptoswap owned partitions. You can cause a wipe on any old
		swap partition at all. wipes occur only on halt, reboot or
		if you manually type:

			/etc/init.d/cryptoswap.sh stop

		WARNING! WARNING! Make absolutely triply redundantly completely
		certain that the device you are going to irretrievaly wipe out,
		zero, clear, blackhole and send to bit nirvana is actually and
		indeed the device or file you think it is. If you wipe your
		system disk or your own data disk, it's gone bye-bye and 
		not even a data recovery specialist can get it back. 

		This is what you *want* on the swap disk of a secure system.
		It is most certainly *not* the fate you wish upon your cherished
		protected data partitions. 

		Oh, and did I say you should be careful with this option?


Example /etc/fstab lines

1)  /dev/hda2        none         swap  sw,wipe=2  0  0

This is a normal unencrypted swap. cryptoswap will overwrite the entire partition /dev/hda2
with zeroes twice on shutdown.

2)  /dev/swap0       none         swap  sw,swapfile=/dev/hda2,loop=6  0  0

This is a normal encrypted swap. It defaults to AES128 encryption. If it can't create a
cryptoswap, it fails. The end result should be /dev/swap0 softlinked to /dev/loop6 which
is a loopback on top of /dev/hda2.

3)  /dev/swap0       none         swap  sw,swapfile=/dev/hda2,keysize=256,loop=6  0  0

The same as above but with a 256 bit keysize.

4)  /dev/swap0       none         swap  sw,swapfile=/dev/hda2,cipher=twofish,loop=6  0  0

This uses twofish with a 128 bit keysize.

5)  /dev/swap0       none         swap  sw,swapfile=/dev/hda2,fallback  0  0

This would probably be a mistake, but it will create an unencrypted partition on /dev/hda2.
There are easier ways to do this.

6)  /dev/swap0       none         swap  sw,swapfile=/root/mybigswapfile,loop=6  0  0

This will create an encrypted swap on the named file. It defaults to AES128 encryption. 
If it can't create a cryptoswap, it fails. The end result should be /dev/swap0 softlinked 
to /dev/loop6 which is a loopback on top of /dev/hda2. You would normally created a file
something like this:

		dd if=/dev/zero of=/root/mybigswapfile bs=1k count=64000

to make a 64MB swapfile. cryptoswap will do the mkswap on the file at startup so 
you needn't bother with that.


