commit 266319eee821eaee7f078c86695b66394c4163c8
parent cc3cfccd210e8dcd1e3c694a11a6f5310f2b01ab
Author: Jaromil <jaromil@dyne.org>
Date: Mon, 25 Mar 2013 12:02:56 +0100
documentation for the new mechanism
skeleton for the user manual
Diffstat:
| M | doc/Tomb_User_Manual.org | | | 178 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | doc/tomb.1 | | | 132 | +++++++++++++++++++++++++++++++++++++++++++++++-------------------------------- |
2 files changed, 257 insertions(+), 53 deletions(-)
diff --git a/doc/Tomb_User_Manual.org b/doc/Tomb_User_Manual.org
@@ -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
+
+
diff --git a/doc/tomb.1 b/doc/tomb.1
@@ -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.
+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 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 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.
+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 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.
+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 "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.
.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
