.TH tomb 1 "Sept 26, 2011" "tomb" .SH NAME Tomb \- the Crypto Undertaker .SH SYNOPSIS .B .IP "tomb [options] command [arguments]" .B .IP "tomb-open [file]" .B .IP "tomb-status mountpoint" .SH DESCRIPTION Tomb is an application to manage the creation and access of encrypted storage files: it can be operated from commandline and it can integrate with a user's graphical desktop. Tomb generates encrypted storage files to be opened and closed using their associated keys, which are also protected with a password chosen by the user. To create, open and close tombs a user will need super user rights to execute the tomb commandline utility. A tomb is like a locked folder that can be safely transported and hidden in a filesystem; it encourages users to keep their keys separate from tombs, for instance keeping a tomb file on your computer harddisk and its key file on a USB stick. For simplified use, the command \fItomb-open\fR starts a wizard that guides users in the creation of a new tomb or, if a tomb file is specified as \fIargument\fR, it opens it and makes it accessible in a default location under the /media folder, starting the status tray applet (\fItomb-status\fR) if a desktop is present. .SH COMMANDS .B .IP "dig" Generates a file that can be used as a tomb and will occupy as much space as its desired initial size, the unlocked \fI.tomb\fR file can then be locked using a \fI.tomb.key\fR. It takes a mandatory option which is the \fI--size\fR in megabytes. This generation is relatively simple: its a data dump (dd) of low-quality random data (from /dev/urandom) and does not require root privileges. .B .IP "forge" Creates a new \fIkey\fR and prompts the user for a \fIpassword\fR to protect its usage. This operation requires high quality random data (from /dev/random) which can take quite some time to be gathered on a server: it works better on a desktop where the mouse can be moved around for entropy. .B .IP "lock" Initializes and locks an empty tomb (made with \fIdig\fR) using a key (made with \fIforge\fR), making it ready for usage. After this operation, the tomb can only be open in possession of the key and knowing its password. This operation requires root privileges to loopback mount, format the tomb (using LUKS and Ext4), then set the key in its first LUKS slot. .B .IP "open" Opens an existing \fI.tomb\fR (first argument), if a second argument is given it will indicate the \fImountpoint\fR where the tomb should be made accessible, else the tomb is mounted in a directory inside /media. The option \fI-k\fR can be used to specify a key file if none is found besides the tomb and \fI-o\fR can be used to pass mount(8) options (default: rw,noatime,nodev). .B .IP "list" List all the tombs found open, including information about the time they were opened and the hooks that they mounted. If the first argument is present, then shows only the tomb named that way or returns an error if its not found. .B .IP "index" Creates or updates the \fIsearch index\fR of a tomb, or all tombs currently opened if none is specified. Indexes are created using updatedb(8) and enable users to run quick search commands using simple word patterns. .B .IP "search" Searches through all tombs currently open for filenames matching one or more text patterns given as arguments. Search returns a list of files found inside the tombs that have been previously indexed using locate(1). The option \fI--regex\fR can be used to interpret all patterns as extended regexps. .B .IP "close" Closes a currently open tomb. If more tombs are open, the first argument should be used to specify the name of the tomb to be closed, or \fIall\fR to close all currently open tombs. This command fails if the tomb is in use by running processes (to force close, see \fIslam\fR below). .B .IP "slam" Closes a tomb like the command \fIclose\fR does, but it doesn't fails even if the tomb is in use by other application processes: it looks for them and violently kills \-9 each of them. This command may provoke unsaved data loss, but assists users to face surprise situations. .B .IP "passwd" Changes the password protecting a \fIkey\fR file specified as first argument. The user will need to know the key's current password, then its content will be decoded and reencoded using the new one. This action can't be forced if the current password is not known. .B .IP "resize" Increase the size of a tomb file to the amount specified by the \fI--size\fR option (in megabytes). Tombs cannot be made smaller with this command, only bigger. This command makes use of the cryptsetup resize feature and the resize2fs command, hence it supports only tombs formatted with an Ext filesystem. .B .IP "bury" Hides a tomb key (first argument) inside a \fIjpeg image\fR (second argument) using \fIsteganography\fR: the image will change in a way that cannot be noticed by human eye and hardly detected by data analysis. This option is useful to backup tomb keys in unsuspected places; it depends from the availability of \fIsteghide\fR. .B .IP "exhume" This command recovers from jpeg images the keys that were previously hidden into them using \fIbury\fR. Exhume requires a key filename (first argument) and a \fIjpeg image\fR file (second argument) known to be containing it. If the right key password is given, the key will be exhumed, but if the password is not known, it is very hard to verify if a key is buried in the image or not. .SH OPTIONS .B .B .IP "-s \fI\fR" When digging or resizing a tomb, this option must be used to specify the \fIsize\fR of the new file to be created, in megabytes. .B .IP "-k \fI\fR" When opening a tomb, this option can specify the location of the key file to use. Keys are created with the same name of the tomb file adding a '.key' suffix, but can be later renamed and transported on other media. If \fI\fR is "-" (dash), it will read it from stdin. .B .IP "--kdf \fI\fR" This will specify the KDF method to use for the tomb we're creating. Please note that no stable release of tomb supports KDF; if you use it, your tomb might be unusable with an older version of tomb. You can specify parameters with --kdf=method:param. That is, for example, \fI--kdf=pbkdf2:2.5\fR will use pbkdf2 with an itertime of 2.5 seconds Supported methods are: pbkdf2, null .B pbkdf2 is probably the most used kdf in security applications, so it's a good choice. It accepts one parameter, that is the seconds it will take on this computer to derive the key. The default is 1. .B null is just the same as not using --kdf at all: it will stick to the "classic" behaviour .B .IP "--kdf \fI\fR" This will specify the KDF method to use for the tomb we're creating. Please note that no stable release of tomb supports KDF; if you use it, your tomb might be unusable with an older version of tomb. .B .IP "-n" Skip processing of post-hooks and bind-hooks if found inside the tomb. See the \fIHOOKS\fR section in this manual for more information. .B .IP "-o" Manually specify mount options to be used when opening a tomb instead of the default \fIrw,noatime,nodev\fR. This option can be used to mount a tomb read-only (ro) to prevent any modification of its data, or to experiment with other settings (if you really know what you are doing) see the mount(8) man page. .B .IP "-f" Force flag, currently used to override swap checks, might be overriding more wimpy behaviours in future, but make sure you know what you are doing if you force an operation... .B .IP "-h" Display a help text and quit .B .IP "-v" Display version and quit .B .IP "-q" Run more quietly .B .IP "-D" Print more information while running, for debugging purposes .B .IP "--no-color" Don't use colors; useful for old terminals or integration in other scripts parsers .SH HOOKS Hooks are special files that can be placed inside the tomb and trigger actions when it is opened and closed; there are two kinds of such files: \fIbind-hooks\fR and \fIpost-hooks\fR can be placed in the base root of the tomb. .B .IP "bind-hooks" This hook file consists of a simple two column list of files or directories inside the tomb to be made directly accessible inside the current user's home directory. Tomb will use the "mount \-o bind" command to bind locations inside the tomb to locations found in $HOME so in the first column are indicated paths relative to the tomb and in the second column are indicated paths relative to $HOME contents, for example: .EX mail mail .gnupg .gnupg .fmrc .fetchmailrc .mozilla .mozilla .EE .B .IP "post-hooks" This hook file gets executed as user by tomb right after opening it; it can consist of a shell script of a binary executable that performs batch operations every time a tomb is opened. .SH PRIVILEGE ESCALATION The tomb commandline tool needs to acquire super user rights to execute most of its operations: to do so it uses sudo(8), while pinentry(1) is adopted to collect passwords from the user. Tomb executes as super user only those commands requiring it, while it executes desktop applications as processes owned by the user. .SH SWAP During "create", "open" and "passwd" operations, swap will complain and \fIabort if your system has swap activated\fR. You can disable this behaviour using the \fI--force\fR. Before doing that, however, you may be interested in knowing the risks of doing so: .IP \(bu During such operations a lack of available memory could cause the swap to write your secret key on the disk. .IP \(bu Even while using an opened tomb, another application could occupy too much memory so that the swap needs to be used, this way it is possible that some contents of files contained into the tomb are physically written on your disk, not encrypted. .P If you don't need swap, execute \fI swapoff -a\fR. If you really need it, you could make an encrypted swap it. Tomb doesn't detect if your swap is encrypted, and will complain anyway. .SH EXAMPLES Inline example: .EX test test .EE .SH BUGS Please report bugs on the tracker at .UR http://bugs.dyne.org .UE Get in touch with developers via mail using this .UR http://dyne.org/contact web page .UE or via chat on .UR http://irc.dyne.org .UE .SH AUTHORS Tomb is designed and written by Denis Roio aka Jaromil. Tomb includes code by Anathema and Boyska. Tomb's artwork is contributed by Jordi aka Mon Mort Testing and reviews are contributed by Hellekin O. Wolf, Dreamer, Shining, Mancausoft, Asbesto Molesto. Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth .SH COPYING This manual is Copyleft (c) 2011 Denis Roio <\fIjaromil@dyne.org\fR> It includes contributions by Boyska Permission is granted to copy, distribute and/or modify this manual under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation. Permission is granted to make and distribute verbatim copies of this manual page provided the above copyright notice and this permission notice are preserved on all copies. .SH AVAILABILITY The most recent version of Tomb sourcecode and up to date documentation is available for download from its website on \fIhttp://tomb.dyne.org\fR. .SH SEE ALSO .B .IP cryptsetup(8) GnuPG website on http://www.gnupg.org DM-Crypt website on http://www.saout.de/misc/dm-crypt LUKS website, http://code.google.com/p/cryptsetup