Tomb/doc/tomb.1

.TH tomb 1 "Jun 25, 2023" "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 \fIkey\fR. It takes a mandatory \fI-s\fR option
which is the size in megabytes (MiB). Tombs are digged using random
data gathered from a non-blocking source (/dev/urandom). For very
large tombs this may take up too much time and entropy, then it is
possible to use \fIfallocate(1)\fR being aware it does not pre-fill
with random data, decreasing the tomb's security.

.B
.IP "forge"
Creates a new \fIkey\fR and prompts the user for a \fIpassword\fR 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 \fI--use-random\fR flag can be used. The
\fI-g\fR option switches on the use of a GPG key instead of a password
(asymmetric encryption), then the \fI-r\fR 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 \fI-o\fR
option, for a list of supported ciphers use \fI-v\fR. For additional protection
against dictionary attacks on keys, the \fI--kdf\fR option can be used when
forging a key, making sure that the binaries in \fIextras/kdf\fR were compiled
and installed on the system.

.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 opened in possession of the key and
knowing its password. As in any other command requiring a key, the
option \fI-k\fR should be used to specify a key file; in case of
encryption to GPG recipients the \fI-g\fR flag should be used followed
by \fI-r\fR and the recipient's secret GPG key id.  The \fI-o\fR
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 \fI--filesystem\fR option can be used to
specify 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 mkfs),
then set the key in its first LUKS slot. 

.RS
.nf
Supported filesystems for \fI--filesystem\fR:
"ext3"	using operating system defaults
"ext4"	using operating system defaults
"btrfs"	for tombs >= 47MB using operating system defaults
"btrfsmixedmode"	for tombs >=18MB btrfs mixed mode (see mkfs.btrfs(8))
"ext3maxinodes"	ext3 with a maximum of inodes (for many small files)
"ext4maxinodes"	ext4 with a maximum of inodes (for many small files)
.RE

.B
.IP "open"
Opens an existing \fItomb file\fR (first argument) using a key
(\fI-k\fR) which can also be hidden inside a \fIjpeg image\fR (see
\fIbury\fR/\fIexhume\fR) or a long text file
(see\fIcloak\fR/\fIuncloak\fR). 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 (if
not available it uses /run/media/$USER).  The option \fI-o\fR can be
used to pass mount(8) options (default: rw,noatime,nodev). The
\fI-g\fR option is needed when using GPG encryption to recipients.

.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 it's not found. If the option
\fI--get-mountpoint\fR is used then print a simple list of currently
open tomb mountpoint paths.

.B
.IP "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 \fIslam\fR command. The lsof(8) utility is used
internally to enumerate processes running in one or all tombs.

.B
.IP "index"
Creates or updates the search indexes of all tombs currently open:
enables use of the \fIsearch\fR 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 \fI.noindex\fR file in it.

.B
.IP "search"
Takes any string as argument and searches for them through all tombs
currently open and previously indexed using the \fIindex\fR 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.

.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 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 \fIlsof\fR else it falls back to \fIclose\fR.


.B
.IP "passwd"
Changes the password protecting a key file specified using
\fI-k\fR. With keys encrypted for GPG recipients use \fI-g\fR followed
by \fI-r\fR 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.

.B
.IP "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 \fI-k\fR option,
the first argument should be the old key and the second and last
argument the tomb file. Use the \fI-g\fR option to unlock the tomb
with a GPG key, the \fI-r\fR to indicate the recipient or a comma
separated list for more than one recipient.

.B
.IP "resize"
Increase the size of a tomb file to the amount specified by the
\fI-s\fR option, which is the new size in megabytes (MiB). Full access
to the tomb using a key (\fI-k\fR) 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.

.B
.IP "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 \fI.qr.png\fR) 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 (\fI-k\fR).

.B
.IP "bury"
Hides a tomb key (\fI-k\fR) inside a \fIjpeg image\fR (first 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. Use the \fI-g\fR flag and
\fI-r\fR option followed by recipient id to use GPG asymmetric
encryption.

.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
(\fI-k\fR) and a \fIjpeg image\fR 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.

.B
.IP "cloak"
Hides a tomb key (\fI-k\fR) inside a \fIlong plain-text file\fR (first
argument) using \fIsteganography\fR: 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 \fIcloakify\fR and
consequently \fIpython2\fR. This function does not support asymmetric
encryption using the \fI-g\fR flag.

.B
.IP "uncloak"
This command recovers from long plain-text files the keys that were
previously hidden into them using \fIcloak\fR.  Cloak requires a key
filename (\fI-k\fR) and a \fIplain-text\fR 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.

.SH OPTIONS
.B
.B
.IP "-k \fI<keyfile>\fR"
For all operations requiring a key, this option specifies the location
of the key file to use. Arguments can also be \fIjpeg image\fR files
where keys have been hidden using the \fIbury\fR or \fIcloak\fR
commands, or text files retrieved from \fIengraved\fR QR codes. If the
\fIkeyfile\fR argument is "-" (dash), Tomb will read the key from
stdin (blocking).
.B
.IP "-n"
Skip processing of exec-hooks and bind-hooks if found inside the tomb.
See the \fIHOOKS\fR section in this manual for more information.
.B
.IP "-p"
When opening a tomb, preserves the ownership of all files and
directories contained in it. Normally the \fIopen\fR 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.
.B
.IP "-o"
Manually specify mount options to be used when opening a tomb instead
of the default \fIrw,noatime,nodev\fR, 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 \fIforge\fR
operations (default \fIAES256\fR) or the LUKS encryption method during
\fIlock\fR operations (default \fIaes-xts-plain64\fR).
.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 "-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 "-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 \fI-r\fR when the command needs to specify recipient(s).
.B
.IP "-r \fI<gpg_id>[,<gpg_id2>]\fR"
Provide a new set of recipient(s) to encrypt a tomb key. \fIgpg_ids\fR
can be one or more GPG key ID, comma separated. All GPG keys must be
trusted keys in GPG.
.B
.IP "--kdf \fI<itertime>\fR"
Activate the KDF feature against dictionary attacks when creating a key: forces
a delay of \fI<itertime>\fR times every time this key is used.  The actual time
to wait depends on the CPU speed (default) or the RAM size (argon2) 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.
.B
.IP "--kdftype \fIargon2 | pbkdf2\fR"
Adopt the \fIargon2\fR algorithm for KDF, stressing the RAM capacity rather
than the CPU speed of the computer decrypting the tomb. Requires the
\fIargon2\fR binary by P-H-C to be installed, as packaged by most distros.
Default is \fIpbkdf2\fR.
.B
.IP "--kdfmem \fI<memory>\fR"
In case of \fIargon2\fR KDF algorithm, this value specifies the size of RAM
used: it consists of a number which is the elevated power of two in kilobytes.
Default is 18 which is 250 MiB (2^18 = 262,144 kilobytes).
.B
.IP "--sudo \fI<executable>\fR"
Select a different tool than sudo for privilege escalation.
Alternatives supported so far are: pkexec, doas, sup, sud. For any
alternative to work the executable must be included in the current
PATH.
.B
.IP "--sphx-user \fI<username>\fR"
Activate the SPHINX feature for password-authenticated key agreement.
This option indicates the \fI<username>\fR used to retrieve the
password from a sphinx oracle key reachable via TCP/IP.
.B
.IP "--sphx-host \fI<domain>\fR"
Activate the SPHINX feature for password-authenticated key agreement.
This option indicates the \fI<domain>\fR 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

.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

.SH DEV MODE
.B
.IP "--no-color"
Suppress colors in console output (needed for string parsing by
wrappers).
.B
.IP "--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.
.B
.IP "--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.
.B
.IP "--tomb-pwd <string>"
Use string as password when needed on tomb.
.B
.IP "--tomb-old-pwd <string>"
Use string as old password when needed in tomb commands requiring
multiple keys, like \fIpasswd\fR or \fIsetkey\fR.
.B
.IP "-U"
Switch to this user ID when dropping privileges.
.B
.IP "-G"
Switch to this group ID when dropping privileges.
.B
.IP "-T"
Switch to this TTY terminal when dropping privileges.

.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 \fIexec-hooks\fR can be placed in the
base root of the tomb.

.B
.IP "bind-hooks"
This hook file consists of a simple text file named \fIbind-hooks\fR
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 \fIopen\fR 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:
.EX
  mail          mail
  .gnupg        .gnupg
  .fmrc         .fetchmailrc
  .mozilla      .mozilla
.EE

.B
.IP "exec-hooks"
This hook file gets executed as user by tomb with the first argument
determining the step of execution (\fIopen\fR or \fIclose\fR) and the second
being the full path to the mountpoint. The \fIexec-hooks\fR 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 \fIclose\fR
command.

.SH PRIVILEGE ESCALATION

The tomb commandline tool needs to acquire super user rights to
execute most of its operations: so it uses sudo(8) or other configured
tools, 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

To avoid that tomb execution is logged by \fIsyslog\fR also add:

.EX
Cmnd_Alias TOMB = /usr/local/bin/tomb
Defaults!TOMB !syslog
.EE

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


.SH SWAP

On execution of certain commands Tomb will complain about swap memory
on disk when present 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 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":

.EX
export HISTIGNORESPACE=1
alias tomb=' tomb'
.EE

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

.EX
eval $(gpg-agent --daemon --write-env-file "${HOME}/.gpg-agent-info")
.EE

In the future it may become mandatory to run gpg-agent when using tomb.

.SH 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 \fI-r\fR (or/and \fI-R\fR) option and if multiple each GPG
key ID must be separated by a comma (\fI,\fR). 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 \fI-r\fR option can be used in the tomb
commands: \fIopen\fR, \fIforge\fR \fIsetkey\fR, \fIpasswd\fR,
\fIbury\fR, \fIexhume\fR and \fIresize\fR.

.SH SPHINX (PAKE)

Using the package libsphinx
.UR https://github.com/stef/libsphinx
.UE
and its python client/daemon implementation pwdsphinx 
.UR https://github.com/stef/pwdsphinx
.UE
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.

.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 -k secret.tomb.key

	tomb open secret.tomb -k secret.tomb.key
.EE

.IP \(bu
Open a Tomb using the key from a remote SSH shell, without saving any
local copy of it:

.EX
	ssh user@my.shell.net 'cat .secrets/tomb.key' | tomb open secret.tomb -k -
.EE

.IP \(bu
Open a Tomb on a remote server passing the unencrypted local key on stdin via SSH,
without saving any remote copy of it:

.EX
	gpg -d .secrets/tomb.key | ssh server tomb open secret.tomb -k cleartext --unsafe
.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 -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
.EE

.IP \(bu
Script a tomb to launch the Firefox browser every time is opened,
keeping all its profile data inside it:

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

.IP \(bu
Script a tomb to archive Pictures using Shotwell, launching it on open:

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

.SH BUGS
Please report bugs on the Github issue tracker at
.UR https://github.com/dyne/Tomb/issues
.UE

One can also try to get in touch with developers via the #dyne chat
channel on \fIhttps://irc.dyne.org\fR.

.SH COPYING

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

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.

.SH AVAILABILITY

The most recent version of Tomb sourcecode and up to date
documentation is available for download from its website on
\fIhttps://tomb.dyne.org\fR.

.SH SEE ALSO

.B
.IP cryptsetup(8)
.B
.IP pinentry(1)
.B
.IP 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