Tomb/doc/Tomb_User_Manual.org

#+TITLE: Tomb User Manual
#+AUTHOR: Jaromil @ Dyne.org

#+LaTeX_CLASS: article
#+LaTeX_CLASS_OPTIONS: [a4,onecolumn,portrait]
#+LATEX_HEADER: \usepackage[english]{babel}
#+LATEX_HEADER: \usepackage{amsfonts, amsmath, amssymb}
#+LATEX_HEADER: \usepackage{ucs}
#+LATEX_HEADER: \usepackage[utf8x]{inputenc}
#+LATEX_HEADER: \usepackage[T1]{fontenc}
#+LATEX_HEADER: \usepackage{hyperref}
#+LATEX_HEADER: \usepackage[pdftex]{graphicx}
#+LATEX_HEADER: \usepackage{fullpage}
#+LATEX_HEADER: \usepackage{lmodern}
#+LATEX_HEADER: \usepackage[hang,small]{caption}
#+LATEX_HEADER: \usepackage{float}
#+LATEX_HEADER: \usepackage{makeidx}
#+LATEX_HEADER: \makeindex
*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.

#+KEYWORDS: Crypto, Storage, Luks, Cryptsetup, DM-Crypt, Privacy, Secrecy

#+EXCLUDE_KEYWORD: noexport



[TABLE-OF-CONTENTS]

#+LATEX: \newpage

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

#+BEGIN_QUOTE
  "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 [[http://www.newschool.edu/centers/socres/privacy/Home.html][Privacy Conference, Social Research, New School University]])
#+END_QUOTE


** Who needs Tomb

[[file: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-Crypt[fn:dm-crypt]
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?

\index{dyne:bolic}

Tomb is an evolution of the /Nesting/ tool developed in 2001 for the
[[http://www.dynebolic.org][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.

[[file: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.

\index{truecrypt}
[[http://en.wikipedia.org/wiki/TrueCrypt][TrueCrypt]] makes use of statically linked libraries so that its code is
hard to audit, plus is [[http://lists.freedesktop.org/archives/distributions/2008-October/000276.html][not considered free]] by free operating system
distributors because of liability reasons, see [[http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=364034][Debian]], [[https://bugs.edge.launchpad.net/ubuntu/+bug/109701][Ubuntu]], [[http://lists.opensuse.org/opensuse-buildservice/2008-10/msg00055.html][Suse]],
[[http://bugs.gentoo.org/show_bug.cgi?id=241650][Gentoo]] and [[https://fedoraproject.org/wiki/ForbiddenItems#TrueCrypt][Fedora]].

\index{cryptkeeper}
[[http://tom.noflag.org.uk/cryptkeeper.html][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 [[http://www.arg0.net/encfs][EncFS]] which
implements weaker encryption than dm-crypt and it doesn't promotes the
separated storage of keys.

At last, the [[https://we.riseup.net/debian/automatically-mount-encrypted-home][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 [[http://dyne.org/donate][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:

 - *Zsh* http://www.zsh.org
 - *Cryptsetup*
 - *Sudo*
 - *GnuPG* http://www.gnupg.org
 - *Pinentry* 

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 [[http://tomb.dyne.org/codedoc][review Tomb's code]]. Those running on [[http://www.dynebolic.org][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 [[http://files.dyne.org/tomb/releases][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-2[fn:debglib]

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

*** 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:

#+BEGIN_EXAMPLE
#!/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
#+END_EXAMPLE

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 [[http://www.hackmeeting.org][Hackmeeting community]] and the mestizo community of
southern Mexico, Chapas and Oaxaca.

* Alphabetic Index


\printindex