documentation for the new mechanism

skeleton for the user manual
This commit is contained in:
Jaromil 2013-03-25 12:02:56 +01:00
parent cc3cfccd21
commit 266319eee8
2 changed files with 261 additions and 57 deletions

View File

@ -1,3 +1,165 @@
#+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}
*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
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 on 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?
\indexentry{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.
[[images/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.
\indexentry{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]].
\indexentry{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
/work on contents in the crunchbang howto/
* Tombs in your pockets
* Tombs in the clouds
when creating a tomb make sure the device mapper is loaded among kernel modules
@ -23,3 +185,19 @@ perl ./egd.pl
/etc/init.d/ekeyd-egd-linux start
* Advanced techniques
* Credits
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.
* Remote tombs

View File

@ -37,16 +37,39 @@ applet (\fItomb-status\fR) if a desktop is present.
.SH COMMANDS
.B
.IP "create"
Creates a new encrypted storage tomb and its key, named as specified
by the given \fIargument\fR.
.IP "dig"
Generates a file that can be used as a tomb and will occupy as much
space as its desired initial size, the unlocked \fI.tomb\fR file can
then be locked using a \fI.tomb.key\fR. It takes a mandatory option
which is the \fI--size\fR in megabytes. This generation is relatively
simple: its a data dump (dd) of low-quality random data (from
/dev/urandom) and does not require root privileges.
.B
.IP "forge"
Creates a new \fIkey\fR and prompts the user for a \fIpassword\fR to
protect its usage. This operation requires high quality random data
(from /dev/random) which can take quite some time to be gathered on a
server: it works better on a desktop where the mouse can be moved
around for entropy.
.B
.IP "lock"
Initializes and locks an empty tomb (made with \fIdig\fR) using a key
(made with \fIforge\fR), making it ready for usage. After this
operation, the tomb can only be open in possession of the key and
knowing its password. This operation requires root privileges to
loopback mount, format the tomb (using LUKS and Ext4), then set the
key in its first LUKS slot.
.B
.IP "open"
Opens an existing tomb file specified in the \fIfirst argument\fR. If
a \fIsecond argument\fR is given it will indicate the \fImountpoint\fR
where the tomb should be made accessible, if not then the tomb is
mounted in a directory named after the filename and inside /media.
Opens an existing \fI.tomb\fR (first argument), if a second argument is
given it will indicate the \fImountpoint\fR where the tomb should be
made accessible, else the tomb is mounted in a directory inside
/media. The option \fI-k\fR can be used to specify a key file if none
is found besides the tomb and \fI-o\fR can be used to pass mount(8)
options (default: rw,noatime,nodev).
.B
.IP "list"
@ -58,70 +81,68 @@ returns an error if its not found.
.B
.IP "close"
Closes a currently open tomb. When \fIan argument\fR is specified, it
should be the name of a mounted tomb; if not specified and only one
tomb is open then it will be closed; if multiple tombs are open, the
command will list them on the terminal. The special
\fIargument\fR 'all' will close all currently open tombs. This command
fails if the tomb is in use by running processes, the command
\fIslam\fR can be used to force close.
.B
.IP "passwd"
Changes the password of a tomb key file specified in the \fIfirst
argument\fR. It will need the old password to decode the key file, it
will then reencode it using the new password.
.B
.IP "resize"
Increase the size of a tomb file to the amount of megabytes specified
by the \fI-s\fI option (total amount of the new size). Tombs cannot be
made smaller with this command, only bigger. This command makes use of
the cryptsetup resize feature and the resize2fs command, hence it
supports only tombs formatted with an EXT filesystem.
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 \fIall\fR to close all currently open tombs. This command fails if
the tomb is in use by running processes (to force close, see
\fIslam\fR below).
.B
.IP "slam"
Closes a tomb like the command \fIclose\fR does, but in case it is in
use looks for all the processes accessing its files and violently
kills them using \-9.
Closes a tomb like the command \fIclose\fR does, but it doesn't fails
even if the tomb is in use by other application processes: it looks
for them and violently kills \-9 each of them. This command may
provoke unsaved data loss, but assists users to face surprise
situations.
.B
.IP "passwd"
Changes the password protecting a \fIkey\fR file specified as first
argument. The user will need to know the key's current password, then
its content will be decoded and reencoded using the new one. This
action can't be forced if the current password is not known.
.B
.IP "resize"
Increase the size of a tomb file to the amount specified by the
\fI--size\fR option (in megabytes). Tombs cannot be made smaller with
this command, only bigger. This command makes use of the cryptsetup
resize feature and the resize2fs command, hence it supports only tombs
formatted with an Ext filesystem.
.B
.IP "bury"
Hides a tomb key (\fIfirst argument\fR) inside a jpeg image (\fIsecond
argument\fR) using steganography: the image will change in a way that
cannot be noticed by human eyes and the presence of the key inside it
isn't detectable without the right password. This option is useful to
backup tomb keys in unsuspected places; it uses steghide and the
serpent encryption algorithm.
Hides a tomb key (first argument) inside a \fIjpeg image\fR (second
argument) using \fIsteganography\fR: 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 \fIsteghide\fR.
.B
.IP "exhume"
Extracts a named tomb key (\fIfirst argument\fR) from a (jpeg) image file
(\fIsecond argument\fR) known to be containing it, if the right password is
given. This is used to recoved buried keys from unsuspected places.
This command recovers from jpeg images the keys that were previously
hidden into them using \fIbury\fR. Exhume requires a key filename
(first argument) and a \fIjpeg image\fR file (second argument) known
to be containing it. If the right key password is given, the key will
be exhumed, but if the password is not known, it is very hard to
verify if a key is buried in the image or not.
.SH OPTIONS
.B
.B
.IP "-s \fI<MBytes>\fR"
When creating or resizing a tomb, this option MUST be used to specify
the size of the new \fIfile\fR to be created, in megabytes.
When digging or resizing a tomb, this option must be used to specify
the \fIsize\fR of the new file to be created, in megabytes.
.B
.IP "-k \fI<keyfile>\fR"
When opening a tomb, this option can be used to specify the location
of the key to use. Keys are created with the same name of the tomb
file adding a '.key' suffix, but can be later renamed and transported
on other media. When a key is not found, the program asks to insert a
USB storage device and it will look for the key file inside it.
If \fI<keyfile>\fR is "-" (dash), it will read stdin
.IP
When creating a tomb, this option can be used to specify the name (and
location) of the key you are creating. For example, you could use
.EX
tomb create -s 100 tombname -k /media/usb/tombname
.EE
to put the key on a usb pendrive
When opening a tomb, this option can specify the location of the key
file to use. Keys are created with the same name of the tomb file
adding a '.key' suffix, but can be later renamed and transported on
other media. If \fI<keyfile>\fR is "-" (dash), it will read it from
stdin.
.B
.IP "--kdf \fI<method>\fR"
@ -198,11 +219,12 @@ command to bind locations inside the tomb to locations found in $HOME
so 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:
.EX
mail mail
.gnupg .gnupg
.fmrc .fetchmailrc
.mozilla .mozilla
.EE
.B
.IP "post-hooks"
@ -239,7 +261,11 @@ If you don't need swap, execute \fI swapoff -a\fR. If you really need
it, you could make an encrypted swap it. Tomb doesn't detect if your
swap is encrypted, and will complain anyway.
.SH EXAMPLES
Inline example:
.EX
test test
.EE
.SH BUGS
Please report bugs on the tracker at
.UR http://bugs.dyne.org