This directory contains cryptmount, a utility for user-level mounting of
encrypted filing systems under GNU/Linux.
cryptmount is Copyright (c) 2005,2006 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 library)
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)
	openssl (or libssl) (e.g version 0.9.7 or later)
	libdevmapper (e.g. version 1.01 or later)

cryptmount has been tested (using the "mudslinger" script in the top-level directory) on the following platforms:

    Debian GNU/Linux 3.1r0a "Sarge" (x86) [1]
    FedoraCore-4 (x86) [2]
    Mandriva Linux 2005 (x86) [3]
    SuSE Linux 10.0 OSS (x86)

    Notes:
        [1] - Debian sarge testing has been performed on systems with custom-compiled kernels (2.6.8, 2.6.12 etc)
        [2] - FedoraCore-4 appears to have, as defaults, rather restrictive security policies on /sbin/losetup and /sbin/mke2fs. After moderating these restrictions, cryptmount appears to pass all tests normally.
        [3] - Mandriva2005 'Limited Edition' of June2005 was used


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

An encrypted filing system must initially be created by the superuser. The exact means of doing so will depend 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 Blowfish cipher.

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
        keyhash=md5 keycipher=bf-cbc
    }

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.

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


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: 130 $, $Date: 2006-10-15 11:42:36 +0100 (Sun, 15 Oct 2006) $
