tdocumentation updates - tomb - the crypto undertaker
HTML git clone git://parazyd.org/tomb.git
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
DIR commit ad59dec3da023bafe1803f4741408de4dc563abe
DIR parent c20ca3a9209afd0f469f91951a9b111f28eaecfe
HTML Author: Jaromil <jaromil@dyne.org>
Date: Sat, 25 May 2013 16:29:19 +0200
documentation updates
Diffstat:
M AUTHORS | 12 ++++++++----
M ChangeLog | 14 ++++++++++++++
M README | 61 ++++++++++++++++++-------------
M doc/tomb.1 | 96 ++++++++++++++++++++-----------
M tomb | 1 +
5 files changed, 120 insertions(+), 64 deletions(-)
---
DIR diff --git a/AUTHORS b/AUTHORS
t@@ -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,
-Shining, Mancausoft, Asbesto Molesto.
+Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
+Asbesto Molesto and Nignux.
+
+Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth
-Cryptsetup is developed by Christophe Saout and Clemens Fruhwirth
+Tomb's developers can be contacted via the "crypto" mailinglist on
+http://lists.dyne.org
DIR diff --git a/ChangeLog b/ChangeLog
t@@ -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
t@@ -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
DIR diff --git a/README b/README
t@@ -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
-integrates in your desktop.
-
-** 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.
+kernel (cryptsetup and LUKS). Tomb can also produce machine parsable
+output to facilitate its use inside graphical applications.
** How does it works
-Tomb generates 'key files' and protects them with a password choosen
-by the user; the key files are then used to encrypt loop-back mounted
-partitions, like single files containing a filesystem inside: this way
-keys can be separated from data for safer transports when required.
+This tool can be used to dig .tomb files (Luks volumes), forge keys
+protected by a password (GnuPG symmetric encryption) and use the keys
+to lock the tombs. Tombs are like single files whose contents are
+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
-is pretty readable. The name transition from 'mknest' to 'tomb' is
-marked by the adaptation of mknest to work on the Debian operating
-system and it has been used in production environments for the past 4
-years.
+As of today, Tomb is a well stable tool also used in mission critical
+situations by a number of activists in endangered zones. It has been
+reviewed by forensics analysts and it can be considered to be safe for
+military grade use, where the integrity of informations stored depend
+from the user's behaviour and the strenght of a standard AES256
+CBC-ESSIV encryption algorithm.
** How can you help
t@@ -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.
DIR diff --git a/doc/tomb.1 b/doc/tomb.1
t@@ -1,4 +1,4 @@
-.TH tomb 1 "Sept 26, 2011" "tomb"
+.TH tomb 1 "May 25, 2013" "tomb"
.SH NAME
Tomb \- the Crypto Undertaker
t@@ -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
t@@ -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
t@@ -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
-executes desktop applications as processes owned by the user.
+To be made available on multi user systems, the superuser execution of
+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
-and \fIabort if your system has swap activated\fR. You can disable
-this behaviour using the \fI--force\fR. Before doing that, however,
-you may be interested in knowing the risks of doing so:
+On execution of certain commands Tomb will complain about swap memory
+on disk when that is presend and \fIabort if your system has swap
+activated\fR. You can disable this behaviour using the
+\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.
t@@ -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
-swap is encrypted, and will complain anyway.
+it, you could make an encrypted swap partition. Tomb doesn't detect if
+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
-.UR http://dyne.org/contact
-web page
+Get in touch with developers via mail by subscribing the "crypto" mailinglist
+.UR http://lists.dyne.org
.UE
-or via chat on
-.UR http://irc.dyne.org
+or via the #dyne chat channel on
+.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,
-Shining, Mancausoft, Asbesto Molesto.
+Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
+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
DIR diff --git a/tomb b/tomb
t@@ -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