Tomb/doc/tomb.1

.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 "create"
Creates a new encrypted storage tomb and its key, named as specified
by the given \fIargument\fR.

.B
.IP "open"
Opens an existing tomb file specified in the \fIfirst argument\fR. If
a \fIsecond argument\fR is given it will indicate the \fImountpoint\fR
where the tomb should be made accessible, if not then the tomb is
mounted in a directory named after the filename and inside /media.

.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 \fIfirst
argument\fR is present, then shows only the tomb named that way or
returns an error if its not found.

.B
.IP "close"
Closes a currently open tomb.  When \fIan argument\fR is specified, it
should be the name of a mounted tomb; if not specified and only one
tomb is open then it will be closed; if multiple tombs are open, the
command will list them on the terminal. The special
\fIargument\fR 'all' will close all currently open tombs. This command
fails if the tomb is in use by running processes, the command
\fIslam\fR can be used to force close.

.B
.IP "passwd"
Changes the password of a tomb key file specified in the \fIfirst
argument\fR. It will need the old password to decode the key file, it
will then reencode it using the new password.

.B
.IP "resize"
Increase the size of a tomb file to the amount of megabytes specified
by the \fI-s\fI option (total amount of the new size). 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 "slam"
Closes a tomb like the command \fIclose\fR does, but in case it is in
use looks for all the processes accessing its files and violently
kills them using \-9.

.B
.IP "bury"
Hides a tomb key (\fIfirst argument\fR) inside a jpeg image (\fIsecond
argument\fR) using steganography: the image will change in a way that
cannot be noticed by human eyes and the presence of the key inside it
isn't detectable without the right password. This option is useful to
backup tomb keys in unsuspected places; it uses steghide and the
serpent encryption algorithm.

.B
.IP "exhume"
Extracts a named tomb key (\fIfirst argument\fR) from a (jpeg) image file
(\fIsecond argument\fR) known to be containing it, if the right password is
given. This is used to recoved buried keys from unsuspected places.

.SH OPTIONS
.B
.B
.IP "-s \fI<MBytes>\fR" 
When creating or resizing a tomb, this option MUST be used to specify
the size of the new \fIfile\fR to be created, in megabytes.
.B
.IP "-k \fI<keyfile>\fR"
When opening a  tomb, this option can be used  to specify the location
of the  key 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. When a key is  not found, the program asks to insert a
USB storage device and it will look for the key file inside it.
If \fI<keyfile>\fR is "-" (dash), it will read stdin
.IP
When creating a tomb, this option can be used to specify the name (and
location) of the key you are creating. For example, you could use
.EX
tomb create -s 100 tombname -k /media/usb/tombname
.EE
to put the key on a usb pendrive

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

  mail          mail
  .gnupg        .gnupg
  .fmrc         .fetchmailrc
  .mozilla      .mozilla

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