tomb

the crypto undertaker
git clone git://parazyd.org/tomb.git
Log | Files | Refs | README | LICENSE

commit ad59dec3da023bafe1803f4741408de4dc563abe
parent c20ca3a9209afd0f469f91951a9b111f28eaecfe
Author: Jaromil <jaromil@dyne.org>
Date:   Sat, 25 May 2013 16:29:19 +0200

documentation updates

Diffstat:
MAUTHORS | 12++++++++----
MChangeLog | 14++++++++++++++
MREADME | 61+++++++++++++++++++++++++++++++++++--------------------------
Mdoc/tomb.1 | 96+++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------
Mtomb | 1+
5 files changed, 120 insertions(+), 64 deletions(-)

diff --git a/AUTHORS b/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, -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 diff --git a/ChangeLog b/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 diff --git a/README b/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 -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 @@ -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. diff --git a/doc/tomb.1 b/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 -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. @@ -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 diff --git a/tomb b/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