Provided by: cryptmount_3.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".

       KEYFORMAT
              specifies which encryption engine is used to manage the KEYFILE.
              The  available  engines are determined when cryptmount is built,
              but may  include  "openssl"  and  "libgcrypt",  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
              unless this is set to "builtin" when the  hashing  algorithm  is
              fixed as "sha1".

       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 unless this is set to
              "builtin" when the hashing algorithm is fixed as "blowfish-cbc",
              or  to  "raw"  when  a value of "none" can be used for a KEYFILE
              that contains an unprotected filesystem decryption key.

       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.

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

EXAMPLE FILE

       The  following  example  of  /etc/cryptmount/cmtab  consists  of  three
       targets, using a variety of encryption  algorithms  and  storing  their
       filesystems  in  different  ways,  and  fourth  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
           }

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

FILES

       /etc/cryptmount/cmtab - main configuration file

SEE ALSO

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

COPYRIGHT NOTICE

       cryptmount is Copyright 2005-2008 RW Penney
       and is supplied with NO WARRANTY.  Licencing terms are as described  in
       the file "COPYING" within the cryptmount source distribution.