.TH CRYPTFS.XML 5 "March 3, 2009" "DM CryptFS" "DM CryptFS" .SH NAME cryptfs.xml \- configuration file for cryptfs .SH DESCRIPTION The .I /etc/cryptfs.xml file describes the physical storage to use, how keys for the encryption are derived, which cipher should be used and which other actions to take when the encrypted partitions are mapped to logical devices with the decrypted filesystem. The root XML element is \fIdmcrypt\fR, which doesn't have any additional attributes. It can contain \fBoption\fR, \fBallow\fR, \fBdeny\fR, \fBtty\fR, \fBstorage\fR and \fBaction\fR elements. .SH Options An option consists of a \fIname\fR and and a \fIvalue\fR: <\fBoption\fR \fBname\fR="\fIname\fR" \fBvalue\fR="\fIvalue\fR"/> The following options are available. .RS .TP .B fsck Shall the decrypted filesystems be checked using .BR fsck ? .BR "" "Values: " "\(dqyes\(dq" ", " "\(dqno\(dq" .br .BR "" "Default: " "\(dqyes\(dq" .TP .B mount Shall the decrypted filesystems be mounted? .BR "" "Values: " "\(dqyes\(dq" ", " "\(dqno\(dq" .br .BR "" "Default: " "\(dqyes\(dq" .SH Access Control When running with suid flag access control is activated. As a default everything is denied. All global \fBallow\fR and \fBdeny\fR elements and the elements from the Action and Mapping are evaluated in this order. The last element that matches the user will allow or deny the action. <\fBallow\fR [ \fBuid\fR="\fIuser\fR" ] [ \fBgid\fR="\fIgroup\fR" ]/> <\fBdeny\fR [ \fBuid\fR="\fIuser\fR" ] [ \fBgid\fR="\fIgroup\fR" ]/> The following conditions can be given: .RS .TP \fBuid\fR="\fIuser\fR" Matches if the uid of the calling user is \fIuser\fR. .TP \fBgid\fR="\fIgroup\fR" Matches if the calling user belongs to this \fIgroup\fR. .RE These elements can contain \fBallow\fR and \fBdeny\fR elements themselves. These elements only match when the superior element matches but can override their decision. .SH TTYs For some operations (like asking for a passphrase or for fsck) a TTY is required. Normally cryptfs will check whether his standard input and output qualify as a TTY and if they don't opens a new virtual terminal. With the tty elements you can change this behavior and specify how to get a TTY. cryptfs will try each .B tty element until it finds a tty. <\fBtty\fR \fBtype\fR="\fItype\fR" [ \fIoptions...\fR ]/> These are the available types: .RS .TP .B current Use the tty cryptfs is currently attached to (if there is one). .TP .B fixed Open the (in the .BR dev attribute) given block device and use it as a tty. .TP .B vt Switch to a new virtual terminal. .TP .B xterm Use an xterm. .RE Some types may have additional parameters: .RS .TP .BR dev "=\(dq\fIfile\fR\(dq" Use the device \fIfile\fR as the tty .BR "" "(" fixed " only)." .TP .BR min "=\(dq\fInumber\fR\(dq" The smallest virtual terminal number to use .BR "" "(" vt " only)." .BR "" "Default: " "\(dq1\(dq" .TP .BR cmd "=\(dq\fIxterm-command\fR\(dq" Command for starting xterm. It can include additional options for xterm. .BR "" "(" xterm " only)." .BR "" "Default: " "\(dqxterm\(dq" (This may not work if xterm's directory is not in .BR PATH .) .TP .BR display "=\(dq\fIdisplay\fR\(dq" The X display to connect to. .BR "" "(" xterm " only)." .BR "" "Default: The " DISPLAY " environment variable." .TP .BR authority "=\(dq\fIauthority-file\fR\(dq" The .I .Xauthority file for connecting to the given display. .BR "" "(" xterm " only)." .BR "" "Default: The " XAUTHORITY " environment variable." .RE The .B tty elements can also contain .BR preexec " and " postexec elements, which are explained later .BR "" "(See " "Preexec, Postexec" " below)." .SH Storage For each block device there is a list of the encrypted filesystems it contains. Each entry contains the name of the filesystem, the cipher, the size of this filesystem block and the start position within the entire device. <\fBstorage\fR \fBdevice\fR="\fIfilename\fR"> <\fBentry\fR \fBname\fR="\fIfsname\fR" \fBcipher\fR="\fIcipher\fR" [ \fBsize\fR="\fIsize\fR" ] [ \fBstart\fR="\fIposition\fR" ]/> [ \fIadditional entries...\fR ] If there's only one filesystem or for the last filesystem the \fIsize\fR can be omitted. It will then fill the entire block device. The position can always be omitted, if there are no gaps between the filesystems. A \fIfilename\fR can occor more than once. The corresponding blocks will then be concatenated to build a single filesystem. The \fIsize\fR and \fIposition\fR should be given in sectors (512 bytes). .SH Actions An action defines which filesystem will be decrypted, how the corresponding key should be derived and which additional operations should be performed. Each action has a unique name which is given to .B cryptfs as a parameter to execute this action. <\fBaction\fR \fBname\fR="\fIname\fR"> [ \fBallow\fR & \fBdeny\fR\fI rules...\fR ] [ \fBpreexec\fR\fI commands...\fR ] <\fBkey\fR \fBtype\fR="\fIkeytype\fR" [ \fIoptions...\fR ]> \fIprompt, command, filename, subkeys or a literal password\fR <\fBmap\fR \fBname\fR="\fIfsname\fR" [ \fIoptions...\fR ]> [ \fIallow & deny rules, preexec commands, own key definition, preexec commands...\fR ] [ \fIadditional mappings...\fR ] [ \fBpostexec\fR\fI commands...\fR ] [ \fBcall\fR\fI statements...\fR ] .SS Keys The \fBkey\fR element is used for each \fBmap\fR element unless it has its own \fBkey\fR element. If all mappings have their own key definition the \fBkey\fR element in the \fBaction\fR element can be omitted. The following \fIkey types\fR are offered: .RS .TP .B passphrase Asks for a passphrase, which will then be hashed. A prompt can be given as the contents of the \fBkey\fR element. .TP .B file Takes a file directly as the key. The file should be given as the contents of the \fBkey\fR element. .TP .B program Executes a program and hashes its standard output. The command should be given as the contents of the \fBkey\fR element. .TP .B literal Takes the contents of the \fBkey\fR element and hashes it. .TP .B composite Several subkeys (also \fBkey\fR elements) are XORed together. .RE The \fBkey\fR element can have additional attributes: .RS .TP \fBid\fR="\fIunique id\fR" Using this id the key can be referenced later (e.g. in another action or as a part of another composite key). If it is a passphrase it will be only asked once, if it is a command it will be executed only once. To reference the key <\fBkey\fR \fBid\fR="\fIunique id\fR"/> (without \fBtype\fR or any other option) will then suffice. .TP \fBlength\fR="\fIkey length\fR" The needed key length. .TP \fBalgo\fR="\fIhash algorithm\fR" This specifies the hash algorithm to be used. It can be something like \fB"md5"\fR, \fB"sha1"\fR, \fB"rmd160"\fR, \fB"sha256"\fR, \fB"sha512"\fR or \fB"none"\fR or any other hash algorithm that is supported by \fBlibgcrypt\fR (\fBpassphrase\fR, \fBprogram\fR and \fBliteral\fR only). Default: \fB"sha256"\fR or if the key length is given one of the SHA family that is long enough. .TP \fBnewline\fR="\fInewline handling\fR" Says, whether a newline at the end of a passphrase should be added (if there isn't one), removed (at most one) or left unchanged (\fBpassphrase\fR, \fBprogram\fR and \fBliteral\fR only). Values: \fB"add"\fR, \fB"remove"\fR, \fB"unchanged"\fR .br Default: \fB"unchanged"\fR .TP \fBretry\fR="\fImaximal number of retries\fR" If cryptfs detects that the given key is wrong it can try and ask again. The only way such a situation can occur is because of a failed fsck, mount or \fBpostexec\fR command. (\fBpassphrase\fR, \fBfile\fR and \fBprogram\fR only). Values: \fB"infinite"\fR or a number .br Default: \fB"0"\fR .TP \fBvt100\fR="\fInumber of lines to reserve\fR" If given cryptfs reserves the number of lines of the bottom of the screen for showing the passphrase prompt. Scrolling does then only happen in the area above these lines (\fBpassphrase\fR only). .TP \fBignorestatus\fR, \fBuid\fR, \fBgid\fR, \fBneedtty\fR Have the same meaning as in the \fBpreexec\fR and \fBpostexec\fR elements. See below. (\fBprogram\fR only) .RE The \fBkey\fR element can also contain \fBpreexec\fR and \fBpostexec\fR elements to execute commands just before and after the evaluation of the key. .SS Mappings The \fBmap\fR element specify which filesystem should be decrypted. Normally a <\fBmap\fR \fBname\fR="\fIfsname\fR"/> is enough to decrypt the filesystem \fIfsname\fR (defined in the \fBstorage\fR section earlier) with the key given in the \fBaction\fR element. A new block device with this name will be put into \fI/dev/mapper\fR and according to the global options this filesystem will be checked and mounted. But the \fBmap\fR element can also have the following attributes: .RS .TP \fBas\fR="\fIdname\fR" Specifies the name which the resulting device should get in the /dev/mapper directory. If you create ambiguities using this option, then cryptfs with the -n option cannot solve them. Default: the value of the \fBname\fR attribute .TP \fBfsck\fR="\fIdo fsck\fR" Overrides the general \fBfsck\fR option and says whether the filesystem should be \fBfsck\fRed. Values: \fB"yes"\fR, \fB"no"\fR .br Default: \fB"no"\fR if \fBro="yes"\fR, global \fBfsck\fR option otherwise .TP \fBmount\fR="\fIdo mount\fR" Overrides the general \fBmount\fR option and says whether the filesystem should be mounted. Values: \fB"yes"\fR, \fB"no"\fR .br Default: global \fBmount\fR option .TP \fBpoint\fR="\fImount point\fR" The mount point of this filesystem (can be omitted if it's in \fI/etc/fstab\fR or should not be mounted). .TP \fBfs\fR="\fIfilesystem\fR" The filesystem type (can be omitted if it's in \fI/etc/fstab\fR or should not be mounted). .TP \fBoptions\fR="\fImount options\fR" Mount options. .TP \fBro\fR="\fIread-only\fR" Sets the block device to read-only. This also sets \fBfsck\fR to \fB"no"\fR unless explicitly set to \fB"yes"\fR. Values: \fB"yes"\fR, \fB"no"\fR .br Default:\fB"no"\fR .TP \fBuid\fR="\fIuser\fR" Sets the uid of the block device to \fIuser\fR. .TP \fBgid\fR="\fIgroup\fR" Sets the gid of the block device to \fIgroup\fR. .TP \fBmode\fR="\fImode\fR" Sets the permissions of the block device to \fImode\fR. \fImode\fR should be a number greater than zero, if given in its octal representation a \fB0\fR should be prepended. .RE The \fBmap\fR element may have some \fBallow\fR or \fBdeny\fR rules that will override the ones from the \fBaction\fR element. It can also contain \fBpreexec\fR and \fBpostexec\fR elements to execute commands just before and after the mapping/mounting. .SS Calls The \fBcall\fR element allows to call other actions. These actions may be specified in the same or another XML file. Calls are always done regardless of the success of the current action. .RS .TP \fBaction\fR="\fIaction name\fR" The name of the action to be called (this is mandatory). .TP \fBfile\fR="\fIfilename\fR" The name of the XML file if the action is defined in another XML file (should be omitted if it's in the same file). .TP \fBro\fR, \fBuid\fR, \fBgid\fR, \fBmode\fR, \fBfsck\fR, \fBmount\fR Override similar options in \fBmap\fR and \fBcall\fR elements of the called action. .SH Preexec, Postexec Within the \fBtty\fR, \fBaction\fR, \fBmap\fR and \fBkey\fR element additional commands can be given which will be executed just before or just after everything else. <\fBpreexec\fR [ \fIoptions ...\fR ]> command <\fBpostexec\fR [ \fIoptions ...\fR ]> command The command will be executed using \fB/bin/sh -e\fR and therefore may use shell commands. The following options can be given. .RS .TP \fBignorestatus\fR="\fIstatus handling\fR" Specifies whether the return status of the command should be ignored. Otherwise a return state other than zero will be interpreted as an error und thus the whole operation be aborted. Values: \fB"yes"\fR, \fB"no"\fR .br Default: \fB"no"\fR .TP \fBuid\fR="\fIuser\fR" Execute this program under the uid \fIuser\fR. Default: The uid of the calling program. .TP \fBgid\fR="\fIgroup\fR" Execute this program under the gid \fIgroup\fR. Default: The gid of the calling program. .TP \fBneedtty\fR="\fItty necessity\fR" If \fB"yes"\fR cryptfs makes sure, that the program has a TTY connected to its input and output. See \fBTTYs\fR above. Values: \fB"yes"\fR, \fB"no"\fR .br Default: \fB"no"\fR .TP \fBonstate\fR="\fIwhen\fR" This is particularly interesting for \fBpostexec\fR commands and says, whether this command should be executed after a successful or aborted action. Values: \fB"success"\fR, \fB"failure"\fR, \fB"always"\fR .br Default: \fB"success"\fR .TP \fBonmode\fR="\fIwhen\fR" cryptfs can be called with \fB-m\fR or \fB-n\fR to only map or mount the corresponding block devices. This attribute specifies in which mode these commands should be executed. (It does not depend on the \fBfsck\fR and \fBmount\fR options in the XML file.) Values: \fB"map"\fR, \fB"mount"\fR, \fB"always"\fR .br Default: \fB"mount"\fR within \fBaction\fR and \fBmap\fR, \fB"map"\fR within \fBkey\fR and \fB"always"\fR within \fBtty\fR elements. .RE .SH EXAMPLE This example show a two factor authorization using a passphrase and an USB stick. pidof X >/dev/null mount /media/usbstick /media/usbstick/hdkey if [ -n "$DISPLAY" ]; then Xdialog \(rs --backtitle 'HD Encryption' \(rs --stdout \(rs --passwordbox \(rs 'Please enter the password:' \(rs 12 40 else dialog \(rs --backtitle 'Encryption for Alex' \(rs --clear --stdout \(rs --passwordbox \(rs 'Please enter the password:' \(rs 8 50 fi umount /media/usbstick .SH SEE ALSO .BR cryptfs (8), .BR dmsetup (8),