From 266319eee821eaee7f078c86695b66394c4163c8 Mon Sep 17 00:00:00 2001 From: Jaromil Date: Mon, 25 Mar 2013 12:02:56 +0100 Subject: [PATCH] documentation for the new mechanism skeleton for the user manual --- doc/Tomb_User_Manual.org | 178 +++++++++++++++++++++++++++++++++++++++ doc/tomb.1 | 140 +++++++++++++++++------------- 2 files changed, 261 insertions(+), 57 deletions(-) diff --git a/doc/Tomb_User_Manual.org b/doc/Tomb_User_Manual.org index be3c904..40b47a2 100644 --- 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 index 9e56ba7..04f4072 100644 --- 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. - -.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\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\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\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\fR is "-" (dash), it will read it from +stdin. .B .IP "--kdf \fI\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