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.
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 fields in each target definition 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 (512-byte 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
(512-byte 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.
When the 'mkswap' option is selected for a particular target within
/etc/cryptmount/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 /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-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=/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-cbc-plain # 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/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 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. 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-2009 RW Penney
and is supplied with NO WARRANTY. Licencing terms are as described in the file
"COPYING" within the cryptmount source distribution.