Provided by: cryptmount_6.2.0-1_amd64 bug

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.