Provided by: cryptmount_5.3.3-1_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                 # REQUIRED
               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     (required)
              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     (required)
              specifies the directory onto which the encrypted filesystem will be mounted.

       fstype=TYPE    (required)
              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",  with  the  default
              being "none".

       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     (required)
              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-2021 RW Penney
       and is supplied with NO WARRANTY.  Licencing terms are as described in the file  "COPYING"
       within the cryptmount source distribution.