Provided by: cryptmount_4.2.1-1_i386 bug

NAME

       cmtab - static information about filesystems managed by cryptmount

DESCRIPTION

       Information about the encrypted filing systems managed by cryptmount is
       contained  in  the  file  /etc/cryptmount/cmtab.   Each  filesystem  is
       labelled  by  a  target  name  which  can  be  used  as  an argument to
       cryptmount and which appears in /etc/cryptmount/cmtab  in  front  of  a
       list  of parameters describing where that filesystem is stored, and how
       it is encrypted.

       The format of the cmtab is  flexible,  with  the  description  of  each
       target  being  delimited  by  braces,  parameters  being  specified  by
       KEY=VALUE pairs, and white-space being  freely  usable.   Comments  are
       prefixed  by  a  `#'  character,  and can start at any point in a line,
       lasting to the end of the line.  The backslash  character  `\'  can  be
       used to ignore any special significance of the following character, for
       example to include a space in a filename.

       /etc/cryptmount/cmtab contains entries of the following form:

           TARGET_NAME {
               dev=DEVICE
               flags=FLAG,FLAG,...
               startsector=STARTSECTOR
               numsectors=NUMSECTORS
               loop=LOOPDEV
               dir=MOUNT_POINT
               fstype=TYPE
               mountoptions=MOPT,MOPT,...
               fsckoptions=FOPT;FOPT;...
               cipher=CIPHER
               ivoffset=IVOFFSET
               keyformat=KEYFORMAT
               keyfile=KEYFILE
               keyhash=KEYHASH
               keycipher=KEYCIPHER
               keymaxlen=KEYMAXLEN
               passwdretries=NUMATTEMPTS
           }

       wherein  the  fields  `flags',  `startsector',  `numsectors',   `loop',
       `ivoffset', `keyformat', `keymaxlen' and `passwdretries' are optional.

       The fields in this structure have the following meaning:

       TARGET_NAME
              is the name that cryptmount uses to refer to a particular filing
              system.  The special  name  "_DEFAULTS_"  may  be  used  to  set
              default values in subsequent targets for various parameters such
              as 'flags',  'fstype',  'mountoptions',  'cipher',  'keyformat',
              'keyhash', 'keycipher', 'keymaxlen', 'passwdretries'.

       DEVICE is the name of the raw device (e.g. /dev/hdb63) or ordinary file
              (e.g.   /home/secretiveuser/private.fs)   that   contains    the
              encrypted filing system.

       FLAG   is a configuration switch, such as
                * "user" (any user can mount),
                * "nouser" (only root can mount),
                * "fsck" (automatically check filesystem before mounting),
                * "nofsck" (don't check filesystem before mounting),
                * "mkswap" (format swap partition before use),
                * "nomkswap" (don't format swap partition).
              This parameter is optional and defaults to "user,fsck,nomkswap".

       STARTSECTOR
              is  the number of sectors (512-byte blocks) into DEVICE at which
              the filing system is to start.  This parameter is optional,  and
              defaults to zero.

       NUMSECTORS
              gives the total length of the filing system in sectors (512-byte
              blocks).  This parameter is optional, and defaults to  -1  which
              is shorthand for the total available length of DEVICE.

       LOOPDEV
              can  be  used  to  specify  a  particular  loopback device (e.g.
              /dev/loop0) used when DEVICE is an ordinary file. This parameter
              is optional and defaults to "auto".

       MOUNT_POINT
              is  the directory onto which the encrypted filing system will be
              mounted.

       TYPE   is the filing system type (as used by mount (8)).  This must  be
              set  to  "swap" if the device is to be used as an encrypted swap
              partition.

       MOPT   is a filesystem mounting option, as used by mount (8). MOPT  can
              typically  be  "default",  "noatime",  "noexec", "nosuid", "ro",
              "sync" etc.

       FOPT   is a filesystem-checking option understood by fsck (8). FOPT can
              typically be "-C", "-V" etc.

       CIPHER is  the  encryption algorithm used on the DEVICE.  The available
              algorithms are determined by the system kernel.  This  parameter
              is optional and defaults to "aes-cbc-plain".

       KEYFORMAT
              specifies which encryption engine is used to manage the KEYFILE.
              The available engines are determined when cryptmount  is  built,
              but  may  include  "libgcrypt", "luks", and "openssl-compat", in
              addition to "builtin" and "raw".  This parameter is optional: if
              absent, "builtin" will be used on first generating the key, with
              an automatic choice being made when reading a pre-existing key.

       KEYFILE
              is an ordinary file that contains the key  used  by  the  CIPHER
              algorithm  to  decrypt  the  filing  system.  This key is itself
              encrypted in a way specified by the KEYHASH and KEYCIPHER

       IVOFFSET
              is the offset added to the sector-number  used  in  constructing
              the cipher algorithm's initialization vector.  This parameter is
              optional, and defaults to 0.

       KEYHASH
              is the hashing algorithm used to turn the user's  password  into
              the  decryption  key  used  by  the  KEYCIPHER  algorithm.   The
              available hashing algorithms are determined by the  chosen  key-
              encryption  engine  specified  by KEYFORMAT .  This parameter is
              optional and the default depends on the value of KEYFORMAT .

       KEYCIPHER
              is the encryption algorithm used to secure the decryption key of
              the   filing   system   itself.   The  available  key-encryption
              algorithms are determined by the  chosen  key-encryption  engine
              specified  by  KEYFORMAT.   This  parameter  is optional and the
              default depends on the value of KEYFORMAT.

       KEYMAXLEN
              is the maximum number of bytes of the decryption key  that  will
              be read from KEYFILE .  This parameter is optional, and defaults
              to 0, indicating that the full length of KEYFILE should be read.

       NUMATTEMPTS
              is the number of password-entry attempts that can be made before
              cryptmount  will exit with an error-code when trying to mount or
              configure the target.

CHOICE OF KEYMANAGER

       cryptmount supports a variety  of  different  ways  of  protecting  the
       access  key associated with each encrypted filesystem.  For most users,
       the default "builtin" keymanager will provide a good level of  security
       and  flexibility.   Alternative  keymanagers  offer  a  wider choice of
       different  password-hashing  schemes  and  compatibility   with   other
       encryption  tools.   The  strengths  and  weaknesses  of  the different
       keymanagers are discussed below.

       builtin

       This keymanager is supported by cryptmount-2.0 or  later,  and  uses  a
       separate  key-file.   A  password-based key derivation function (PBKDF)
       using the SHA1 hashing algorithm, together with blowfish-cbc encryption
       is  used  to  protect the filesystem key.  That key-derivation function
       was changed in cryptmount-4.0 to improve the security of new  keyfiles,
       while  preserving compatibility with existing keyfiles.  If you need to
       write   keyfiles   in   the   previous   format,   you   can    specify
       "keyformat=builtin:0".    The  KEYHASH  and  KEYCIPHER  parameters  are
       ignored.

       libgcrypt

       This keymanager is supported by cryptmount-1.1 or  later,  and  uses  a
       separate key-file.  A password-based key derivation function (PBKDF) is
       used to  protect  the  filesystem  key,  with  any  hashing  or  cipher
       algorithm  supported  by the installed version of the libgcrypt library
       being available.

       luks

       This keymanager is supported by cryptmount-3.1 or later,  and  provided
       compatibility  with  the  Linux  Unified  Key Setup (LUKS) disk-format.
       Instead of a separate keyfile, LUKS uses a header within the  encrypted
       filesystem  itself.   It is advisable to choose the same value for both
       the 'dev' and 'keyfile' parameters, or leave 'keyfile' unspecified.  As
       with  all  cryptmount  filesystems,  the  'dev'  parameter may point to
       either a raw disk partition or an ordinary file.  However,  because  of
       the  filesystem  structure  assumed by LUKS, it is strongly recommended
       that you do not use either the 'startsector' or 'numsector' parameters.

       openssl/openssl-compat

       This keymanager has  been  supported  since  the  earliest  release  of
       cryptmount,  and  uses  a separate keyfile which is compatible with the
       format used by  the  'openssl'  command-line  encryption  tool.   Since
       cryptmount-3.0  this  file-format  has  been provided via the libgcrypt
       library, and is preferably specified by "keyformat=openssl-compat".   A
       password-based  key  derivation function (PBKDF) is used to protect the
       filesystem key, with a choice of hashing  or  cipher  algorithms  being
       available.   Most  algorithms  supported  by the 'openssl' command-line
       tool should  be  available,  provided  the  underlying  algorithms  are
       available within libgcrypt.

       password

       This  keymanager  is supported by cryptmount-4.0 or later, and does not
       require any separate keyfile, but instead derives  the  filesystem  key
       directly  from the user's password.  This means that it is not possible
       to  change  the  access  password  without  re-encrypting  the   entire
       filesystem.  The 'keyhash' and 'keycipher' parameters are ignored.

       raw

       This  keymanager  is  supported  by cryptmount-1.1 or later, and uses a
       separate keyfile where the access key is stored  directly  and  without
       any  encryption.  This keymanager is most useful for managing encrypted
       swap partitions, where the keyfile can be chosen  as  /dev/random,  and
       hence where the access key will be different every time it is read.  If
       the keyfile is an ordinary file, it offers minimal security, and should
       preferably  be stored separately from the disk containing the encrypted
       filesystem, e.g. on a USB flash disk.

SECURITY

       Because cryptmount needs to operate with setuid privileges, it is  very
       important   that  its  configuration  file  is  kept  secure.   Ideally
       /etc/cryptmount/cmtab  should   be   managed   only   by   the   system
       administrator,  and  all  key-files  should  be  readable only by their
       owner.

       cryptmount makes basic checks on the security of  /etc/cryptmount/cmtab
       each  time  it  runs,  and  will refuse to operate unless the following
       conditions are met:
         * cmtab must be owned by root
         * cmtab must be a regular file
         * cmtab must not be globally writable
         * the directory containing cmtab must be owned by root
         * the directory containing cmtab must not be globally writable
       In addition, for each target within  /etc/cryptmount/cmtab,  all  paths
       must be absolute (i.e. starting with '/').

       When  using  unencrypted keyfiles (i.e. when KEYFORMAT is "raw"), it is
       recommended that the KEYFILE is stored with access permissions no  less
       restrictive  than  0600,  or on a removable device such as a USB flash-
       disk.  (With recent versions of  cryptmount  the  "builtin"  key-format
       should  be  portable  between  different  installations and vastly more
       secure than "raw" keyfiles.)

       It is very important that you do not lose or damage the KEYFILE as this
       file  is  essential  to  providing access to your encrypted filesystem.
       You are strongly advised to consider keeping a backup of  your  KEYFILE
       in some form.

ENCRYPTED SWAP PARTITIONS & AUTO-FORMATTING

       When  the  'mkswap'  option  is selected for a particular target within
       /etc/cryptmount/cmtab, cryptmount will attempt to automatically  format
       an  encrypted  swap  partition  whenever  you  run "cryptmount --swapon
       <target>".  This is often useful when there is no need to preserve swap
       data  between  reboots, such as when not using the kernel's hibernation
       features.

       Because reformatting will destroy any existing data on the chosen  swap
       partition, cryptmount will do some basic checking on the first megabyte
       of the partition, based on the degree of randomness  (entropy)  in  the
       current  contents.  If the partition looks like it contains pure noise,
       or has been zeroed, then the partition will be formatted automatically.
       If  cryptmount  determines  that  the  partition may contain non-random
       data, then it will ask you to run 'mkswap' manually.

       As there is no  fool-proof  way  of  determining  whether  a  partition
       (especially  after  encryption)  contains  valuable data, you should be
       very careful about the raw device chosen for any target  on  which  you
       select the 'mkswap' option.

EXAMPLE FILE

       The   following  example  of  /etc/cryptmount/cmtab  consists  of  five
       targets, using a variety of encryption  algorithms  and  storing  their
       filesystems  in  different  ways,  including  a  target representing an
       encrypted swap partition:

           # /etc/cryptmount/cmtab
           # example file - please modify before use

           _DEFAULTS_ {
               passwdretries=3     # allow 3 password attempts by default
           }

           basic {
               dev=/home/secretiveuser/crypt.fs
               dir=/home/secretiveuser/crypt           # where to mount
               loop=auto                               # find free loop-device
               fstype=ext3     mountoptions=default
               cipher=aes-cbc-plain                    # filesystem encryption
               keyfile=/home/secretiveuser/crypt.key
               # use default sha1/blowfish key-encryption:
               keyformat=builtin
           }

           partition {
               dev=/dev/hdb62                      # use whole disk partition
               dir=/mnt/crypt62
               fstype=ext3     mountoptions=nosuid,noexec
               cipher=serpent-cbc-plain

               # information about file used to store decryption key:
               keyfile=/etc/cryptmount/crypt_hdb62.key
               keyformat=openssl                   # use OpenSSL key-encryption
               keyhash=md5 keycipher=bf-cbc        # encryption of key file
           }

           subset {
               dev=/dev/hdb63
               startsector=512 numsectors=16384    # use subset of partition
               dir=/mnt/encrypted\ subset\ of\ hdb
               fstype=reiserfs     mountoptions=defaults
               cipher=twofish-cbc-plain            # filesystem encryption

               # information about file used to store decryption key:
               keyfile=/etc/cryptmount/crypt_hdb63.key
               keyformat=libgcrypt
               keyhash=md5 keycipher=blowfish-cbc # encryption of key file
           }

           encswap {                               # encrypted swap partition
               dev=/dev/hdb63
               startsector=16896 numsectors=1024   # use subset of partition
               fstype=swap        flags=mkswap       cipher=twofish-cbc-plain

               # read fresh 16-byte key from /dev/random whenever used:
               keyfile=/dev/random        keymaxlen=16     keyformat=raw
           }

           luks {                          # partition created by cryptsetup-luks
               dev=/dev/hdb63
               dir=/mnt/luks-partition
               keyformat=luks
               keyfile=/dev/hdb63
               fstype=ext3
           }

           # end of cmtab

       The 'basic' target uses an ordinary file "/home/secretiveuser/crypt.fs"
       to  store the encrypted filesystem, perhaps within a normal user's home
       directory.  A loopback device will be automatically allocated  (because
       of  the  "loop=auto")  by  cryptmount to turn this into a block-special
       device, before mounting.  The decryption key for the filesystem is also
       stored  in  this  user's  home  directory, making it easier for them to
       change the password protecting the key.

       The 'partition' target  uses  a  whole  disk  partition  to  store  the
       encrypted  filing  system,  with  the decryption key stored in the main
       cryptmount configuration directory.

       The 'subset' target is similar to the 'partition' target except that it
       does  not use a whole disk partition.  This would allow other groups of
       blocks within that partition to be used for other  filesystems  managed
       via cryptmount or dmsetup.

       The 'encswap' target uses a subset of blocks within a disk partition to
       form an encrypted swap device.  A new encryption key is read  from  the
       system  random-number  generator  /dev/random  every time the target is
       used.

       The 'luks' target provides access to an encrypted partition created  by
       the  'cryptsetup-luks'  utility.   cryptmount will be able to mount and
       unmount the partition, but password-changing and advanced LUKS features
       must be accessed through cryptsetup

FILES

       /etc/cryptmount/cmtab - main configuration file

SEE ALSO

       cryptmount(8),    cryptmount-setup(8),    cryptsetup(8),    dmsetup(8),
       openssl(1)

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.