tomb(1)

📦
version 2.13 · 5 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

tomb(1) — straight outta the General Commands Manual — Tomb, aka the Crypto Undertaker. 💀💖

🦋 SYNOPSIS 🦋

tomb [options] command [arguments]

🌸 DESCRIPTION 🌸

Okay so picture this: Tomb is the app that handles making and opening your encrypted storage files — like the whole creation-and-access situation. You can run it straight from the commandline, and it can also integrate with your graphical desktop. 🖥️✨

Tomb generates encrypted storage files, and those get opened and closed using their associated keys. Those keys? Also protected with a password that you pick. 🔐 To create, open, and close tombs, you're gonna need super user rights to execute the tomb commandline utility. No cap.

A tomb is basically a locked folder that can be safely transported and hidden in a filesystem. It encourages users to keep their keys separate from their tombs — like, keeping a tomb file on your computer harddisk and its key file on a USB stick. That's the whole energy. 🫶

💫 COMMANDS 💫

okay bestie, here's the whole toolkit — every single thing tomb can do for you, explained with love 💖

  • dig — bestie this one makes you a tomb file. It generates a file that works as a tomb and takes up as much space as the initial size you want, and then that unlocked .tomb file can be locked with a key later. It requires the -s option, which is the size in megabytes (MiB). Tombs get dug using random data pulled from a non-blocking source (/dev/urandom). Heads up though: for very large tombs this can take way too much time and entropy, so you can use fallocate(1) instead — but be aware it does not pre-fill with random data, which decreases the tomb's security. ⚠️
  • forge — makes a brand-new key and asks you for a password to protect its usage with symmetric encryption. This uses random data from a non-blocking source (/dev/urandom) and only sometimes takes a while; if you wanna switch to a blocking source, use the --use-random flag. The -g option switches on using a GPG key instead of a password (asymmetric encryption), and then -r says which recipient key — you can list more recipient GPG ids (comma separated). Default cipher for protecting the key is AES256, but you can set a custom one with -o, and for a list of supported ciphers use -v. For extra protection against dictionary attacks on keys, use the --kdf option while forging. Two KDFs are currently supported: argon2 and pbkdf2. pbkdf2 is available from extras/kdf and needs to be compiled and installed on your system. argon2 is generally available from distribution repositories. ✨
  • lock — initializes and locks an empty tomb (made with dig) using a key (made with forge), getting it ready for usage. After this, the tomb can only be opened if you've got the key and know its password. Like every other command that needs a key, use -k to specify a key file; if you're encrypting to GPG recipients, use the -g flag followed by -r and the recipient's secret GPG key id. The -o option lets you specify the cipher specification: default is "aes-xts-plain64", and old versions of Tomb used "aes-cbc-essiv:sha256". If you're feeling exotic, also try "serpent-xts-plain64". More options live in cryptsetup(8) and the Linux documentation. The --filesystem option lets you specify an alternative filesystem to format the tomb with, instead of the default "ext4". This whole operation needs root privileges to loopback mount, format the tomb (using LUKS and mkfs), then set the key in its first LUKS slot. 👑

Supported filesystems for --filesystem:

  • 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)
  • 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 (see cloak/uncloak). If you give a second argument, that's the mountpoint where the tomb should be made accessible — otherwise the tomb is mounted in a directory inside /media (or if that's not available, it uses /run/media/$USER). The -o option passes mount(8) options (default: rw,noatime,nodev). The -g option is needed when you're using GPG encryption to recipients. 🦋
  • list — lists all the tombs that are currently open, including info about when they were opened and the hooks they mounted. If the first argument is present, it shows only the tomb named that way, or returns an error if it's not found. If you use the --get-mountpoint option, it prints a simple list of currently open tomb mountpoint paths. 🌸
  • ps — lists all the processes running inside the tombs that are open, printing their PIDs and owners. Super useful to get an overview of programs keeping the tombs busy — the ones that would eventually get killed by the slam command. It uses the lsof(8) utility internally to enumerate processes running in one or all tombs. 🔍
  • index — creates or updates the search indexes of all tombs currently open, which enables the search command using simple word patterns on file names. Indexes are created using plocate's updatedb(8) and recoll(1) if they're found on the system. Indexes let you search very fast for filenames and contents inside a tomb; they're stored inside it and aren't accessible if the Tomb is closed. To avoid indexing a specific tomb, just touch a .noindex file in it. Useful tools to have: poppler-utils, aspell, xdg-utils, plocate. 📇
  • search — takes any string as argument and searches for it through all tombs currently open and previously indexed using the index command. The search matches filenames if plocate is installed, and then also file contents if recoll is installed — all results are listed on the console. You can also run recoll's GUI using recoll -c /media/tomb. 🔎
  • close — closes a currently open tomb. If more tombs are open, use the first argument to specify the name of the tomb to close, 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 close does, but it does not 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 it helps users face surprise situations. It requires lsof, otherwise it falls back to close. 💀
  • passwd — changes the password protecting a key file specified with -k. For keys encrypted to GPG recipients, use -g followed by -r to indicate the new recipient key, or a comma separated list. You'll need to know the key's current password, or possess at least one of the current recipients' GPG secret keys, because the key contents get 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, swapping the old one for a new one. You need both the old and the new key files for this, and their passwords or GPG recipient(s) secret keys must be available. The new key must be specified with the -k option, the first argument should be the old key, and the second and last argument is the tomb file. Use the -g option to unlock the tomb with a GPG key, and -r to indicate the recipient or a comma separated list for more than one recipient. 🔄
  • resize — increases the size of a tomb file to the amount specified by the -s option, which is the new size in megabytes (MiB). You need full access to the tomb using a key (-k) and its password. Tombs can only grow and can never be made smaller. This command uses the cryptsetup(8) resize feature and the resize2fs command: it's way more practical than making a new tomb and moving everything into it. There's no data-loss if a failure happens during resize — just re-launch the command and the resize operation will complete. 📏
  • engrave — transforms a tomb key into an image that can be printed on paper and physically stored as a backup, like hidden in a book. It renders a QRCode of the tomb key, still protected by its password: a PNG image (extension .qr.png) gets created in the current directory and can be printed later (fits an A4 or Letter format). To recover an engraved key, 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 changes in a way that can't be noticed by the human eye and is hardly detected by data analysis. This is useful to back up tomb keys in unsuspected places; it depends on steghide being available. Use the -g flag and -r option followed by recipient id to use GPG asymmetric encryption. 🙈
  • exhume — recovers from jpeg images the keys that were previously hidden in them using bury. Exhume requires a key filename (-k) and a jpeg image file (first argument) known to contain a key. If you give the right key password, the key will be exhumed. If the password isn't known, it is very hard to verify whether a key is buried in any image or not. 🧚
  • cloak — cloaks a tomb key (-k) by disguising it as text using a cipher file (first argument), writing the result to stdout or optionally an output file (second argument). See /usr/share/doc/tomb/examples/cloak-ciphers for potential cipher files. However, it's recommended to create and use your own ciphers. This is useful to back up tomb keys in unsuspected places. 💜
  • uncloak — recovers a tomb key from a cloaked text file. Uncloak requires a text file (first argument), a cipher file (second argument) and optionally an output file (third argument). If the first two parameters are correct, the output will be a valid tomb key file restored from cloak. 🌈
  • -k <keyfile> — for literally any operation that needs a key, this is where you tell tomb which key file to use 🔑. And bestie, the keyfile can be so much more than a boring key file: it can be a jpeg image where the key is hidden away (you know, the bury or cloak commands? those ones 💅), or a text file you got back from an engraved QR code. And if you pass - (just a dash), Tomb will read the key straight from stdin — which blocks, so heads up, it'll just sit there waiting for you 🙈.
  • -n — skips processing of exec-hooks and bind-hooks if they're chillin' inside the tomb. Want the details? Peek at the HOOKS section down below, iykyk ✨.
  • -p — when you're opening a tomb, this preserves the ownership of all the files and directories inside it. Normally open reassigns the ownership of everything in the tomb to the UID and GID of whoever successfully opened it — it's a lil usability feature for when one person uses a tomb across different systems 🫶. This flag turns that behaviour off.
  • -o — lets you manually specify the mount options used when opening a tomb, instead of the default rw,noatime,nodev. Like, say you wanna mount a tomb read-only (ro) so nobody can touch its data — this is your girl 🎀. It can also be used to change the symmetric encryption algorithm for keys during forge operations (default is AES256), or the LUKS encryption method during lock operations (default is aes-xts-plain64) 👑
  • -f — the force flag 💪. Currently it overrides swap checks, and it might override even more wimpy behaviours in the future. But fr fr, make sure you know what you're doing before you force an operation.
  • -s <MBytes> — when you're digging or resizing a tomb, you must use this to specify the size of the new file being created. Units are megabytes (MiB) 📏.
  • -g — tells tomb to use asymmetric GnuPG key encryption instead of a symmetric passphrase to protect a tomb key 🗝️. You can follow this up with -r when the command needs to name recipient(s).
  • -r <gpg_id>[,<gpg_id2>] — provides a fresh set of recipient(s) to encrypt a tomb key. The gpg_ids can be one or more GPG key IDs, comma separated. And no cap: all GPG keys must be trusted keys in GPG, periodt.
  • --kdf [argon2 | pbkdf2] — turns on the KDF feature so dictionary attacks get absolutely bodied when you're creating a key 🛡️. The required argument lets you pick between argon2 or pbkdf2. Here's the tea:
    • argon2 uses a mix of RAM capacity, number of threads and iterations to reach a time cost.
    • pbkdf2 is only about calculation speed to hit that time cost. Because it has a low memory footprint and no restrictions on threads, that time cost can get kinda negated through parallelization — especially on GPUs with all their cores 😭.
    • argon2 requires the respective binary by P-H-C to be installed, as packaged by most distros. pbkdf2 is available straight from the tomb sources and is a custom implementation of the algorithm.
    • Default is pbkdf2.
  • --kdfiter <itertime> — available for both argon2 and pbkdf2. Generally this controls how often the algorithm gets run. For pbkdf2, the argument is interpreted as an interval in seconds, and the actual number of iterations needed to achieve that delay gets calculated with tomb-kdb-pbkdf2-getiter, which needs to be available (it's normally installed right alongside tomb's pbkdf2 tools) — because the actual time to wait depends on your CPU speed, obviously 💅. OWASP recommendations from 2023 suggest a minimal iteration count of 600000 for pbkdf2, which should be reached with the current default value. Default is 3 (based on the argon2 default).
  • --kdfmem <memory> — for the argon2 KDF algorithm, this specifies the size of RAM used: it's a number that's the elevated power of two in kilobytes. Default is 18, which is 250 MiB (2^18 = 262,144 kilobytes) 🧠.
  • --kdfpar <# of threads> — for the argon2 KDF algorithm, this specifies how many threads should be used. It helps remedy the effects of an increased time cost on your system, whereas setups of ASICs or GPUs don't profit 🌈. Only increase this if memory or iteration got bumped so much that key decryption takes massively longer on regular systems. Default is 1 thread (based on the argon2 default).
  • --sudo <executable> — pick a different tool than sudo for privilege escalation 👑. The alternatives supported so far are: pkexec, doas, sup, sud. For any alternative to actually work, the executable must be included in the current PATH.
  • -h — displays a help text and quits 🫶.
  • -v — displays version and quits ✨.
  • -q — runs more quietly 🤫.
  • -D — prints more information while running, for debugging purposes 🐛.

🛠️ DEV MODE 🛠️

  • --no-color — suppresses colors in console output (needed for string parsing by wrappers) 🎨.
  • --unsafe — enables using dev-mode arguments, i.e. passing passwords from commandline options 🙈. This is mostly needed for execution by wrappers and the testing suite.
  • --use-random — uses a blocking random source. Tomb uses /dev/urandom by default, since the non-blocking source of the Linux kernel doesn't degrade the quality of random 💜.
  • --tomb-pwd <string> — uses string as the password when needed on tomb 🔑.
  • --tomb-old-pwd <string> — uses string as the old password when needed in tomb commands that require 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 you can place inside the tomb that trigger actions when it gets opened and closed 🎀. There are two kinds of such files: bind-hooks and exec-hooks, and they can be placed in the base root of the tomb.

bind-hooks

This hook file is a simple text file named bind-hooks containing a two column list of paths to files or directories inside the tomb 📂. Those files and directories get made directly accessible by the tomb open command inside the current user's home directory. Tomb internally uses the mount -o bind command to bind locations inside the tomb to locations found in $HOME ✨. First column = paths relative to the tomb, second column = paths relative to $HOME contents. Like, 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, 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 a line like this to /etc/sudoers:

username ALL=NOPASSWD: /usr/local/bin/tomb

To avoid tomb execution being 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 it's usually configured with a symlink 🌸. When using Tomb in a graphical environment (X11 or Wayland), it's better to use either pinentry-gtk2 (deprecated), pinentry-gnome or pinentry-qt, because it helps prevent keylogging by other clients 🛡️. When using it from a remote ssh connection, it might be necessary to force use of pinentry-tty — for instance by unsetting the DISPLAY (X11) or WAYLAND_DISPLAY (Wayland) 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 --force. But before you do that, you might wanna know the risks, bestie:

  • 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 — and this way, some contents of files contained in the tomb could be 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 these two lines in .zshrc:

export HISTIGNORESPACE=1
alias tomb=' tomb'

🫶 SHARE A TOMB 🫶

A tomb key can be encrypted with more than one recipient, which means a tomb can be shared between different users 💞. The recipients are given using the -r (or/and -R) option, and if there are 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 is stolen or lost, it'll always be 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.

✨ EXAMPLES ✨

okay bestie, real talk: here's how you actually use this thing. every command below is copy-paste ready, no cap. 💖

  • 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 🐛

found a bug? do not gatekeep, bestie. please report bugs on the Github issue tracker at https://github.com/dyne/Tomb/issues

you can also try to get in touch with developers via the #dyne chat channel on https://irc.dyne.org. they're nice, i promise. 🫶

📜 COPYING 📜

okay legal moment but make it cute. this manual is Copyright (c) 2011-2021 by Denis Roio <jaromil@dyne.org>. it also 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. periodt. 💜

🌐 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. go get the freshest one, bestie. ✨

👀 SEE ALSO 👀

then the websites, because iykyk:

this page is tomb(1), source/version tomb, dated Jun 25, 2023. now go lock your secrets, main character. 💅✨

📦 where this page comes from