CRYPTMOUNT(8)							   User commands						     CRYPTMOUNT(8)

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 tar-
       gets 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 differ-
	      ent 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 verifica-
	      tion.

       -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 supe-
	      ruser 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-2011 RW Penney
       and is supplied with NO WARRANTY.  Licencing terms are as described in the file "COPYING" within the cryptmount source distribution.

4.3.1								    2011-05-03							     CRYPTMOUNT(8)