documentation updates

AUTHORS

@@ -1,10 +1,14 @@
+
 Tomb is designed and written by Denis Roio aka Jaromil.
 
-Tomb includes code by Anathema and Boyska.
+Tomb includes code by Anathema, Boyska and Hellekin O. Wolf.
 
 Tomb's artwork is contributed by Jordi aka Mon Mort
 
-Testing and reviews are contributed by Hellekin O. Wolf, Dreamer,
+Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
-Shining, Mancausoft, Asbesto Molesto.
+Asbesto Molesto and Nignux.
 
-Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth
+Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth
+
+Tomb's developers can be contacted via the "crypto" mailinglist on
+http://lists.dyne.org

ChangeLog

@@ -1,4 +1,17 @@
+May 2013 - 1.3
+
+	A refactoring of Tomb's main script internals was made, including
+	a new messaging system, machine parsable output, cleaner code and
+	updated compatibility to Debian 7. A new search feature lets users
+	index and run fast filename searches in their open tombs. Creation
+	of tombs is broken out in three steps (dig, forge and lock).
+	Source distribution includes experimental add-ons for a python
+	GUI, KDF key encryption and a key "undertaker". Documentation was
+	updated.
+
+
 Nov 2011 - 1.2
+
 	Includes an Important fix to password parsing for spaces and
 	extended chars, plus a new 'passwd' command to change a key's
 	password. Tomb now checks for swap to avoid its usage (see SWAP
@@ -6,6 +19,7 @@ Nov 2011 - 1.2
 	full.
 
 May 2011 - 1.1
+
 	Fixes to mime types, icons and desktop integration. A new 'list'
 	command provides an overview on all tombs currently open. Now a
 	tomb cannot be mounted multiple times, the message console has

README

@@ -12,49 +12,55 @@ X~     `?888888hx~  ...ue888b   .888: x888  x888.   8888   .
 '    "*88888888*      'Y"         `~    "    `"`    `%888*%"
         ^"***"`                                        "`
 
-a simple commandline tool to manage encrypted storage  v.1.2
+A minimalistic commandline tool to manage encrypted volumes  v.1.3
 
                    http://tomb.dyne.org
 
 
 Tomb aims to be a free and open source system for easy encryption and
 backup of personal files, written in code that is easy to review and
-links shared OS components.
+links shared GNU/Linux components.
 
 At present time, Tomb consists of a simple shell script (Zsh) using
 standard filesystem tools (GNU) and the cryptographic API of the Linux
-kernel (cryptsetup and LUKS), plus a status tray application which
+kernel (cryptsetup and LUKS). Tomb can also produce machine parsable
-integrates in your desktop.
+output to facilitate its use inside graphical applications.
-
-** Who needs Tomb
-
-Our target community are desktop 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.
-
-If you don't own a laptop then it's possible to go around with a USB
-stick and borrow computers, still leaving no trace and keeping your
-data safe during transports. Tomb aims to facilitate all this and to
-be interoperable across popular GNU/Linux operating systems.
 
 ** How does it works
 
-Tomb generates 'key files' and protects them with a password choosen
+This tool can be used to dig .tomb files (Luks volumes), forge keys
-by the user; the key files are then used to encrypt loop-back mounted
+protected by a password (GnuPG symmetric encryption) and use the keys
-partitions, like single files containing a filesystem inside: this way
+to lock the tombs. Tombs are like single files whose contents are
-keys can be separated from data for safer transports when required.
+unaccessible in absence of the key they were locked with and its
+password.
+
+Once open the tombs are just like normal folders and can contain
+different files, plus they offer advanced functionalities like bind
+and execution hooks and fast search, or they can be slammed close even
+if busy. Keys can be stored on separate media like USB sticks, NFC or
+bluetooth devices to make the transport of data safer: one always
+needs both the tomb and the key, plus its password, to access it.
+
+The tomb script takes care of several details to improve the security
+of tombs in every day usage: adopting pinentry for passwords,
+facilitating the storage of backup keys using image steganography,
+listing open tombs and selectively closing them, warning the user
+about their size and last time they were used, etc.
 
 ** Stage of development
 
 Tomb is an evolution of the 'mknest' tool developed for the dyne:bolic
 GNU/Linux distribution, which is used by its 'nesting' mechanism to
-encrypt the Home directory of users.
+encrypt the Home directory of users, a system implemented already in
+2001. Since then, the same shell routines kept being maintained and in
+2007 they were adapted to work on Debian and Arch distributions.
 
-As such, it uses well tested and reviewed routines and its shell code
+As of today, Tomb is a well stable tool also used in mission critical
-is pretty readable. The name transition from 'mknest' to 'tomb' is
+situations by a number of activists in endangered zones. It has been
-marked by the adaptation of mknest to work on the Debian operating
+reviewed by forensics analysts and it can be considered to be safe for
-system and it has been used in production environments for the past 4
+military grade use, where the integrity of informations stored depend
-years.
+from the user's behaviour and the strenght of a standard AES256
+CBC-ESSIV encryption algorithm.
 
 ** How can you help
 
@@ -62,8 +68,11 @@ Code is pretty short and readable: start looking around it and the
 materials found in doc/ which are good pointers at security measures
 to be further implemented.
 
+Tomb's developers can be contacted via the "crypto" mailinglist on
+http://lists.dyne.org
+
 Enthusiastic ideas are in the TODO file.
 
 Donations are always welcome, see http://dyne.org/donate
 
-More about who is currently involved in the AUTHORS file.
+Information on developers involved is found in the AUTHORS file.

doc/tomb.1

@@ -1,4 +1,4 @@
-.TH tomb 1 "Sept 26, 2011" "tomb"
+.TH tomb 1 "May 25, 2013" "tomb"
 
 .SH NAME
 Tomb \- the Crypto Undertaker
@@ -6,10 +6,6 @@ Tomb \- the Crypto Undertaker
 .SH SYNOPSIS
 .B
 .IP "tomb [options] command [arguments]"
-.B
-.IP "tomb-open [file]"
-.B
-.IP "tomb-status mountpoint"
 
 .SH DESCRIPTION
 
@@ -27,12 +23,6 @@ hidden in a filesystem; it encourages users to keep their keys
 separate from tombs, for instance keeping a tomb file on your computer
 harddisk and its key file on a USB stick.
 
-For simplified use, the command \fItomb-open\fR starts a wizard that
-guides users in the creation of a new tomb or, if a tomb file is
-specified as \fIargument\fR, it opens it and makes it accessible in a
-default location under the /media folder, starting the status tray
-applet (\fItomb-status\fR) if a desktop is present.
-
 
 .SH COMMANDS
 
@@ -251,17 +241,24 @@ batch operations every time a tomb is opened.
 
 The tomb commandline tool needs to acquire super user rights to
 execute most of its operations: to do so it uses sudo(8), while
-pinentry(1) is adopted to collect passwords from the user.
+pinentry(1) is adopted to collect passwords from the user. Tomb
+executes as super user only when required.
 
-Tomb executes as super user only those commands requiring it, while it
+To be made available on multi user systems, the superuser execution of
-executes desktop applications as processes owned by the user.
+the tomb script can be authorized for users without jeopardizing the
+whole system's security: just add such a line to \fI/etc/sudoers\fR:
+
+.EX
+	username ALL=NOPASSWD: /usr/local/bin/tomb
+.EE
 
 .SH SWAP
 
-During "create", "open" and "passwd" operations, swap will complain
+On execution of certain commands Tomb will complain about swap memory
-and \fIabort if your system has swap activated\fR. You can disable
+on disk when that is presend and \fIabort if your system has swap
-this behaviour using the \fI--force\fR. Before doing that, however,
+activated\fR. You can disable this behaviour using the
-you may be interested in knowing the risks of doing so:
+\fI--force\fR. Before doing that, however, you may be interested in
+knowing the risks of doing so:
 .IP \(bu
 During such operations a lack of available memory could cause the swap
 to write your secret key on the disk.
@@ -273,48 +270,79 @@ written on your disk, not encrypted.
 .P
 
 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
+it, you could make an encrypted swap partition. Tomb doesn't detect if
-swap is encrypted, and will complain anyway.
+your swap is encrypted, and will complain anyway.
 
 .SH EXAMPLES
-Create a 128MB large "secret" tomb and its keys, then open it
+
+.IP \(bu
+Create a 128MB large "secret" tomb and its keys, then open it:
+
 .EX
 	tomb dig -s 128 secret.tomb
 	tomb forge secret.tomb.key
 	tomb lock secret.tomb secret.tomb.key
 	tomb open secret.tomb -k secret.tomb.key
 .EE
+
+.IP \(bu
+Create a bind hook that places your GnuPG folder inside the tomb, but
+makes it reachable from the standard $HOME/.gnupg location every time
+the tomb will be opened:
+
+.EX
+	tomb open GPG.tomb
+	echo ".gnupg .gnupg" > /media/GPG.tomb/bind-hooks
+	mv ~/.gnupg /media/GPG.tomb/.gnupg && mkdir ~/.gnupg
+	tomb close GPG && tomb open GPG.tomb
+.EE
+
+.IP \(bu
+Create an exec post hook that launches a Firefox browser every time
+the tomb will be opened, keeping all its profile data inside it:
+
+.EX
+	tomb open FOX.tomb
+	touch        /media/FOX.tomb/post-hooks
+	chmod +x     /media/FOX.tomb/post-hooks
+	cat <<EOF >> /media/FOX.tomb/post-hooks
+#!/usr/bin/env bash
+if [ "$1" == open ]; then
+  firefox -no-remote -profile $(dirname $0)/firefox_prof &
+fi
+EOF
+.EE
+
 .SH BUGS
 Please report bugs on the tracker at
-.UR http://bugs.dyne.org
+.UR https://bugs.dyne.org
 .UE
 
-Get in touch with developers via mail using this
+Get in touch with developers via mail by subscribing the "crypto" mailinglist
-.UR http://dyne.org/contact
+.UR http://lists.dyne.org
-web page
 .UE
-or via chat on
+or via the #dyne chat channel on
-.UR http://irc.dyne.org
+.UR https://irc.dyne.org
 .UE
 
 .SH AUTHORS
 
-Tomb is designed and written by Denis Roio aka Jaromil.
+Tomb is designed, written and maintained by Denis Roio aka Jaromil.
 
-Tomb includes code by Anathema and Boyska.
+Tomb includes code by Anathema, Boyska and Hellekin O. Wolf.
 
 Tomb's artwork is contributed by Jordi aka Mon Mort
 
-Testing and reviews are contributed by Hellekin O. Wolf, Dreamer,
+Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
-Shining, Mancausoft, Asbesto Molesto.
+Asbesto Molesto and Nignux.
 
-Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth
+Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth
 
 .SH COPYING
 
-This manual is Copyleft (c) 2011-2013 Denis Roio <\fIjaromil@dyne.org\fR>
+This manual is Copyright (c) 2011-2013 by Denis Roio <\fIjaromil@dyne.org\fR>
 
-It includes contributions by Boyska
+This manual includes contributions by Boyska.
 
 Permission is  granted to copy,  distribute and/or modify  this manual
 under the terms of the  GNU Free Documentation License, Version 1.1 or

tomb

@@ -355,6 +355,7 @@ EOF
     fi # are we root already
 
     # make sure necessary kernel modules are loaded
+    modprobe dm_mod
     modprobe dm_crypt
 
     return 0