Provided by: cryptmount_4.1-2_i386 bug

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.