2014-04-15 10:56:00 +00:00
..... ..
.H8888888h. ~-. . uW8"
888888888888x `> u. .. . : ` t888
X~ `?888888hx~ ...ue888b .888: x888 x888. 8888 .
' x8.^"*88*" 888R Y888r ~`8888~'888X`?888f` 9888.z88N
`-:- X8888x 888R I888> X888 888X '888> 9888 888E
488888> 888R I888> X888 888X '888> 9888 888E
.. `"88* 888R I888> X888 888X '888> 9888 888E
x88888nX" . u8888cJ888 X888 888X '888> 9888 888E
!"*8888888n.. : "*888*P" "*88%""*88" '888!` .8888 888"
' "*88888888* 'Y" `~ " ` "` `%888*%"
^"***"` "`
2010-08-22 13:04:19 +00:00
2014-08-29 21:23:08 +00:00
*A minimalistic commandline tool to manage encrypted volumes* aka **The Crypto Undertaker**
2010-08-23 19:28:09 +00:00
2015-12-22 17:22:48 +00:00
[![software by Dyne.org ](https://www.dyne.org/wp-content/uploads/2015/12/software_by_dyne.png )](http://www.dyne.org)
2014-11-16 14:18:11 +00:00
2014-11-16 12:55:51 +00:00
Updates on website: https://www.dyne.org/software/tomb
2014-04-15 10:56:00 +00:00
2014-08-29 21:23:08 +00:00
Get the stable .tar.gz signed release for production use!
2014-11-26 19:28:06 +00:00
2014-08-29 21:23:08 +00:00
Download it from https://files.dyne.org/tomb
2015-12-22 17:22:48 +00:00
![tomb's logo ](https://github.com/dyne/Tomb/blob/master/extras/images/monmort.png )
2016-06-12 11:10:47 +00:00
[![Build Status ](https://travis-ci.org/dyne/Tomb.svg?branch=master )](https://travis-ci.org/dyne/Tomb)
2016-12-19 08:40:10 +00:00
# Breaking news (literally)
Those who upgraded the ZSh interpreter to version 5.3 (released very recently) will have problems opening tombs. [This problem is known ](https://github.com/dyne/Tomb/issues/232 ) and will be fixed soon. There is no data loss for your tombs, of course. Meanwhile we advise to downgrade ZSh to 5.2.
2016-06-12 11:10:47 +00:00
2014-09-23 09:57:15 +00:00
# What is Tomb, the crypto undertaker?
2010-08-22 13:04:19 +00:00
2010-08-23 13:10:57 +00:00
Tomb aims to be a free and open source system for easy encryption and
backup of personal files, written in code that is easy to review and
2013-05-25 14:29:19 +00:00
links shared GNU/Linux components.
2010-08-22 13:04:19 +00:00
2014-09-23 09:57:15 +00:00
At present, Tomb consists of a simple shell script (Zsh) using
2010-08-25 18:18:15 +00:00
standard filesystem tools (GNU) and the cryptographic API of the Linux
2013-05-25 14:29:19 +00:00
kernel (cryptsetup and LUKS). Tomb can also produce machine parsable
output to facilitate its use inside graphical applications.
2010-08-23 13:10:57 +00:00
2014-09-23 09:57:15 +00:00
# How does it work?
2014-04-15 10:56:00 +00:00
2014-11-16 14:18:11 +00:00
To create a Tomb, do:
```
$ tomb dig -s 100 secret.tomb
$ tomb forge secret.tomb.key
$ tomb lock secret.tomb -k secret.tomb.key
```
To open it, do
```
$ tomb open secret.tomb -k secret.tomb.key
```
and after you are done
```
$ tomb close
```
or if you are in a hurry
```
$ tomb slam all
```
2014-04-15 10:56:00 +00:00
For the instructions on how to get started using Tomb, see [INSTALL ](INSTALL.md ).
2010-08-23 13:10:57 +00:00
2014-11-16 14:18:11 +00:00
```
Syntax: tomb [options] command [arguments]
Commands:
// Creation:
dig create a new empty TOMB file of size -s in MB
forge create a new KEY file and set its password
lock installs a lock on a TOMB to use it with KEY
// Operations on tombs:
2015-12-02 15:34:22 +00:00
open open an existing TOMB (-k specify KEY file)
2014-11-16 14:18:11 +00:00
index update the search indexes of tombs
search looks for filenames matching text patterns
list list of open TOMBs and information on them
close close a specific TOMB (or 'all')
slam slam a TOMB killing all programs using it
resize resize a TOMB to a new size -s (can only grow)
// Operations on keys:
passwd change the password of a KEY (needs old pass)
setkey change the KEY locking a TOMB (needs old key and pass)
// Backup on paper:
engrave makes a QR code of a KEY to be saved on paper
// Steganography:
bury hide a KEY inside a JPEG image (for use with -k)
exhume extract a KEY from a JPEG image (prints to stout)
Options:
-s size of the tomb file when creating/resizing one (in MB)
-k path to the key to be used ('-k -' to read from stdin)
-n don't process the hooks found in tomb
-o mount options used to open (default: rw,noatime,nodev)
-f force operation (i.e. even if swap is active)
--kdf generate passwords armored against dictionary attacks
-h print this help
-v print version, license and list of available ciphers
-q run quietly without printing informations
-D print debugging information at runtime
```
2014-11-16 15:16:25 +00:00
# What is this for, exactly?
2014-11-16 14:18:11 +00:00
2014-09-23 09:57:15 +00:00
This tool can be used to dig .tomb files (LUKS volumes), forge keys
2013-05-25 14:29:19 +00:00
protected by a password (GnuPG symmetric encryption) and use the keys
to lock the tombs. Tombs are like single files whose contents are
2014-09-23 09:57:15 +00:00
inaccessible in the absence of the key they were locked with and its
2013-05-25 14:29:19 +00:00
password.
2014-09-23 09:57:15 +00:00
Once open, the tombs are just like normal folders and can contain
2013-05-25 14:29:19 +00:00
different files, plus they offer advanced functionalities like bind
and execution hooks and fast search, or they can be slammed close even
2014-09-23 09:57:15 +00:00
if busy. Keys can be stored on separate media like USB sticks, NFC, or
2013-05-25 14:29:19 +00:00
bluetooth devices to make the transport of data safer: one always
needs both the tomb and the key, plus its password, to access it.
2014-11-16 15:16:25 +00:00
The tomb script takes care of several details to improve user's
behaviour and the security of tombs in everyday usage: secures the
typing of passwords from keyloggers, facilitates hiding keys inside
images, indexes and search a tomb's contents, lists open tombs and
selectively closes them, warns the user about free space and last time
usage, etc.
2010-08-23 13:10:57 +00:00
2014-04-15 10:56:00 +00:00
# How secure is this?
2013-05-28 10:53:26 +00:00
2014-09-23 09:57:15 +00:00
Death is the only sure thing in life. That said, Tomb is a pretty
2014-11-16 15:16:25 +00:00
secure tool especially because it is kept minimal, its source is
2015-07-06 11:03:32 +00:00
always open to review (even when installed) and its code is easy to
read with a bit of shell script knowledge.
2013-05-28 10:53:26 +00:00
All encryption tools being used in Tomb are included as default in
many GNU/Linux operating systems and therefore are regularly peer
reviewed: we don't add anything else to them really, just a layer of
usability.
2014-12-05 03:20:42 +00:00
The file [KNOWN_BUGS.md ](KNOWN_BUGS.md ) contains some notes on known
2014-11-26 19:28:06 +00:00
vulnerabilities and threat model analysis.
2015-07-06 11:03:32 +00:00
In absence or malfunction of the Tomb script it is always possible to
access the contents of a Tomb only using a dm-crypt enabled Linux
kernel, cryptsetup, GnuPG and any shell interpreter issuing the
following commands as root:
2014-11-16 15:16:25 +00:00
```
2015-01-30 01:00:07 +00:00
lo=$(losetup -f)
losetup -f secret.tomb
pass="$(gpg -d secret.key)"
echo -n -e "$pass" | cryptsetup --key-file - luksOpen $lo secret
mount /dev/mapper/secret /mnt
2014-11-16 15:16:25 +00:00
```
2015-07-06 11:03:32 +00:00
One can change the last argument `/mnt` to where the Tomb has to be
mounted and made accessible. To close the tomb then use:
```
umount /mnt
cryptsetup luksClose /dev/mapper/secret
```
2013-05-28 10:53:26 +00:00
2014-04-15 10:56:00 +00:00
# Stage of development
2010-08-23 13:10:57 +00:00
2014-11-16 15:16:25 +00:00
Tomb is an evolution of the 'mknest' tool developed for the
[dyne:bolic ](http://www.dynebolic.org ) 100% Free GNU/Linux
distribution in 2001: its 'nesting' mechanism allowed the liveCD users
to encrypt and make persistent home directories. Since then the same
shell routines kept being maintained and used for dyne:bolic until
2007, when they were ported to work on more GNU/Linux distributions.
2010-08-23 13:10:57 +00:00
2014-09-23 09:57:15 +00:00
As of today, Tomb is a very stable tool also used in mission critical
situations by a number of activists in dangerous zones. It has been
2013-05-25 14:29:19 +00:00
reviewed by forensics analysts and it can be considered to be safe for
2014-11-16 14:18:11 +00:00
military grade use where the integrity of information stored depends
on the user's behaviour and the strength of a standard AES-256 (XTS
plain) encryption algorithm.
2010-08-23 13:10:57 +00:00
2014-11-16 14:18:11 +00:00
# Use stable releases in production!
2014-08-29 21:23:08 +00:00
Anyone planning to use Tomb to store and access secrets should not use
the latest development version in Git, but use instead the .tar.gz
release on https://files.dyne.org/tomb . The stable version will
2014-09-23 09:57:15 +00:00
always ensure backward compatibility with older tombs: we make sure it
2014-08-29 21:23:08 +00:00
creates sane tombs and keys by running various tests before releasing
it. The development version in Git might introduce sudden bugs and is
2014-09-23 09:57:15 +00:00
not guaranteed to produce backward- or forward-compatible tombs and keys.
2014-11-16 12:55:51 +00:00
The development version in Git should be used to report bugs, test new
features and develop patches.
2014-08-29 21:23:08 +00:00
So be warned: do not use the latest Git version in production
environments, but use a stable release versioned and packed as
tarball on https://files.dyne.org/tomb
2014-04-15 10:56:00 +00:00
# How can you help
2010-08-23 13:10:57 +00:00
2014-11-26 19:28:06 +00:00
Donations are very welcome, please go to https://www.dyne.org/donate
2013-06-12 12:28:40 +00:00
2014-06-09 10:42:38 +00:00
Translations are also needed: they can be contributed via this website
2015-07-25 14:15:29 +00:00
https://poeditor.com/join/project/b276xMGAmB
2014-06-09 10:42:38 +00:00
or simply sending the .po file. Start from `extras/po/tomb.pot` .
2014-09-23 09:57:15 +00:00
The code is pretty short and readable: start looking around and the
materials found in `doc/` which are good pointers at security measures
2010-08-23 13:10:57 +00:00
to be further implemented.
2013-06-12 12:28:40 +00:00
For the bleeding edge visit https://github.com/dyne/Tomb
2013-05-25 14:29:19 +00:00
2014-11-26 19:28:06 +00:00
If you plan to commit code into Tomb, please keep in mind this is a
minimalist tool and its code should be readable. Guidelines on the
2014-12-05 03:20:42 +00:00
coding style are illustrated in [doc/HACKING.txt ](doc/HACKING.txt ).
2014-11-26 19:28:06 +00:00
2014-08-29 21:23:08 +00:00
Tomb's developers can be contacted using the issues on GitHub or over
2015-07-23 16:39:10 +00:00
IRC on https://irc.dyne.org channel ** #dyne ** (or direct port 9999 SSL)
2011-01-30 22:25:01 +00:00
2014-11-26 19:28:06 +00:00
# Licensing
2014-11-16 14:18:11 +00:00
2015-12-30 16:50:36 +00:00
Tomb is Copyright (C) 2007-2016 by the Dyne.org Foundation
2014-11-16 14:18:11 +00:00
2014-11-26 19:28:06 +00:00
More information on all the developers involved is found in the
[AUTHORS ](AUTHORS.md ) file.
2014-11-16 14:18:11 +00:00
2014-11-26 19:28:06 +00:00
This source code is free software; you can redistribute it and/or
modify it under the terms of the GNU Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
2014-11-16 14:18:11 +00:00
2014-11-26 19:28:06 +00:00
This source code is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please refer
to the GNU Public License for more details.
2014-11-16 14:18:11 +00:00
2014-11-26 19:28:06 +00:00
You should have received a copy of the GNU Public License along with
this source code; if not, write to: Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.