Provided by: cryptmount_4.1-2_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  (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.

       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.

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

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