Provided by: cryptmount_5.2.4-1build1_amd64 bug

NAME

       cmtab - static information about filesystems managed by cryptmount

DESCRIPTION

       Information about the encrypted filesystems 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                      # REQUIRED
               flags=FLAG,FLAG,...
               startsector=STARTSECTOR
               numsectors=NUMSECTORS
               loop=LOOPDEV
               dir=MOUNT_POINT
               fstype=TYPE                     # REQUIRED
               mountoptions=MOPT,MOPT,...
               fsckoptions=FOPT;FOPT;...
               supath=SUPATH
               bootaction=BOOTACTION
               cipher=CIPHER
               ivoffset=IVOFFSET
               keyformat=KEYMANAGER
               keyfile=KEYFILE                 # REQUIRED
               keyhash=KEYHASH
               keycipher=KEYCIPHER
               keymaxlen=KEYMAXLEN
               passwdretries=NUMATTEMPTS
           }

       Some  fields, such as `dev' and `fstype' are mandatory, although many fields have sensible
       default values.  Depending  on  the  choice  of  KEYMANAGER,  fields  such  as  `keyhash',
       `keycipher', `keymaxlen' may need to be set explicitly.

       Any  field  which  contains non-numerical values (e.g. not `startsector', `ivoffset' etc.)
       can contain references to environmental variables of  the  form  $(HOME).   The  following
       variables  are  recognized, all based on the characteristics of the user currently running
       cryptmount :
         * $(HOME) - the home directory, as obtained from /etc/passwd
         * $(UID) - the numerical identifier of the user
         * $(USERNAME) - the printable name of the user
         * $(GID) - the numerical identifier of the user's current group
         * $(GROUPNAME) - the printable name of the user's current group

TARGET DEFINITIONS

       The components in each target definition have the following meaning:

       TARGET_NAME { ... }
              specifies the name that cryptmount uses to refer to a particular  filesystem,  with
              configuration  options  for  that  filesystem contained within the matching braces.
              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'.   Note  that  if
              the  "_DEFAULTS_"  target  appears  more  than  once, each will undo the effects of
              previous default values - i.e. this pseudo-target does not operate incrementally.

       dev=DEVICE
              sets the  name  of  the  raw  device  (e.g.  /dev/hdb63)  or  ordinary  file  (e.g.
              /home/secretiveuser/private.fs)  that contains the encrypted filesystem.  Note that
              it may be useful to use a symbolic name based on an entry beneath  /dev/disk/by-id,
              /dev/disk/by-path,  to reduce the risk of device nodes being renamed when new disks
              are added to the system, etc.

       flags=FLAG,FLAG,...
              sets configuration switches, 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)
                * "trim" (enable TRIM/discard support on solid-state disks),
                * "notrim" (disable SSD TRIM/discard support)
              This parameter is optional and defaults to "user,fsck,nomkswap,notrim".

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

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

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

       dir=MOUNT_POINT
              specifies the directory onto which the encrypted filesystem will be mounted.

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

       mountoptions=MOPT,MOPT,...
              sets filesystem mounting options, as used by  mount  (8).  MOPT  can  typically  be
              "default", "noatime", "noexec", "nosuid", "ro", "sync" etc.

       fsckoptions=FOPT;FOPT;...
              sets  filesystem-checking  options  understood  by  fsck (8). FOPT can typically be
              "-C", "-V" etc.  Note that the list of fsck options uses semicolons as a  separator
              to allow passing options that themselves contain commas.

       supath=SUPATH
              sets  the  PATH  environment  variable when running subprocesses as the super-user.
              This may be necessary when commands such as fsck and mount need to run  subcommands
              (e.g. fsck.ext4).  By default, this PATH is set to /sbin:/bin:/usr/sbin:/usr/bin.

       bootaction=BOOTACTION
              indicates  what  action,  if any, should be taken for this target on system bootup.
              BOOTACTION can be one of "none", "mount", "swap" or "prepare".

       cipher=CIPHER
              sets 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=KEYMANAGER
              specifies the key management scheme used to interact with the KEYFILE, as discussed
              in  the  CHOICE  OF  KEYMANAGER section below.  The set of available key management
              schemes is 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=KEYFILE
              gives  the  name  of  an  ordinary  file  that  contains the key used by the CIPHER
              algorithm to decrypt the  filesystem.  This  key  is  itself  encrypted  in  a  way
              specified by the KEYHASH and KEYCIPHER

       ivoffset=IVOFFSET
              sets  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=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  KEYMANAGER.   This  parameter  is
              optional and the default depends on the value of KEYMANAGER.

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

       keymaxlen=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.

       passwdretries=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 @CM_SYSCONFDIR@/cmtab,  all  paths  must  be  absolute
       (i.e. starting with '/').

       When  using  unencrypted  keyfiles (i.e. when KEYMANAGER 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 @CM_SYSCONFDIR@/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 @CM_SYSCONFDIR@/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:

           # @CM_SYSCONFDIR@/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=@CM_SYSCONFDIR@/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=@CM_SYSCONFDIR@/crypt_hdb63.key
               keyformat=libgcrypt
               keyhash=md5 keycipher=blowfish-cbc # encryption of key file
           }

           encswap {                               # encrypted swap partition
               bootaction=swap
               dev=/dev/disk/by-id/scsi-SATA_ST500_ABCDEFG-part37
               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-$(USERNAME)
               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 filesystem, 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.   By using the environmental variable $(USERNAME), the filesystem's mount-
       point will vary depending on which user invokes cryptmount.  For example, user 'joe' would
       find  the  filesystem  mounted  below /mnt/luks-partition-joe.  cryptmount will be able to
       mount and unmount the partition, but various  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-2018 RW Penney
       and  is supplied with NO WARRANTY.  Licencing terms are as described in the file "COPYING"
       within the cryptmount source distribution.