---
obj: application
website: https://dyne.org/software/tomb
repo: https://github.com/dyne/Tomb
---

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

## Usage

**Commands**:
- `dig -s SIZE FILE` : 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 be locked using a key. Tombs are digged using random data (`/dev/urandom`).
- `forge [OPTIONS] KEY` : 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; The `-g` option switches on the use of a [GPG](../../cryptography/GPG.md) key instead of a password (asymmetric encryption), then the `-r` option indicates the recipient key; more recipient [GPG](../../cryptography/GPG.md) 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 -k KEY FILE` : 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](../../cryptography/GPG.md) recipients the `-g` flag should be used followed by `-r` and the recipient's secret [GPG](../../cryptography/GPG.md) 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 and [Linux](../../linux/Linux.md) documentation. The `--filesystem` option can be used to specify [`btrfs`](../../linux/filesystems/Btrfs.md) as an alternative filesystem used to format the tomb, in place of the default [`ext4`](../../linux/filesystems/Ext4.md). This operation requires root privileges to loopback mount, format the tomb (using [LUKS](../../linux/filesystems/LUKS.md) and [Ext4](../../linux/filesystems/Ext4.md)), then set the key in its first [LUKS](../../linux/filesystems/LUKS.md) slot.
- `open -k KEY FILE MOUNT` : 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](../../linux/Mount.md) options (default: `rw,noatime,nodev`). The `-g` option is needed when using [GPG](../../cryptography/GPG.md) 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 utility is used internally to enumerate processes running in one or all tombs.
- `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](../../cryptography/GPG.md) 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](../../cryptography/GPG.md) 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 OLDKEY FILE` : 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](../../cryptography/GPG.md) 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](../../cryptography/GPG.md) 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 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 [QR Code](../../tools/QR%20Code.md) of the tomb key, still protected by its password: a [PNG](../../files/media/image/PNG.md) 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 [QR Code](../../tools/QR%20Code.md) reader on a smartphone: save it into a file and then use that file as a key (`-k`).
- `bury IMAGE` : 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](../../cryptography/GPG.md) asymmetric encryption.
- `exhume IMAGE` : 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 FILE` : 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 FILE` : 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

| Option                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-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.                                                                                                                                                                                                                                                                                                                                                                                                           |
| `-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](../../linux/Mount.md) options to be used when opening a tomb instead of the default `rw,noatime,nodev`, i.e. to [mount](../../linux/Mount.md) 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](../../linux/filesystems/LUKS.md) 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](../../cryptography/GPG.md) 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](../../cryptography/GPG.md) key ID, comma separated. All [GPG](../../cryptography/GPG.md) keys must be trusted keys in [GPG](../../cryptography/GPG.md).                                                                                                                                                                                                                                |
| `--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.                                                                                                                                                    |

## 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 is a simple text file `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:**
his  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](Shell.md) 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.
