Tomb/doc/tomb.1

.TH tomb 1 "May 25, 2013" "tomb"

.SH NAME
Tomb \- the Crypto Undertaker

.SH SYNOPSIS
.B
.IP "tomb [options] command [arguments]"

.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.


.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 search index of a specific tomb (or all tombs)
open: enables use of the \fIsearch\fR command using simple word
patterns on file names. Indexes are created using updatedb(8) and
stored in an .updatedb file inside the tomb's root. To avoid indexing
a specific tomb simply touch a \fI.noindex\fR file in its root.

.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 in all open tombs on which the \fIindex\fR command was run
at least once. 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<MBytes>\fR" 
When digging or resizing a tomb, this option must be used to specify
the \fIsize\fR of the new file to be created. Units are megabytes (MiB).
.B
.IP "-k \fI<keyfile>\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<keyfile>\fR is "-" (dash), it will read it from
stdin.

.B
.IP "--kdf \fI<method>\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<method>\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 when required.

To be made available on multi user systems, the superuser execution of
the tomb script can be authorized for users without jeopardizing the
whole system's security: just add such a line to \fI/etc/sudoers\fR:

.EX
	username ALL=NOPASSWD: /usr/local/bin/tomb
.EE

.SH SWAP

On execution of certain commands Tomb will complain about swap memory
on disk when that is presend 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 partition. Tomb doesn't detect if
your swap is encrypted, and will complain anyway.

.SH EXAMPLES

.IP \(bu
Create a 128MB large "secret" tomb and its keys, then open it:

.EX
	tomb dig -s 128 secret.tomb
	tomb forge secret.tomb.key
	tomb lock secret.tomb secret.tomb.key
	tomb open secret.tomb -k secret.tomb.key
.EE

.IP \(bu
Create a bind hook that places your GnuPG folder inside the tomb, but
makes it reachable from the standard $HOME/.gnupg location every time
the tomb will be opened:

.EX
	tomb open GPG.tomb
	echo ".gnupg .gnupg" > /media/GPG.tomb/bind-hooks
	mv ~/.gnupg /media/GPG.tomb/.gnupg && mkdir ~/.gnupg
	tomb close GPG && tomb open GPG.tomb
.EE

.IP \(bu
Create an exec post hook that launches a Firefox browser every time
the tomb will be opened, keeping all its profile data inside it:

.EX
	tomb open FOX.tomb
	touch        /media/FOX.tomb/post-hooks
	chmod +x     /media/FOX.tomb/post-hooks
	cat <<EOF >> /media/FOX.tomb/post-hooks
#!/usr/bin/env bash
if [ "$1" == open ]; then
  firefox -no-remote -profile $(dirname $0)/firefox_prof &
fi
EOF
.EE

.SH BUGS
Please report bugs on the tracker at
.UR https://bugs.dyne.org
.UE

Get in touch with developers via mail by subscribing the "crypto" mailinglist
.UR http://lists.dyne.org
.UE
or via the #dyne chat channel on
.UR https://irc.dyne.org
.UE

.SH AUTHORS

Tomb is designed, written and maintained by Denis Roio aka Jaromil.

Tomb includes code by Anathema, Boyska and Hellekin O. Wolf.

Tomb's artwork is contributed by Jordi aka Mon Mort

Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
Asbesto Molesto and Nignux.

Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth

.SH COPYING

This manual is Copyright (c) 2011-2013 by Denis Roio <\fIjaromil@dyne.org\fR>

This manual 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