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.