cryptoloop - a generic cryptographic loop device filter
=======================================================

In order to make use of this filter, you'll have to patch your loop
driver in order to fix the IV calculation, which broke in the 2.4.x
kernels.
(loop patches may be found at
<http://www.kernel.org/pub/linux/kernel/crypto/> or
<http://www.kernel.org/pub/linux/kernel/people/hvr/>)

Note: this is now done during make patch-kernel

Quickstart
~~~~~~~~~~

(if you have old encrypted volumes, please read the section about
conversion below)

you need a kernel compiled with 
 *) loop device driver
 *) cryptographic support
 *) generic crypto loop filter
 *) one or more ciphers you want to use for encryption
either as module or statically (if you build them as module, don't
forget to insmod them!)

you also need a util-linux patched package (see
<http://www.kernel.org/pub/linux/kernel/people/hvr/> for some recent
patches)

read on at
<http://encryptionhowto.sourceforge.net/>


How Loopback Encryption Works
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  Here is a small overview of how the loopback filesystem encryption works.
For all the of the data to be encrypted on a drive we need to interrupt the
disk write/read *after* the filesystem meta data is attached.  Instead of pre-
empting the system call we pipe the the filesystem commands through a loopback
device.
  One advantage of this is that you can either encrypt a device(hard drive) or
a file already on a drive and mount it as a file system.  This allows you to have
encrypted folders on an unencrypted drive, useful if you don't want to encrypt 
everything.
  The loopback device fits in like this:

  device-->loop-->mountpoint

  The loop stage is actually divided into a couple stages, which is why the crypto-
loop module is included.  It splits the input and output from the loopback into pieces
for the ciphers.  Since they operate on a specific blocksize(i.e. 64-bits, 128-bits) the
data must be chopped up for them.

  device-->cryptoloop-->loop-->mountpoint

  The cryptoloop module is also where the actual encryption and decryption of the data 
takes place.


Some words about IV Calculation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are some problems with the IV calculation up to recent 2.4.x
linux kernels. It's been calculated more or less by 

IV = rel_sector / (blocksize >> 9) + (lo_offset / blocksize)

The first problem which arises, is that data transfers are not always
guaranteed to have a size of an integral multiple of the blocksize;
This is a problem, because of CBC mode's property of needing the
complete ciphertext block, i.e. you can't cipher or decipher only the
2nd half of a block if you don't know the first half of it!

Another problem which may be experienced is, when the soft blocksize
changes, i.e. due to different medias, as CDROM block devices and
alike, or when the filesystem layer sets the blocksize to some other
size.

But there's hope, as all transfer sizes are usually (except for the
last block on file backed loop devices sometimes...) an integral
multiple of 512 byte units (which is linux' atomic sector size);

So the solution is to stick to a portable, uniform 512 byte based IV
metric! Alas this can't be accomplished without modifying the loop
driver, as the more granular IV metric can't be calculated from the
current dynamic IV metric.

This change also renders most previously used encrypted volumes
unreadable, which need to be converted to the new IV metric.


Converting from Older IV Metrics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The recommended procedure is as follow, in case you don't want to
backup your old data in a conventional manner, and then restore it to
a freshly created encrypted volume with the new IV-metric.

The more valuable your data is, the more important it is, that you try
the following procedure with some dummy data, before risking your real
data! Cause if something goes wrong you'll have to keep both pieces...

1) decrypt from within your old kernel version

 1.1) setup your encrypted loop device, and mount it (this is also
 important for making sure, the filesystem layer sets the soft block
 size accordingly!)

 1.2) unmount the filesystem (but leave the loop device setted up)

 1.3) dd if=/dev/loop0 of=/dev/<underlying blockdev/file> make sure
 the process does not get interrupted, otherwise you will have a hard
 time, reconstructing your data, since you are decrypting the data
 back to the same area where the ciphertext was.

3) make sure the block/file contains the properly deciphered content!!

2) boot the new kernel featuring the 512byte based IV
 follow the instructions for 'encrypting unencrypted volumes' below


Encrypting Unencrypted Volumes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

just as simple as that (please test this before trying on important data)

 1) set up a new encrypted loop device over the still unencrypted data
 2) dd if=/dev/<underlying blockdev/file> of=/dev/loop0


Migrating from loop-AES to CryptoAPI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  If you want to move from using the loop-AES filesystem encryption to CryptoAPI
it only requires a small tweak.  After loading cryptoapi and loading the cipher-aes
module use the following line when setting up your loopback device:

            $ losetup -e aes -k 256 -P sha512 /dev/loop0 /dev/<your drive>

Then proceed to mount your loop device as you normall would.  Here is the table for
mapping loop-AES to cryptoapi losetup flags:

loop-AES                        cryptoapi
============================================================
-e aes128 -H rmd160             -e aes -k 128
-e aes128 -H sha256             -e aes -k 128 -P sha256
-e aes128 -H sha384             -e aes -k 128 -P sha384
-e aes128 -H sha512             -e aes -k 128 -P sha512

-e aes256 -H rmd160             -e aes -k 256
-e aes256 -H sha256             -e aes -k 256 -P sha256
-e aes256 -H sha384             -e aes -k 256 -P sha384
-e aes256 -H sha512             -e aes -k 256 -P sha512

-e aes128                       -e aes -k 128 -P sha256
-e aes192                       -e aes -k 192 -P sha384
-e aes256                       -e aes -k 256 -P sha512

--


