NAME
cryptmount - mount/unmount/configure an encrypted filing system
SYNOPSIS
cryptmount TARGET [TARGET ...]
cryptmount --unmount TARGET [TARGET ...]
cryptmount --change-password TARGET
cryptmount --generate-key SIZE TARGET
cryptmount --swapon TARGET
cryptmount --swapoff TARGET
DESCRIPTION
cryptmount allows an encrypted filing system to be mounted or
unmounted, without requiring superuser privileges, and assists the
superuser in creating new encrypted filesystems. After initial
configuration of the filing system by the system administrator, the
user needs only to provide the decryption password for that filing
sytem in order for cryptmount to automatically configure device-mapper
and loopback targets before mounting the filing system.
cryptmount was written in response to differences between the newer
device-mapper infrastructure of the linux-2.6 kernel series, and the
older cryptoloop infrastructure which allowed ordinary users access to
encrypted filing systems directly through mount (8).
OPTIONS
-a --all
act on all available targets, e.g. for mounting all targets.
-m --mount
mount the specified target, configuring any required device-
mapper or loopback devices. The user will be asked to supply a
password to unlock the decryption key for the filing system.
-u --unmount
unmount the specified target, and deconfigure any underlying
device-mapper or loopback devices. No password is required,
although the operation will fail if the filing system is in use,
or if a non-root user tries to unmount a filing system mounted
by a different user.
-l --list
lists all available targets, including basic information about
the filing system and mount point of each.
-c --change-password
change the password protecting the decryption key for a given
filing system.
-g --generate-key size
setup a decryption key for a new filing system. size gives the
length of the key in bytes.
-e --reuse-key existing-target
setup a decryption key for a new filing system, using an
existing key from another filing system, for example to
translate between different file-formats for storing a single
key. This option is only available to the superuser.
-f --config-fd num
read configuration information about targets from file-
descriptor num instead of the default configuration file. This
option is only available to the superuser.
-w --passwd-fd num
read passwords from file-descriptor num instead of from the
terminal, e.g. for using cryptmount within scripts or GUI
wrappers. Each password is read once only, in contrast to
terminal-based operation where new passwords would be requested
twice for verification.
-p --prepare
prepare all the device-mapper and loopback devices needed to
access a target, but do not mount. This is intended to allow
the superuser to install a filing system on an encrypted device.
-r --release
releases all device-mapper and loopback devices associated with
a particular target. This option is only available to the
superuser.
-s --swapon
enable the specified target for paging and swapping. This
option is only available to the superuser.
-x --swapoff
disable the specified target for paging and swapping. This
option is only available to the superuser.
-k --key-managers
list all the available formats for protecting the filesystem
access keys.
-n --safetynet
attempts to close-down any mounted targets that should normally
have been shutdown with --unmount or --swapoff. This option is
only available to the superuser, and intended exclusively for
use during shutdown/reboot of the operating system.
-v --version
show the version-number of the installed program.
RETURN CODES
cryptmount returns zero on success. A non-zero value indicates a
failure of some form, as follows:
1 unrecognized command-line option;
2 unrecognized filesystem target name;
3 failed to execute helper program;
100 insufficient privilege;
101 security failure in installation.
EXAMPLE USAGE
In order to create a new encrypted filing system managed by cryptmount,
you can use the supplied ’cryptmount-setup’ program, which can be used
by the superuser to interactively configure a basic setup.
Alternatively, suppose that we wish to setup a new encrypted filing
system, that will have a target-name of "opaque". If we have a free
disk partition available, say /dev/hdb63, then we can use this directly
to store the encrypted filing system. Alternatively, if we want to
store the encrypted filing system within an ordinary file, we need to
create space using a recipe such as:
dd if=/dev/zero of=/home/opaque.fs bs=1M count=512
and then replace all occurences of ’/dev/hdb63’ in the following with
’/home/opaque.fs’. (/dev/urandom can be used in place of /dev/zero,
debatably for extra security, but is rather slower.)
First, we need to add an entry in /etc/cryptmount/cmtab, which
describes the encryption that will be used to protect the filesystem
itself and the access key, as follows:
opaque {
dev=/dev/hdb63 dir=/home/crypt
fstype=ext2 mountoptions=defaults cipher=twofish
keyfile=/etc/cryptmount/opaque.key
keyformat=builtin
}
Here, we will be using the "twofish" algorithm to encrypt the filing
system itself, with the built-in key-manager being used to protect the
decryption key (to be stored in /etc/cryptmount/opaque.key).
In order to generate a secret decryption key (in
/etc/cryptmount/opaque.key) that will be used to encrypt the filing
system itself, we can execute, as root:
cryptmount --generate-key 32 opaque
This will generate a 32-byte (256-bit) key, which is known to be
supported by the Twofish cipher algorithm, and store it in encrypted
form after asking the system administrator for a password.
If we now execute, as root:
cryptmount --prepare opaque
we will then be asked for the password that we used when setting up
/etc/cryptmount/opaque.key, which will enable cryptmount to setup a
device-mapper target (/dev/mapper/opaque). (If 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.)
We can now use standard tools to create the actual filing system on
/dev/mapper/opaque:
mke2fs /dev/mapper/opaque
(It may be advisable, after the filesystem is first mounted, to check
that the permissions of the top-level directory created by mke2fs are
appropriate for your needs.)
After executing
cryptmount --release opaque
mkdir /home/crypt
the encrypted filing system is ready for use. Ordinary users can mount
it by typing
cryptmount -m opaque
or
cryptmount opaque
and unmount it using
cryptmount -u opaque
cryptmount keeps a record of which user mounted each filesystem in
order to provide a locking mechanism to ensure that only the same user
(or root) can unmount it.
PASSWORD CHANGING
After a filesystem has been in use for a while, one may want to change
the access password. For an example target called "opaque", this can
be performed by executing:
cryptmount --change-password opaque
After successfully supplying the old password, one can then choose a
new password which will be used to re-encrypt the access key for the
filesystem. (The filesystem itself is not altered or re-encrypted.)
LUKS ENCRYPTED FILESYSTEMS
cryptmount can be used to provide easy access to encrypted filesystems
compatible with the Linux Unified Key Setup (LUKS) capabilities of the
cryptsetup application.
In order to access an existing LUKS partition, an entry needs to be
created within /etc/cryptmount/cmtab. For example, if the hard-disk
partition /dev/hdb62 is used to contain a LUKS encrypted ext3
filesystem, an entry of the form:
LUKS {
keyformat=luks
dev=/dev/hdb62 keyfile=/dev/hdb62
dir=/home/luks-dir fstype=ext3
}
would allow this to be mounted via cryptmount beneath /home/luks-dir by
executing
cryptmount LUKS
cryptmount will also allow any user that knows one of the access-
passwords to change their password via
cryptmount --change-password LUKS
cryptmount also provides basic support for creating new LUKS encrypted
filesystems, which can be placed within ordinary files as well as disk
partitions, via the ’--generate-key’ recipe shown above. However, to
exploit the full range of functionality within LUKS, such as for adding
multiple passwords, one needs to use cryptsetup
It is strongly recommended that you do not attempt to use LUKS support
in combination with cryptmount’s features for storing multiple
encrypted filesystems within a single disk partition or an ordinary
file. This is because of assumptions within the cryptsetup-luks design
that the LUKS key-material is always stored at the beginning of the
disk partition.
FILES
/etc/cryptmount/cmtab - main configuration file
/etc/cryptmount/cmstatus - record of mounted filesystems
SEE ALSO
cmtab(5), cryptmount-setup(8), cryptsetup(8), mount(8)
BUGS
The author would be grateful for any constructive suggestions and bug-
reports, via <rwpenney@users.sourceforge.net>
COPYRIGHT NOTICE
cryptmount is Copyright 2005-2009 RW Penney
and is supplied with NO WARRANTY. Licencing terms are as described in
the file "COPYING" within the cryptmount source distribution.