Provided by: cryptmount_4.0-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
               fsoptions=OPT,OPT,...
               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’,  ’fsoptions’,  ’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  (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 (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.

       OPT    is a filesystem mounting option, as used by mount (8).  OPT  can
              typically  be  "default",  "noatime",  "noexec", "nosuid", "ro",
              "sync" 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 specifed 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.

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     fsoptions=default
               cipher=aes                              # 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     fsoptions=nosuid,noexec
               cipher=serpent

               # 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     fsoptions=defaults
               cipher=twofish                      # 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

               # 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.