Provided by: tomb_2.9+dfsg1-1_amd64 
NAME
Tomb - the Crypto Undertaker
SYNOPSIS
tomb [options] command [arguments]
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.
COMMANDS
dig Generates a file that can be used as a tomb and will occupy as much space as its
desired initial size, the unlocked .tomb file can then be locked using a key. It
takes a mandatory -s option which is the size in megabytes (MiB). Tombs are digged
using random data gathered from a non-blocking source (/dev/urandom).
forge Creates a new key and prompts the user for a password to protect its usage using
symmetric encryption. This operation uses random data from a non-blocking source
(/dev/urandom) and it may take long only in some cases; to switch using a blocking
source the --use-random flag can be used. The -g option switches on the use of a
GPG key instead of a password (asymmetric encryption), then the -r option indicates
the recipient key; more recipient GPG ids can be indicated (comma separated). The
default cipher to protect the key is AES256, a custom one can be specified using
the -o option, for a list of supported ciphers use -v. For additional protection
against dictionary attacks on keys, the --kdf option can be used when forging a
key.
lock Initializes and locks an empty tomb (made with dig) using a key (made with forge),
making it ready for usage. After this operation, the tomb can only be opened in
possession of the key and knowing its password. As in any other command requiring a
key, the option -k should be used to specify a key file; in case of encryption to
GPG recipients the -g flag should be used followed by -r and the recipient's secret
GPG key id. The -o option can be used to specify the cipher specification: default
is "aes-xts-plain64", old versions of Tomb used "aes-cbc-essiv:sha256". If you are
looking for something exotic, also try "serpent-xts-plain64". More options may be
found in cryptsetup(8) and Linux documentation. The --filesystem option can be used
to specify "btrfs" as an alternative filesystem used to format the tomb, in place
of the default "ext4". This operation requires root privileges to loopback mount,
format the tomb (using LUKS and Ext4), then set the key in its first LUKS slot.
open Opens an existing tomb file (first argument) using a key (-k) which can also be
hidden inside a jpeg image (see bury/exhume) or a long text file
(seecloak/uncloak). If a second argument is given it will indicate the mountpoint
where the tomb should be made accessible, else the tomb is mounted in a directory
inside /media (if not available it uses /run/media/$USER). The option -o can be
used to pass mount(8) options (default: rw,noatime,nodev). The -g option is needed
when using GPG encryption to recipients.
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 it's not found. If the
option --get-mountpoint is used then print a simple list of currently open tomb
mountpoint paths.
ps List all the processes found running inside the tombs that are open, printing out
their PIDs and owners. This is useful to have an overview of programs that are
keeping the tombs busy and would eventually be killed by the slam command. The
lsof(8) utility is used internally to enumerate processes running in one or all
tombs.
index Creates or updates the search indexes of all tombs currently open: enables use of
the search command using simple word patterns on file names. Indexes are created
using mlocate's updatedb(8) and swish-e(1) if they are found on the system. Indexes
allow one to search very fast for filenames and contents inside a tomb, they are
stored inside it and are not accessible if the Tomb is closed. To avoid indexing a
specific tomb simply touch a .noindex file in it.
search Takes any string as argument and searches for them through all tombs currently open
and previously indexed using the index command. The search matches filenames if
mlocate is installed and then also file contents if swish++ is present on the
system, results are listed on the console.
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 all to close all currently
open tombs. This command fails if the tomb is in use by running processes (to force
close, see slam below).
slam Closes a tomb like the command close does, but it doesn't fail even if the tomb is
in use by other application processes: it looks for and closes each of them (in
order: TERM, HUP, KILL). This command may provoke unsaved data loss, but assists
users to face surprise situations. It requires lsof else it falls back to close.
passwd Changes the password protecting a key file specified using -k. With keys encrypted
for GPG recipients use -g followed by -r to indicate the new recipient key, or a
comma separated list.. The user will need to know the key's current password, or
possess at least one of the current recipients GPG secret keys, because the key
contents will be decoded and reencoded using the new passwords or keys. If the key
file is broken (missing headers) this function also attempts its recovery.
setkey Changes the key file that locks a tomb, substituting the old one with a new one.
Both the old and the new key files are needed for this operation and their
passwords or GPG recipient(s) secret keys must be available. The new key must be
specified using the -k option, the first argument should be the old key and the
second and last argument the tomb file. Use the -g option to unlock the tomb with a
GPG key, the -r to indicate the recipient or a comma separated list for more than
one recipient.
resize Increase the size of a tomb file to the amount specified by the -s option, which is
the new size in megabytes (MiB). Full access to the tomb using a key (-k) and its
password is required. Tombs can only grow and can never be made smaller. This
command makes use of the cryptsetup(8) resize feature and the resize2fs command:
its much more practical than creating a new tomb and moving everything into it.
There is no data-loss if a failure occurs during resize: the command can be re-
launched and the resize operation will complete.
engrave
This command transforms a tomb key into an image that can be printed on paper and
physically stored as backup, i.e. hidden in a book. It Renders a QRCode of the tomb
key, still protected by its password: a PNG image (extension .qr.png) will be
created in the current directory and can be later printed (fits an A4 or Letter
format). To recover an engraved key one can use any QRCode reader on a smartphone:
save it into a file and then use that file as a key (-k).
bury Hides a tomb key (-k) inside a jpeg image (first argument) using steganography: 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 steghide. Use the -g flag and -r option
followed by recipient id to use GPG asymmetric encryption.
exhume This command recovers from jpeg images the keys that were previously hidden into
them using bury. Exhume requires a key filename (-k) and a jpeg image file (first
argument) known to be containing a key. If the right key password is given, the key
will be exhumed. If the password is not known, it is very hard to verify if a key
is buried in any image or not.
cloak Hides a tomb key (-k) inside a long plain-text file (first argument) using
steganography: the text will change in a way that can hardly 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 cloakify and
consequently python2. This function does not support asymmetric encryption using
the -g flag.
uncloak
This command recovers from long plain-text files the keys that were previously
hidden into them using cloak. Cloak requires a key filename (-k) and a plain-text
file (first argument) known to be containing a key. If the right key password is
given, the key will be exhumed. If the password is not known, it is quite hard to
verify if a key is buried in a text or not.
OPTIONS
-k <keyfile>
For all operations requiring a key, this option specifies the location of the key
file to use. Arguments can also be jpeg image files where keys have been hidden
using the bury or cloak commands, or text files retrieved from engraved QR codes.
If the keyfile argument is "-" (dash), Tomb will read the key from stdin
(blocking).
-n Skip processing of exec-hooks and bind-hooks if found inside the tomb. See the
HOOKS section in this manual for more information.
-p When opening a tomb, preserves the ownership of all files and directories contained
in it. Normally the open command changes the ownership of a tomb's contents to the
UID and GID of the user who has successfully opened it: it is a usability feature
in case a tomb is used by a single user across different systems. This flag
deactivates this behaviour.
-o Manually specify mount options to be used when opening a tomb instead of the
default rw,noatime,nodev, i.e. to mount a tomb read-only (ro) to prevent any
modification of its data. Can also be used to change the symmetric encryption
algorithm for keys during forge operations (default AES256) or the LUKS encryption
method during lock operations (default aes-xts-plain64).
-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.
-s <MBytes>
When digging or resizing a tomb, this option must be used to specify the size of
the new file to be created. Units are megabytes (MiB).
-g Tell tomb to use a asymmetric GnuPG key encryption instead of a symmetric
passphrase to protect a tomb key. This option can be followed by -r when the
command needs to specify recipient(s).
-r <gpg_id>[,<gpg_id2>]
Provide a new set of recipient(s) to encrypt a tomb key. gpg_ids can be one or more
GPG key ID, comma separated. All GPG keys must be trusted keys in GPG.
--kdf <itertime>
Activate the KDF feature against dictionary attacks when creating a key: forces a
delay of <itertime> times every time this key is used. The actual time to wait
depends on the CPU speed of the computer where the key is used. Using 5 or 10 is a
sane amount for modern computers, the value is multiplied by 1 million.
--sphx-user <username>
Activate the SPHINX feature for password-authenticated key agreement. This option
indicates the <username> used to retrieve the password from a sphinx oracle key
reachable via TCP/IP.
--sphx-host <domain>
Activate the SPHINX feature for password-authenticated key agreement. This option
indicates the <domain> used to retrieve the password from a sphinx oracle daemon
reachable via TCP/IP. This is not the network address of the daemon, which is
configured in /etc/sphinx
-h Display a help text and quit.
-v Display version and quit.
-q Run more quietly
-D Print more information while running, for debugging purposes
DEV MODE
--no-color
Suppress colors in console output (needed for string parsing by wrappers).
--unsafe
Enable using dev-mode arguments, i.e. to pass passwords from commandline options.
This is mostly used needed for execution by wrappers and testing suite.
--use-random
Use a blocking random source. Tomb uses by default /dev/urandom since the non-
blocking source of Linux kernel doesn't degrades the quality of random.
--tomb-pwd <string>
Use string as password when needed on tomb.
--tomb-old-pwd <string>
Use string as old password when needed in tomb commands requiring multiple keys,
like passwd or setkey.
-U Switch to this user ID when dropping privileges.
-G Switch to this group ID when dropping privileges.
-T Switch to this TTY terminal when dropping privileges.
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: bind-hooks and exec-hooks can be
placed in the base root of the tomb.
bind-hooks
This hook file consists of a simple text file named bind-hooks containing a two
column list of paths to files or directories inside the tomb. The files and
directories will be be made directly accessible by the tomb open command inside the
current user's home directory. Tomb uses internally the "mount -o bind" command to
bind locations inside the tomb to locations found in $HOME. 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
exec-hooks
This hook file gets executed as user by tomb with the first argument determining
the step of execution (open or close) and the second being the full path to the
mountpoint. The exec-hooks file should be executable (ELF or shell script) and
present inside the Tomb. Tomb executes this hook as user and adds the name,
loopback device and dev-mapper device paths as additional arguments for the close
command.
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 /etc/sudoers:
username ALL=NOPASSWD: /usr/local/bin/tomb
To avoid that tomb execution is logged by syslog also add:
Cmnd_Alias TOMB = /usr/local/bin/tomb
Defaults!TOMB !syslog
PASSWORD INPUT
Password input is handled by the pinentry program: it can be text based or graphical and
is usually configured with a symlink. When using Tomb in X11 it is better to use a
graphical pinentry-gtk2 or pinentry-qt because it helps preventing keylogging by other X
clients. When using it from a remote ssh connection it might be necessary to force use of
pinentry-curses for instance by unsetting the DISPLAY environment var.
SWAP
On execution of certain commands Tomb will complain about swap memory on disk when present
and abort if your system has swap activated. You can disable this behaviour using the
--force. Before doing that, however, you may be interested in knowing the risks of doing
so:
• During such operations a lack of available memory could cause the swap to write
your secret key on the disk.
• 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.
If you don't need swap, execute swapoff -a. 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.
DENIABILITY
The possibility to have an encrypted volume which is invisible and cannot be detected is
called "deniability". The cryptographic layer of the device mapper in Linux (dm-crypt)
does not implement deniability. Tomb is just a wrapper on top of that and it doesn't add
cryptographic deniability. However a certain way of using tomb can facilitate a weak sort
of deniability outside of the scenario of seized devices and forensic analysis of files
and blocks on disc.
For instance to eliminate any trace of tomb usage from the shell history ZSh users can
activate the "HISTIGNORESPACE" feature and prefix all invocations of tomb with a blank
space, including two lines in ".zshrc":
export HISTIGNORESPACE=1
alias tomb=' tomb'
PASSWORD INPUT
Tomb uses the external program "pinentry" to let users type the key password into a
terminal or a graphical window. This program works in conjunction with "gpg-agent", a
daemon running in background to facilitate secret key management with gpg. It is
recommended one runs "gpg-agent" launching it from the X session initialization
("~/.xsession" or "~/.xinitrc" files) with this command:
eval $(gpg-agent --daemon --write-env-file "${HOME}/.gpg-agent-info")
In the future it may become mandatory to run gpg-agent when using tomb.
SHARE A TOMB
A tomb key can be encrypted with more than one recipient. Therefore, a tomb can be shared
between different users. The recipients are given using the -r (or/and -R) option and if
multiple each GPG key ID must be separated by a comma (,). Sharing a tomb is a very
sensitive action and the user needs to trust that all the GPG public keys used are kept
safe. If one of them its stolen or lost, it will be always possible to use it to access
the tomb key unless all its copies are destroyed. The -r option can be used in the tomb
commands: open, forge setkey, passwd, bury, exhume and resize.
SPHINX (PAKE)
Using the package libsphinx ⟨https://github.com/stef/libsphinx⟩ and its python
client/daemon implementation pwdsphinx ⟨https://github.com/stef/pwdsphinx⟩ is possible to
store and retrieve safely the password that locks the tomb. Using this feature will make
it impossible to retrieve the password without the oracle sphinx server running and
reachable. Each key entry needs a username and a domain specified on creation and a
password that locks it.
SPHINX makes it impossible to maliciously retrieve the password locking the tomb key
without an attacker accessing both the server, the sphinx password and the tomb key file.
EXAMPLES
• Create a 128MB large "secret" tomb and its keys, then open it:
tomb dig -s 128 secret.tomb
tomb forge secret.tomb.key
tomb lock secret.tomb -k secret.tomb.key
tomb open secret.tomb -k secret.tomb.key
• Open a Tomb using the key from a remote SSH shell, without saving any local copy of
it:
ssh user@my.shell.net 'cat .secrets/tomb.key' | tomb open secret.tomb -k -
• Open a Tomb on a remote server passing the unencrypted local key on stdin via SSH,
without saving any remote copy of it:
gpg -d .secrets/tomb.key | ssh server tomb open secret.tomb -k cleartext --unsafe
• 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:
tomb open GPG.tomb -k GPG.tomb.key
echo ".gnupg .gnupg" > /media/GPG.tomb/bind-hooks
mv ~/.gnupg /media/GPG.tomb/.gnupg && mkdir ~/.gnupg
tomb close GPG && tomb open GPG.tomb -k GPG.tomb.key
• Script a tomb to launch the Firefox browser every time is opened, keeping all its
profile data inside it:
tomb open FOX.tomb -k FOX.tomb.key
cat <<EOF > /media/FOX.tomb/exec-hooks
#!/bin/sh
if [ "$1" = "open" ]; then
firefox -no-remote -profile "$2"/firefox-pro &
fi
EOF
chmod +x /media/FOX.tomb/exec-hooks
mkdir /media/FOX.tomb/firefox-pro
• Script a tomb to archive Pictures using Shotwell, launching it on open:
tomb open Pictures.tomb -k Pictures.tomb.key
cat <<EOF > /media/Pictures.tomb/bind-hooks
Pictures Pictures
EOF
cat <<EOF > /media/Pictures.tomb/exec-hooks
#!/bin/sh
if [ "$1" = "open" ]; then
which shotwell > /dev/null
if [ "$?" = "0" ]; then
shotwell -d "$2"/Pictures/.shotwell &
fi
fi
EOF
chmod +x /media/Pictures.tomb/exec-hooks
BUGS
Please report bugs on the Github issue tracker at ⟨https://github.com/dyne/Tomb/issues⟩
One can also try to get in touch with developers via the #dyne chat channel on
https://irc.dyne.org.
COPYING
This manual is Copyright (c) 2011-2021 by Denis Roio <jaromil@dyne.org>
This manual includes contributions by Boyska and Hellekin O. Wolf.
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.
AVAILABILITY
The most recent version of Tomb sourcecode and up to date documentation is available for
download from its website on https://tomb.dyne.org.
SEE ALSO
cryptsetup(8)
pinentry(1)
gpg-agent(1)
GnuPG website: https://www.gnupg.org
DM-Crypt website: https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
LUKS website: https://gitlab.com/cryptsetup/cryptsetup/wikis/home