.\" cryptmount manual page.\" $Revision: 117 $, $Date: 2006-07-30 10:20:45 +0100 (Sun, 30 Jul 2006) $.\" Copyright (c) 2005,2006 RW Penney.\".TH CRYPTMOUNT 8 "2006-07-17" "@PACKAGE_VERSION@" "User commands".SH NAMEcryptmount \- mount/unmount/configure an encrypted filing system.\" --------------------------------.SH SYNOPSIS.BI "cryptmount [\-aclmu] [target ...]".LP.BI "cryptmount [\-\-change\-password [target ...]]".LP.BI "cryptmount [\-\-generate\-key \fIsize\fP [target ...]]".LP.BI "cryptmount [\-\-prepare [target ...]]".LP.BI "cryptmount [\-\-release [target ...]]"___DELETE_CSWAP_0.LP.BI "cryptmount [\-\-swapon [target ...]]".LP.BI "cryptmount [\-\-swapoff [target ...]]"___END_CSWAP_0.\" --------------------------------.SH DESCRIPTION.Bcryptmountallows a user to mount an encrypted filing systemwithout requiring superuser privileges,and assists the superuser in creating new encrypted filesystems.After initial configuration of the filing system by the system administrator,the user needs only to provide the decryption password for that filing sytem in order for.B cryptmountto automatically configure device-mapper and loopback targets before mounting the filing system..B cryptmountwas written in response to differences betweenthe newer device-mapper infrastructure of the linux-2.6 kernel series,and the older cryptoloop infrastructure which allowed ordinary usersaccess to encrypted filing systems directly through.B mount(8)..\" --------------------------------.SH OPTIONS.TP.B \-a \-\-allact on all available targets, e.g. for mounting all targets..TP.B \-m \-\-mountmount the specified target, configuring any required device-mapperor loopback devices.The user will be asked to supply a password to unlockthe decryption key for the filing system..TP.B \-u \-\-unmountunmount the specified target, and deconfigure any underlying device-mapperor loopback devices.No password is required, although the operation will failif the filing system is in use, or if a non-root user triesto unmount a filing system mounted by a different user..TP.B \-l \-\-listlists all available targets, including basic information about the filing system and mount point of each..TP.B \-c \-\-change\-passwordchange the password protecting the decryption key for a given filing system..TP.B \-\-generate\-key "\fIsize\fP"setup a decryption key for a new filing system..IR size\fPgives the length of the key in bytes..TP.B \-\-prepareprepare 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 filing system on an encrypted device..TP.B \-\-releasereleases all device-mapper and loopback devices associated with a particular target. This option is only available to the superuser.___DELETE_CSWAP_0.TP.B \-\-swaponenable the specified target for paging and swapping.This option is only available to the superuser..TP.B \-\-swapoffdisable the specified target for paging and swapping.This option is only available to the superuser.___END_CSWAP_0.\" --------------------------------.SH RETURN CODES.B cryptmountreturns zero on success.A non-zero value indicates a failure of some form, with specific values traceable, in principle, to different error conditions..\" --------------------------------.SH EXAMPLE USAGESuppose that we wish to setup a new encrypted filing system, that will have a target-name of "opaque".If we have a free disk partition available, say /dev/hdb63, then we can use this directly to store the encrypted filing system.Alternatively, if we want to store the encrypted filing system within an ordinary file, we need to create space using a recipe such as:.nf    dd if=/dev/zero of=/home/opaque.fs bs=1M count=512.fiand then replace all occurences of '/dev/hdb63' in the followingwith '/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 @etcdir@/cmtab,which describes the encryption that will be usedto protect the filesystem itself and the access key, as follows:.nf    opaque {        dev=/dev/hdb63 dir=/home/crypt        fstype=ext2 fsoptions=defaults cipher=twofish        keyfile=@etcdir@/opaque.key keyhash=md5 keycipher=bf\-cbc    }.fiHere, we will be using the "twofish" algorithm to encryptthe filing system itself,with the "bf\-cbc" and "md5" algorithms being usedto protect the decryption key (to be stored in @etcdir@/opaque.key).In order to generate a secret decryption key (in @etcdir@/opaque.key)that will be used to encrypt the filing system itself,we can execute, as root:.nf    cryptmount \-\-generate\-key 32 opaque.fiThis will generate a 32-byte (256-bit) key,which is known to be supported by the Twofish cipher algorithm,and store it in encrypted formafter asking the system administrator for a password.If we now execute, as root:.nf    cryptmount \-\-prepare opaque.fiwe will then be asked for the password that we used when setting up @etcdir@/opaque.key, which will enable.B cryptmountto setup a device-mapper target (/dev/mapper/opaque).(Alternatively, if the encrypted filing system resides on a raw disk partition, one can use.B cryptsetup(8)as follows:.nf    openssl enc \-d \-md md5 \-bf\-cbc @etcdir@/opaque.key | \\    cryptsetup \-c twofish \-d /dev/stdin create opaque /dev/hdb63.fito perform a similar process.)We can now use standard tools to create the actual filing system on /dev/mapper/opaque:.nf    mke2fs /dev/mapper/opaque.fi(It may be advisable, after the filesystem is first mounted,to check that the permissions of the top-level directorycreated by mke2fs are appropriate for your needs.)After executing.nf    cryptmount \-\-release opaque    mkdir /home/crypt.fi(or using the equivalent recipe for.Bcryptsetup), the encrypted filing system is ready for use.Ordinary users can mount it by typing.nf    cryptmount \-m opaque.fior.nf    cryptmount opaque.fiand unmount it using.nf    cryptmount \-u opaque.fi.B cryptmountkeeps a record of which user mounted each filesystemin order to provide a locking mechanism to ensure thatonly the same user (or root) can unmount it..\" --------------------------------.SH PASSWORD CHANGINGAfter 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:.nf    cryptmount \-\-change\-password opaque.fiAfter successfully supplying the old password, one can then choosea new password which will be used to re-encrypt the access key for thefilesystem.(The filesystem itself is not altered or re-encrypted.)___DELETE_FSCK_1.\" --------------------------------.SH FILESYTEM MAINTENANCEFor filesystems that are mounted on system-startup,it is normal for checks on their integrityto be performed automatically at regular intervals,typically every few dozen mounts.If.B cryptmounthas not been compiled with the '\-\-enable\-fsck' option,such checks need to be performed manuallyfor filesystems managed by.B cryptmount, which will require the involvement of both the system administratorand the users who know the relevant access passwordsfor the filing systems involved.Suppose that we wish to check the filesystem associated with.B cryptmounttarget 'opaque', we first need to prepare the decryption devices:.nf    cryptmount \-\-prepare opaque.fithis will create a device-mapper target accessible via '/dev/mapper/opaque', on which we can then run standard checking utilities:.nf    fsck \-t auto /dev/mapper/opaque.fiAfter these tests have been completed, we can then release the devices:.nf    cryptmount \-\-release opaque.fiand continue using the filesystem as before.___END_FSCK_1.\" --------------------------------.SH FILES.I @etcdir@/cmtab- main configuration file.LP.I @etcdir@/cmstatus- record of mounted filesystems.SH "SEE ALSO".BR cmtab (5),.BR cryptsetup (8),.BR dmsetup (8),.BR fsck (8),.BR mount (8),.BR openssl (1).\" --------------------------------.SH BUGSThe author would be grateful for any.B constructivesuggestions and bug-reports, via <rwpenney@users.sourceforge.net>.\" --------------------------------.SH COPYRIGHT NOTICE.B cryptmountis Copyright 2005-2006 RW Penney.brand is supplied with NO WARRANTY.Licencing terms are as described in the file "COPYING"within the cryptmount source distribution.