CRYPTMOUNT(8)

📦
version 6.4.0 · 4 versions
, in ubuntu stonking

💖 CRYPTMOUNT(8) 💖

okay bestie, welcome to cryptmount — she lives in the User commands section of the manual, and she is literally the moment. buckle up 🎀

✨ 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 💅

So cryptmount lets you mount or unmount an encrypted filesystem without needing superuser privileges, and she also helps the superuser out when they're creating brand-new encrypted filesystems. iconic behaviour, truly. 🫶

Here's the vibe: the system administrator does the initial configuration of the filesystem once, and after that the user only has to hand over the decryption password for that filing system. cryptmount then automatically configures the device-mapper and loopback targets before mounting the filesystem. she does all the boring bits for you. 💖

ngl, 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. the old one let ordinary users reach encrypted filesystems directly through mount(8), and the new one… did not. so she stepped in. 🧚

✨ OPTIONS ✨

  • -a, --all — act on all available targets. like, for mounting every single target at once. the "select all" of cryptomounting 👑
  • -m, --mount — mount the specified target, configuring any device-mapper or loopback devices that are required. the user is going to get 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 needed bestie. that said, it will fail if the filesystem is in use, or if a non-root user tries to unmount a filesystem that was mounted by a different user. 💀
  • -S, --status — gives you info on whether the specified target is currently mounted or not. a little vibe check for your filesystem 🔍
  • -l, --list — lists all available targets, including basic information about the filesystem and mount point of each. window shopping ✨
  • -c, --change-password — change the password that protects the decryption key for a given filesystem. glow-up for your password 🌈
  • -g, --generate-key size — set up a decryption key for a new filesystem. size gives the length of the key in bytes.
  • -e, --reuse-key existing-target — set up a decryption key for a new filesystem using an existing key from another filesystem. the use case: translating 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. this is the move when you're using cryptmount inside scripts or GUI wrappers. each password is read once only here — 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. the intention here is 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. typically you'd use this to automatically mount encrypted filesystems, or to 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. 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 it's 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 means something went sideways, and here's the tea:

  1. 1 — unrecognized command-line option;
  2. 2 — unrecognized filesystem target name;
  3. 3 — failed to execute helper program;
  4. 100 — insufficient privilege;
  5. 101 — security failure in installation.

🦋 EXAMPLE USAGE 🦋

So you wanna create a new encrypted filesystem managed by cryptmount? you can use the supplied cryptmount-setup program — the superuser can use it to interactively configure a basic setup. easy mode. 💖

Alternatively, a manual setup allows more control over configuration settings. before doing that though, you should make sure kernel support for /dev/loop and /dev/mapper is available, e.g. via

modprobe -a loop dm-crypt

now, suppose 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 it 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 (which is 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/disk/by-id/dm-name-opaque).

heads up bestie: 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/disk/by-id/dm-name-opaque:

mke2fs /dev/disk/by-id/dm-name-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 that ensures only the same user (or root) can unmount it. that's main character energy, honestly. 👑

🔑 PASSWORD CHANGING 🔑

after a filesystem has been in use for a while, you might 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, you 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. no cap, just the key gets a new fit.) 💅

🧚 LUKS ENCRYPTED FILESYSTEMS 🧚

cryptmount can be used to provide easy access to encrypted filesystems that are 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. don't do it bestie, it's giving chaos 💀

📁 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 🫶

okay bestie, legal era, but make it cute 💖

cryptmount is (C)Copyright 2005-2026, RW Penney, and it comes to you with NO WARRANTY — like, none, zero, nada, you are on your own in the best way possible 🙈

The licencing terms are all spelled out in the file "COPYING" inside the cryptmount source distribution. so if you wanna know the fine print, that's where the fine print lives, go read it, it's giving very legit 📜✨

and that's the whole page, bestie!! you made it to the end, iconic behaviour honestly 👑💅

this was cryptmount 6.4.0, dated 2024-07-21 — go mount something, stay encrypted, stay slay 🦋🔐✨

📦 where this page comes from