Provided by: cryptmount_6.2.0-1_amd64 
NAME
cryptmount - mount/unmount/configure an encrypted filesystem
SYNOPSIS
cryptmount TARGET [TARGET ...]
cryptmount --unmount TARGET [TARGET ...]
cryptmount --change-password TARGET
cryptmount --generate-key SIZE TARGET
cryptmount --swapon TARGET
cryptmount --swapoff TARGET
DESCRIPTION
cryptmount allows an encrypted filesystem to be mounted or unmounted, without requiring
superuser privileges, and assists the superuser in creating new encrypted filesystems.
After initial configuration of the filesystem by the system administrator, the user needs
only to provide the decryption password for that filing system in order for cryptmount to
automatically configure device-mapper and loopback targets before mounting the filesystem.
cryptmount was written in response to differences between the newer device-mapper
infrastructure of the linux-2.6 kernel series, and the older cryptoloop infrastructure
which allowed ordinary users access to encrypted filesystems directly through mount (8).
OPTIONS
-a --all
act on all available targets, e.g. for mounting all targets.
-m --mount
mount the specified target, configuring any required device-mapper or loopback
devices. The user will be asked to supply a password to unlock the decryption key
for the filesystem.
-u --unmount
unmount the specified target, and deconfigure any underlying device-mapper or
loopback devices. No password is required, although the operation will fail if the
filesystem is in use, or if a non-root user tries to unmount a filesystem mounted
by a different user.
-S --status
provide information on whether the specified target is currently mounted or not
-l --list
lists all available targets, including basic information about the filesystem and
mount point of each.
-c --change-password
change the password protecting the decryption key for a given filesystem.
-g --generate-key size
setup a decryption key for a new filesystem. size gives the length of the key in
bytes.
-e --reuse-key existing-target
setup a decryption key for a new filesystem, using an existing key from another
filesystem, for example to translate between different file-formats for storing a
single key. This option is only available to the superuser.
-f --config-fd num
read configuration information about targets from file-descriptor num instead of
the default configuration file. This option is only available to the superuser.
-w --passwd-fd num
read passwords from file-descriptor num instead of from the terminal, e.g. for
using cryptmount within scripts or GUI wrappers. Each password is read once only,
in contrast to terminal-based operation where new passwords would be requested
twice for verification.
-p --prepare
prepare all the device-mapper and loopback devices needed to access a target, but
do not mount. This is intended to allow the superuser to install a filesystem on
an encrypted device.
-r --release
releases all device-mapper and loopback devices associated with a particular
target. This option is only available to the superuser.
-s --swapon
enable the specified target for paging and swapping. This option is only available
to the superuser.
-x --swapoff
disable the specified target for paging and swapping. This option is only
available to the superuser.
-k --key-managers
list all the available formats for protecting the filesystem access keys.
-B --system-boot
setup all targets which have declared a "bootaction" parameter. This will
typically be used to automatically mount encrypted filesystems, or setup encrypted
swap partitions, on system startup. This option is only available to the
superuser.
-Q --system-shutdown
close-down all targets which have declared a "bootaction" parameter. This is
essentially the opposite of the "--system-boot" option.
-n --safetynet
attempts to close-down any mounted targets that should normally have been shutdown
with --unmount or --swapoff. This option is only available to the superuser, and
intended exclusively for use during shutdown/reboot of the operating system.
-v --version
show the version-number of the installed program.
RETURN CODES
cryptmount returns zero on success. A non-zero value indicates a failure of some form, as
follows:
1 unrecognized command-line option;
2 unrecognized filesystem target name;
3 failed to execute helper program;
100 insufficient privilege;
101 security failure in installation.
EXAMPLE USAGE
In order to create a new encrypted filesystem managed by cryptmount, you can use the
supplied 'cryptmount-setup' program, which can be used by the superuser to interactively
configure a basic setup.
Alternatively, a manual setup allows more control of configuration settings. Before doing
so, one should ensure that kernel support for /dev/loop and /dev/mapper is available, e.g.
via
modprobe -a loop dm-crypt
Now suppose that we wish to setup a new encrypted filesystem, that will have a target-name
of "opaque". If we have a free disk partition available, say /dev/sdb63, then we can use
this directly to store the encrypted filesystem. Alternatively, if we want to store the
encrypted filesystem within an ordinary file, we need to create space using a recipe such
as:
dd if=/dev/zero of=/home/opaque.fs bs=1M count=512
and then replace all occurrences of '/dev/sdb63' in the following with '/home/opaque.fs'.
(/dev/urandom can be used in place of /dev/zero, debatably for extra security, but is
rather slower.)
First, we need to add an entry in /etc/cryptmount/cmtab, which describes the encryption
that will be used to protect the filesystem itself and the access key, as follows:
opaque {
dev=/dev/sdb63 dir=/home/crypt
fstype=ext2 mountoptions=defaults cipher=twofish
keyfile=/etc/cryptmount/opaque.key
keyformat=builtin
}
Here, we will be using the "twofish" algorithm to encrypt the filesystem itself, with the
built-in key-manager being used to protect the decryption key (to be stored in
/etc/cryptmount/opaque.key).
In order to generate a secret decryption key (in /etc/cryptmount/opaque.key) that will be
used to encrypt the filesystem itself, we can execute, as root:
cryptmount --generate-key 32 opaque
This will generate a 32-byte (256-bit) key, which is known to be supported by the Twofish
cipher algorithm, and store it in encrypted form after asking the system administrator for
a password.
If we now execute, as root:
cryptmount --prepare opaque
we will then be asked for the password that we used when setting up
/etc/cryptmount/opaque.key, which will enable cryptmount to setup a device-mapper target
(/dev/mapper/opaque). (If you receive an error message of the form device-mapper ioctl
cmd 9 failed: Invalid argument , this may mean that you have chosen a key-size that isn't
supported by your chosen cipher algorithm. You can get some information about suitable
key-sizes by checking the output from "more /proc/crypto", and looking at the "min
keysize" and "max keysize" fields.)
We can now use standard tools to create the actual filesystem on /dev/mapper/opaque:
mke2fs /dev/mapper/opaque
(It may be advisable, after the filesystem is first mounted, to check that the permissions
of the top-level directory created by mke2fs are appropriate for your needs.)
After executing
cryptmount --release opaque
mkdir /home/crypt
the encrypted filesystem is ready for use. Ordinary users can mount it by typing
cryptmount -m opaque
or
cryptmount opaque
and unmount it using
cryptmount -u opaque
cryptmount keeps a record of which user mounted each filesystem in order to provide a
locking mechanism to ensure that only the same user (or root) can unmount it.
PASSWORD CHANGING
After a filesystem has been in use for a while, one may want to change the access
password. For an example target called "opaque", this can be performed by executing:
cryptmount --change-password opaque
After successfully supplying the old password, one can then choose a new password which
will be used to re-encrypt the access key for the filesystem. (The filesystem itself is
not altered or re-encrypted.)
LUKS ENCRYPTED FILESYSTEMS
cryptmount can be used to provide easy access to encrypted filesystems compatible with the
Linux Unified Key Setup (LUKS) capabilities of the cryptsetup application.
In order to access an existing LUKS partition, an entry needs to be created within
/etc/cryptmount/cmtab. For example, if the hard-disk partition /dev/sdb62 is used to
contain a LUKS encrypted ext3 filesystem, an entry of the form:
LUKS {
keyformat=luks
dev=/dev/sdb62 keyfile=/dev/sdb62
dir=/home/luks-dir fstype=ext3
}
would allow this to be mounted via cryptmount beneath /home/luks-dir by executing
cryptmount LUKS
cryptmount will also allow any user that knows one of the access-passwords to change their
password via
cryptmount --change-password LUKS
cryptmount also provides basic support for creating new LUKS encrypted filesystems, which
can be placed within ordinary files as well as disk partitions, via the '--generate-key'
recipe shown above. However, to exploit the full range of functionality within LUKS, such
as for adding multiple passwords, one needs to use cryptsetup
It is strongly recommended that you do not attempt to use LUKS support in combination with
cryptmount's features for storing multiple encrypted filesystems within a single disk
partition or an ordinary file. This is because of assumptions within the cryptsetup-luks
design that the LUKS key-material is always stored at the beginning of the disk partition.
FILES
/etc/cryptmount/cmtab - main configuration file
/run/cryptmount.status - record of mounted filesystems
SEE ALSO
cmtab(5), cryptmount-setup(8), cryptsetup(8), mount(8)
BUGS
The author would be grateful for any constructive suggestions and bug-reports, via
https://github.com/rwpenney/cryptmount/issues
COPYRIGHT NOTICE
cryptmount is Copyright 2005-2023, RW Penney
and is supplied with NO WARRANTY. Licencing terms are as described in the file "COPYING"
within the cryptmount source distribution.