#+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]]. For these and other reasons - presumably very sad ones for its users - Truecrypt has also been discontinued. \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