Provided by: cryptmount_3.0-1_i386 bug

NAME

       cryptmount - mount/unmount/configure an encrypted filing system

SYNOPSIS

       cryptmount [-aclmu] [target ...]

       cryptmount [--change-password [target ...]]

       cryptmount [--generate-key size [target ...]]

       cryptmount [--prepare [target ...]]

       cryptmount [--release [target ...]]

       cryptmount [--swapon [target ...]]

       cryptmount [--swapoff [target ...]]

DESCRIPTION

       cryptmount  allows  a  user to mount an encrypted filing system 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 fsoptions=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.)

FILES

       /etc/cryptmount/cmtab - main configuration file

       /etc/cryptmount/cmstatus - record of mounted filesystems

SEE ALSO

       cmtab(5), cryptmount-setup(8), dmsetup(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-2007 RW Penney
       and  is supplied with NO WARRANTY.  Licencing terms are as described in
       the file "COPYING" within the cryptmount source distribution.