Provided by: cryptmount_4.5-1_amd64 
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
flags=FLAG,FLAG,...
startsector=STARTSECTOR
numsectors=NUMSECTORS
loop=LOOPDEV
dir=MOUNT_POINT
fstype=TYPE
mountoptions=MOPT,MOPT,...
fsckoptions=FOPT;FOPT;...
bootaction=BOOTACTION
cipher=CIPHER
ivoffset=IVOFFSET
keyformat=KEYMANAGER
keyfile=KEYFILE
keyhash=KEYHASH
keycipher=KEYCIPHER
keymaxlen=KEYMAXLEN
passwdretries=NUMATTEMPTS
}
wherein the fields `flags', `startsector', `numsectors', `loop', `ivoffset', `keyformat', `keymaxlen' and
`passwdretries' are optional.
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.
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-2013 RW Penney
and is supplied with NO WARRANTY. Licencing terms are as described in the file "COPYING" within the
cryptmount source distribution.