Provided by: cryptmount_5.2-1_i386 bug

NAME

       cryptmount - mount/unmount/configure an encrypted filesystem

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 filesystem to be mounted or unmounted,
       without requiring superuser privileges, and assists  the  superuser  in
       creating new encrypted filesystems.  After initial configuration of the
       filesystem by the system administrator, the user needs only to  provide
       the  decryption password for that filing system in order for cryptmount
       to automatically configure device-mapper and  loopback  targets  before
       mounting the filesystem.

       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 filesystems 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 filesystem.

       -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 filesystem is in use, or
              if  a  non-root  user tries to unmount a filesystem mounted by a
              different user.

       -S --status
              provide information on whether the specified target is currently
              mounted or not

       -l --list
              lists  all  available targets, including basic information about
              the filesystem and mount point of each.

       -c --change-password
              change the password protecting the decryption key  for  a  given
              filesystem.

       -g --generate-key size
              setup  a  decryption  key  for a new filesystem.  size gives the
              length of the key in bytes.

       -e --reuse-key existing-target
              setup a decryption key for a new filesystem, using  an  existing
              key  from  another  filesystem, 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 filesystem 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.

       -B --system-boot
              setup all targets which have declared a "bootaction"  parameter.
              This  will  typically  be  used to automatically mount encrypted
              filesystems, or  setup  encrypted  swap  partitions,  on  system
              startup.  This option is only available to the superuser.

       -Q --system-shutdown
              close-down  all  targets  which  have  declared  a  "bootaction"
              parameter.  This is essentially the opposite of  the  "--system-
              boot" option.

       -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 filesystem 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,  a  manual  setup  allows  more control of configuration
       settings.  Before doing so, one should ensure that kernel  support  for
       /dev/loop and /dev/mapper is available, e.g. via
           modprobe -a loop dm-crypt
       Now suppose that we wish to setup a new encrypted filesystem, 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 filesystem.  Alternatively, if we want to store the encrypted
       filesystem  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
       filesystem  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 filesystem
       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 filesystem 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 filesystem 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

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