Tomb - the Crypto Undertaker
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.
- 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.
- -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
- --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 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.
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.
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.
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.
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.
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.
- 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
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.
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.
The most recent version of Tomb sourcecode and up to date
documentation is available for download from its website on
https://tomb.dyne.org.