mirror of
https://github.com/Llewellynvdm/Tomb.git
synced 2024-11-22 12:35:13 +00:00
documentation for the new mechanism
skeleton for the user manual
This commit is contained in:
Jaromil
parent
cc3cfccd21
commit
266319eee8
@ -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
|
||||
|
||||
|
||||
|
||||
140
doc/tomb.1
140
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<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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user