Tomb/doc/Tomb_User_Manual.org

14 KiB

Tomb User Manual

Abstract: Tomb is a cryptographic application that helps you store private and confidential data into volumes secured by keys and passwords. It works on GNU/Linux operating systems, both for desktop and remote shell usage, presenting users with with an intuitive command-line interface. This manual will outline the basic usage of Tomb, from getting started to the everyday drill, plus tips and recommendations on advanced usage and data safety.

[TABLE-OF-CONTENTS]

This user manual is obsolete, please refer to man tomb

Why Tomb?

Privacy and freedom

The internet offers plenty of free services, on the wave of the Web2.0 fuzz and the community boom, while all private informations are hosted on servers owned by global corporations and monopolies.

It is important to keep in mind that no-one else better than you can ensure the privacy of your personal data. Server hosted services and web integrated technologies gather all data into huge information pools that are made available to established economical and cultural regimes.

This software urges you to reflect on the importance of your privacy. World is full of prevarication and political imprisonments, war rages in several places and media is mainly used for propaganda by the powers in charge. Some of us face the dangers of being tracked by oppressors opposing our self definition, independent thinking and resistance to omologation.

"The distinction between what is public and what is private is becoming more and more blurred with the increasing intrusiveness of the media and advances in electronic technology. While this distinction is always the outcome of continuous cultural negotiation, it continues to be critical, for where nothing is private, democracy becomes impossible."

(from Privacy Conference, Social Research, New School University)

Who needs Tomb

/Llewellyn/Tomb/media/commit/372a1a1cf8fcf4d96d41df0b10c789f6a5e6b7c6/doc/tomb_and_bats.png

Tomb improves the usability patterns of every-day cryptography and relies on military-grade algorithms to grant a level of secrecy for stored data that is very hard to break by most military organisations and law enforcement agencies.

Our target community are GNU/Linux users with no time to click around, sometimes using old or borrowed computers, operating in places endangered by conflict where a leak of personal data can be a threat.

For example, if one doesn't owns a laptop or simply doesn't likes to carry a computer around, Tomb functions as a secure on-line and off-line storage for data and programs. On a desktop computer, Tomb can store some files locked using a key which can be carried with you and hidden into images. Tomb can do that also on a remote shell and setup a ready environment every time its opened by mounting personal directories in place using bind hooks.

Under the Hood

Tomb provides military-grade encryption at the reach of your fingertips, fostering best practices and saving users the time to look into the details of LUKS volumes and cryptsetup. Rather than reinventing the wheel, Tomb relies only on peer-reviewed, free and open source software components: at its core is DM-Crypt1 which is part of the Linux kernel architecture.

For better clarity, Tomb is written in shell script and its code can be reviewed any time. More specifically, Tomb is written in ZSh, but can be used also from Bash.

Tomb is written in a way that promotes privilege separation: a system can let its users execute the script as root, resting assured that it will drop privileges when unneeded.

The key files in Tomb are generated using high entropy random and protected via symmetric cryptography using GnuPG. The combination of a key and its password allow to open a tomb: the key contents are used to encrypt LUKS volumes mounted in loopback. The password is asked using Pinentry programs to protect from common software keyloggers and measures are taken to avoid leaving traces on any permanent storage.

Yet another tool?

∈dex{dyne:bolic}

Tomb is an evolution of the Nesting tool developed in 2001 for the Dyne:bolic GNU/Linux distribution: a nomadic system to encrypt the Home directory of users and have it ready for use on different machines. At that time, Tomb was the first secure implementation of what nowadays we call persistent storage in live operating systems.

/Llewellyn/Tomb/media/commit/372a1a1cf8fcf4d96d41df0b10c789f6a5e6b7c6/doc/foster_privacy.png

Later on we've felt the urgency to publishing this mechanism for other operating systems than dyne:bolic since the current situation in personal desktop encryption is far from optimal. Let's have a look.

∈dex{truecrypt} TrueCrypt makes use of statically linked libraries so that its code is hard to audit, plus is not considered free by free operating system distributors because of liability reasons, see Debian, Ubuntu, Suse, Gentoo and Fedora. For these and other reasons - presumably very sad ones for its users - Truecrypt has also been discontinued.

∈dex{cryptkeeper} Cryptkeeper is the best alternative to Tomb out there and its main advantage consists in not needing root access on the machine it's being used. But Cryptkeeper still has drawbacks: it uses EncFS which implements weaker encryption than dm-crypt and it doesn't promotes the separated storage of keys.

At last, the Encrypted home mechanisms on operating systems as Debian and Ubuntu adopt encryption algorithms as strong as Tomb does, but they need to be configured when the machine is installed, they cannot be easily transported and again they don't promote separated storage of keys.

With Tomb we try to overcome all these limitations providing strong encryption, encouraging users to separate keys from data and letting them transport tombs around easily. Also to facilitate auditing and customization we intend to:

  • write code that is short, readable and well documented
  • use commonly available shared components whenever possible
  • facilitate integration into desktop and graphical interfaces
  • keep the development process open and distributed using Git
  • distribute Tomb under the GNU General Public License v3

If you believe this is a worthy effort, you are welcome to support it.

TODO Getting Started

Build

Tomb at its core consists of a single Z-Shell script which has to be run as root, plus a few common dependencies that must be present on the system:

Provided the programs above are installed and root access is available on the system, the impatient user can just skip the rest of this section, download the bare Tomb script and use it. The nitpickers out there are right to wonder about running a script as root, so please be welcome to review Tomb's code. Those running on Dyne:bolic GNU/Linux can simply skip this step since our operating system already contains a fully featured version of Tomb.

In addition to the core script there are a number of optional packages that, if present on the system, will be used by Tomb to enhance the user experience, add features and improve security.

To start a full build make sure you know some command-line basics, then download the full stable source distribution of Tomb, unpack it and read on.

tar xvfz Tomb-1.3.tar.gz
cd Tomb

Be welcome to the making of your tomb.

Security extras

To make the steganography feature available, that is the possibility to hide keys inside images, one needs to install the steghide software on your system.

To insure secure deletion of all Tomb traces temporary written in memory or on storage by Tomb, one should install wipe.

To enable the anti-bruteforce feature, KDF libs should be installed and they often require a recent version of GLib-22

Usability extras

To have a progress bar that informs about the status of tomb creation steps, one should install dcfldd which is an enhanced version of the simple dd UNIX tool.

If Tomb is used locally on a graphical desktop, one might prefer to use a graphical dialog to input the password, then install pinentry-gtk or pinentry-qt.

To compile the gtk-tray component that shows the open tomb in your desktop tray, make sure the following packages are installed (this list matches package names for Debian/Ubuntu distributions:

build-essential autoconf libtool gtk2.0-dev libnotify-dev zsh pinentry-curses pinentry-gtk2 

Binary builds

Once all the extra dependencies are in place on your system, to build the gtk-tray or the KDF components, one should run the usual commands:

./configure
make

This will autodetect the capabilities of the system and build binary helper applications needed for those two extra functions. Any other feature in Tomb does not require compiling anything.

Installation

After running the configure-make combo to compile binaries it is possible to simply use make install to copy several files in place, including the main tomb script, image resources for the gtk pinentry and manuals.

Assuming the prefix is /usr/local paths for installation are:

  • /usr/local/bin/tomb
  • /usr/local/share/tomb

Multi-user systems

When installed on systems used by multiple users, Tomb can be made available to all of them even without granting root access. Simply add this line to /etc/sudoers (using the visudo command as root) for each user you like to enable to build and use tombs:

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

Tomb is built with this possibility in mind and its code is reviewed to make this setup safe, so that a user cannot escalate to the privilege of a full root shell on the system, but just handle Tombs.

Tombs in your pockets

Tombs in the clouds

Server requirements

When creating a tomb make sure the device mapper is loaded among kernel modules or creation will fail and leave you in the dust.

modprobe dm_mod modprobe dm_crypt

Automatic doors

When logging out of a server it is very easy to forget and leave behind open tombs.

Using a simple cronjob will make sure that all tombs on server are closed automatically if the user who opened them is no more logged in:

#!/bin/zsh
PATH=$PATH:/usr/local/bin
tombs=`find /media -name "*tomb"`
for i in ${(f)tombs}; do
  { test -r ${i}/.tty } && {
    tty=`cat ${i}/.tty`
    uid=`cat ${i}/.uid`
    if [ -r ${tty} ]; then 
      ttyuid=`ls -ln ${tty} | awk '{print $3}'`
      { test "$ttyuid" = "$uid" } || { tomb close ${i} }
    else tomb close ${i}; fi
  }
done
return 0

This script assumes all tombs are opened inside the /media folder and that the 'tomb' script is included in root's PATH. Feel free to adapt it to your needs and then add it to root's cronjob so that it is run every minute.

Lack of entropy

To create a tomb key on a server (especially VPS) the problem becomes the lack of available entropy. Generating keys on a desktop (using the forge command) is the best choice, since entropy can be gathered simply moving the mouse. Anyway, in case there is no GNU/Linux desktop, one can try generating keys directly on the server in a reasonable time usi EGD, the Entropy Gathering Daemon.

On Debian/Ubuntu, install these packages:

# apt-get install libdigest-sha1-perl
# apt-get install ekeyd-egd-linux

Then check ekeyd's default configuration in:

/etc/default/ekeyd-egd-linux

Then download EGD from its website http://egd.sourceforge.net and finally start both EGD and ekeyd:

perl ./egd.pl # from inside EGD source directory
/etc/init.d/ekeyd-egd-linux start # as root on debian

You should see both daemons running, they will feed as much entropy as they can gather from various sources. Usually one will experience a burst of entropy when they are launched, then the stream keeps going rather slow anyway.

Acknowledgments

The development of Tomb was not supported by any governative or non-governative organization, its author and maintainer is an European citizen residing in the Netherlands.

Test cases for the development Tomb have been analyzed through active exchange with the needs of various activist communities, in particular the Italian Hackmeeting community and the mestizo community of southern Mexico, Chapas and Oaxaca.

Alphabetic Index

\printindex


2

On Debian 6.0 for instance the version of GLib-2 is too old and should be installed from source or from backports