This directory contains cryptmount, a utility for user-level mounting of
encrypted filing systems under GNU/Linux.
cryptmount is Copyright (c) 2005-2007 RW Penney, and is issued under
the General Public License (GPL) version-2

***** IMPORTANT NOTE:
    cryptmount is supplied with NO WARRANTY of any form -
    please see the file 'COPYING' for more information.


Introduction
============

cryptmount allows any user to access encrypted filing systems
on demand under GNU/Linux systems running a 2.6-series kernel.
It also assists the system administrator in creating and managing
encrypted filesystems based on the kernel's dm-crypt device-mapper target.
After initial configuration by the superuser, an ordinary user can
mount or unmount filesystems managed by cryptmount solely by providing
the decryption password, with any system devices needed to access
the filing system being configured automatically. A wide variety of
encryption schemes (provided by the kernel and OpenSSL/libgcrypt libraries)
can be used to protect both the filing system and the access key.
The protected filing systems can reside in either ordinary files,
or disk partitions.


Installation
============

To build cryptmount from source, please follow the instructions in
the file 'INSTALL' in the same directory as this file.
You will need the following packages (including 'developer' add-ons)
installed to successfully build and use cryptmount:
	
	kernel-headers (preferably for a 2.6-series kernel)
	libdevmapper (e.g. version 1.01 or later)

The following packages are optional, and allow a wider choice
of protection schemes for the keyfiles which govern access
to the protected filesystems:

	libgcrypt (e.g. version 1.2.0 or later)
	openssl (or libssl) (e.g version 0.9.7 or later)

cryptmount has been tested (using the "mudslinger" script
in the top-level directory) on a variety of GNU/Linux platforms including:
Debian 4.0, Debian 3.1, Fedora Core 5.0, Fedora Core 4.0,
Mandriva 2005, SuSE 10.0 etc.


Configuration & usage
=====================

An encrypted filing system must initially be created by the superuser.
A basic setup can be created interactively by running the 'cryptmount-setup'
program, which is typically installed in /usr/local/sbin.

If you wish to use more sophisticated setup options, the setup process
will depend more on the details of the host system
and the encryption algorithms available to the kernel.
The following is an example based on housing a 128Mb AES-encrypted
filing system in an ordinary file ("/home/crypt.fs")
which will be mounted below /mnt/crypt, and where the 256-bit decryption key
is protected by the builtin SHA1/Blowfish encryption engine.

First create a configuration file (by default "/usr/local/etc/cryptmount/cmtab")
that describes the encrypted filing system that we are about to create,
containing:

    crypt {
        dev=/home/crypt.fs dir=/mnt/crypt
        fstype=ext2 fsoptions=defaults cipher=aes
        keyfile=/usr/local/etc/cryptmount/crypt.key
        keyformat=builtin
    }

Then prepare the key-file and filing system as follows:

    cryptmount --generate-key 32 crypt
    dd if=/dev/zero of=/home/crypt.fs bs=1M count=128
    mkdir /mnt/crypt
    cryptmount --prepare crypt
    mke2fs /dev/mapper/crypt
    cryptmount --release crypt

A very similar process can be used to setup an encrypted filing system using
a raw disk partition in place of a loopback file.
(If, during the 'cryptmount --prepare' stage, you receive an error message
of the form 'device-mapper ioctl cmd 9 failed: Invalid argument', this
may mean that you have chosen a key-size that isn't supported by your
chosen cipher algorithm. You can get some information about suitable key-sizes
by checking the output from 'more /proc/crypto', and looking at the
'min keysize' and 'max keysize' fields.)

Thereafter, all information about the encrypted filing systems available
for mounting with cryptmount is contained in /usr/local/etc/cryptmount/cmtab.
So, the following command, executed by an ordinary user,
will make the filing system accessible below /mnt/crypt:

    cryptmount crypt

and the following will unmount it:

    cryptmount -u crypt


Configuring filesystems at system bootup
========================================

If you want to have encrypted filesystems setup at system boot-up,
this can be achieved using the supplied 'initscript' program
which is normally automatically installed as /etc/init.d/cryptmount.

You may need to create symbolic links from /etc/rc?.d to /etc/init.d/cryptmount
(in a way that depends on the precise details of your distribution),
with something like 'update-rc.d cryptmount defaults 28'
being suitable under Debian systems.

You can also create symbolic links to /etc/init.d/cryptmount with
linknames ending in '-early' to allow configuration of encrypted devices
early in the boot-process, so that they can be mounted via normal
bootup mechanisms, e.g. depending on entries in /etc/fstab.

When configured with dynamically loadable key-manager modules,
cryptmount can still be used to setup encrypted devices in the preliminary
stages of system booting even before the OpenSSL or libgcrypt libraries
are accessible, provided that the encrypted devices use
the 'builtin' keyformat (based on the SHA1 & Blowfish ciphers).

Once you have installed the boot-scripts,
you can edit /etc/defaults/cryptmount to list
the filesystem targets that you want configured/mounted at boot.


Suggestions/Patches
===================

You are welcome to send constructive suggestions and bug-fixes to the author:
    rwpenney@users.sourceforge.net
Any feedback (including the associated log-file) from running the "mudslinger"
tests on any systems not listed above would be particularly helpful.

# $Revision: 176 $, $Date: 2007-08-04 14:01:08 +0100 (Sat, 04 Aug 2007) $
