tdocumentation and makefile scripts updates for release - tomb - the crypto undertaker
(HTM) git clone git://parazyd.org/tomb.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
(DIR) commit 0d690bf142ada38deb5930d7e791a63482d267f9
(DIR) parent 710558381fb5ffee177dee5a724682df04a46ad8
(HTM) Author: Jaromil <jaromil@dyne.org>
Date: Wed, 26 Nov 2014 20:28:06 +0100
documentation and makefile scripts updates for release
Diffstat:
M AUTHORS.md | 3 ++-
M ChangeLog.md | 9 +++++----
M INSTALL.md | 128 ++++++++++++++++++++++++++-----
M README.md | 69 +++++++++++--------------------
M doc/tomb.1 | 20 +++++++++++++-------
M extras/gtk-tray/Makefile | 11 ++++++++---
A extras/gtk-tray/gtkrc-2.0 | 3 +++
M extras/kdf-keys/Makefile | 8 ++++----
M tomb | 20 +++++++++++++-------
9 files changed, 180 insertions(+), 91 deletions(-)
---
(DIR) diff --git a/AUTHORS.md b/AUTHORS.md
t@@ -13,7 +13,8 @@ German translation by x3nu.
Testing, reviews and documentation are contributed by Dreamer, Shining
the Translucent, Mancausoft, Asbesto Molesto, Nignux, Vlax, The Grugq,
-Reiven, GDrooid, Alphazo, Brian May, TheJH and the Linux Action Show!
+Reiven, GDrooid, Alphazo, Brian May, TheJH, fsLeg, JoelMon and the
+Linux Action Show!
Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth.
(DIR) diff --git a/ChangeLog.md b/ChangeLog.md
t@@ -12,10 +12,11 @@ connections: it is possible to pipe cleartext secrets from stdin using
`-k cleartext` but that requires the --unsafe flag.
The security is also improved by avoiding most uses of temporary
-files. All code has been refactored for readability and integration
-with zsh features. Signal handlers are now in place, global arrays are
-used to keep track of temp files. Namespace has been revisioned and
-corrected, described in [HACKING](docs/HACKING.txt).
+files. The privilege escalation model has been simplified and sudo is
+called only when needed. All code has been refactored for readability
+and integration with zsh features. Signal handlers are now in place,
+global arrays are used to keep track of temp files. Namespace has been
+revisioned and corrected, described in [HACKING](docs/HACKING.txt).
## 1.5.3
### June 2014
(DIR) diff --git a/INSTALL.md b/INSTALL.md
t@@ -8,19 +8,19 @@ Tomb needs a few programs to be installed on a system in order to work:
* sudo
* gnupg
* cryptsetup
- * pinentry-curses (or -gtk or -qt as you prefer)
+ * pinentry-curses (and/or -gtk-2, -x11, -qt)
-Most systems provide these tools in their package collection,
-for instance on Debian/Ubuntu one can use 'apt-get install'
-on Fedora and CentOS one can use 'yum install'
+Most systems provide these tools in their package collection, for
+instance on Debian/Ubuntu one can use `apt-get install` on Fedora and
+CentOS one can use `yum install` and `pacman` on Arch.
## Install Tomb
To install Tomb simply download the source distribution (the tar.gz file)
-and decompress it. From a terminal:
+from https://files.dyne.org/tomb and decompress it. From a terminal:
cd Downloads
- tar xvfz Tomb-1.5.3.tar.gz (correct with actual file name)
+ tar xvfz Tomb-2.0.tar.gz (correct with actual file name)
Then enter its directory and run 'make install' as root, this will install
Tomb into /usr/local:
t@@ -33,12 +33,35 @@ After installation one can read the commandline help or read the manual:
tomb -h (print a short help on the commandline)
man tomb (show the full usage manual)
-At this point one can proceed creating a tomb, for instance:
+# Basic usage
- tomb dig -s 1000 secrets.tomb (be patient and wait a bit)
- tomb forge -k secrets.tomb.key (be patient and follow instructions)
+Once installed one can proceed creating a tomb, for instance:
+
+ tomb dig -s 10 secrets.tomb (dig a 10MB Tomb, be patient)
+ tomb forge -k secrets.tomb.key (be patient and follow instructions)
tomb lock -k secrets.tomb.key secrets.tomb
+When this is done, the tomb can be opened with:
+
+ tomb open -k secrets.tomb.key secrets.tomb
+
+The key can also be hidden in an image, to be used as key later
+
+ tomb bury -k secrets.tomb.key nosferatu.jpg
+ tomb open -k nosferatu.jpg secrets.tomb
+
+Or backupped to a QRCode that can be printed on paper and hidden in
+books. QRCodes can be scanned with any mobile application, resulting
+into a block of text that can be used with `-k` just as a normal key.
+
+ tomb engrave -k secrets.tomb.key (also an image will work)
+
+There are some more things that tomb can do for you, make sure you
+have a look at the manpage and at the commandline help to find out
+more.
+
+# Advanced usage
+
## Install optional tools
Tomb can use some optional tools to extend its functionalities:
t@@ -66,36 +89,99 @@ functionality or integrate it into particular system environments.
### extras/gtk-tray
-The Gtk3 tray adds a nifty tomb skull into the desktop toolbar: one can use it to close, slam and explore the open tomb represented by it.
+The Gtk tray adds a nifty tomb skull into the desktop toolbar: one can
+use it to close, slam and explore the open tomb represented by it.
-To have it enter `extras/gtk-tray` then
+When using pinentry-gtk-2 it also adds a little skull on the password
+input, useful to not confuse it with other password inputs.
+
+To have it change directory `extras/gtk-tray` then
1. make sure libnotify and gtk+-3.0 dev packages are available
2. run `make` inside the directory to build `tomb-gtk-tray`
- 3. optionally copy tomb-gtk-tray into your PATH (/usr/local/bin)
- 4. start `tomb-gtk-tray tombname` for each tomb
+ 3. run `sudo make install` (default PREFIX is `/usr/local`)
+ 4. start `tomb-gtk-tray tombname` after the tomb is open
-One can include the launch of tomb-gtk-tray from scripts.
+Of cource one can include the launch of tomb-gtk-tray scripts.
### extras/kdf-keys
-The KDF wrapper programs allows one to use KDF rounds on passwords in order to obstruct dictionary based and similar brute-forcing attacks.
+The KDF wrapper programs allows one to use KDF rounds on passwords in
+order to obstruct dictionary based and similar brute-forcing attacks.
-In case an attacker comes in possession of both a tomb and its key, the easy to memorize password can be guessed by rapidly trying different combinations. With KDF every try will require a significant amount of computation that will slow down the process avoiding tight loops and in fact making such attacks very onerous and almost impossible.
+In case an attacker comes in possession of both a tomb and its key,
+the easy to memorize password can be guessed by rapidly trying
+different combinations. With KDF every try will require a significant
+amount of computation that will slow down the process avoiding tight
+loops and in fact making such attacks very onerous and almost
+impossible.
To have it enter `extras/kdf-keys` then
1. make sure libgcrypt dev packages are available
2. run `make` inside the directory to build tomb-kdb-* executables
- 3. optionally copy tomb-kdb-* into your PATH (/usr/local/bin)
- 4. always use tomb using the `--kdf` flag: forge, lock, open etc.
+ 3. run `sudo make install` (default PREFIX is `/usr/local`)
+ 4. use `--kdf 100` when forging a key (tune the number to your cpu)
+
+KDF keys are recognized automatically by Tomb, which will always need
+the `extras/kdf-keys` program to be installed on a machine in order to
+open the Tomb.
-In case one creates and uses KDF keys then the --kdf flag must be always present for tomb to work correctly. It might be handy to create an alias tomb=`tomb --kdf`.
+Please note that it doesn't makes much sense to use KDF keys and
+steganography, since the latter will invalidate the brute-forcing
+protection. For details on the issue see [KNOWN_BUGS.md](KNOWN_BUGS).
### extras/po (translations)
-There are translations available for Tomb. If you wish to install them
-navigate to extras/po and run 'make install' as root:
+There are translations available for Tomb and they are installed by
+default. If you wish to update them manually navigate to extras/po
+and run 'make install' as root:
cd extras/po
sudo make install
+
+# Tomb support in other applications
+
+Can Tomb be used by other applications?
+
+Sure as Hell it can! Licensing issues aside ([GNU GPLv3+](COPYING)
+terms) Tomb provides machine-readable output and interaction via some
+flags:
+
+ flag | function
+--------------- | ------------------------------------------------
+ --no-color | avoids coloring output to allow parsing
+ --unsafe | allows passwords options and cleartext key from stdin
+ --tomb-pwd | specify the key password as argument
+ --tomb-old-pwd | specify the old key password as argument
+ -k cleartext | reads the unencrypted key from stdin
+
+Yet please consider that these flags may introduce vulnerabilities and
+other people logged on the same system can easily log your passwords
+while such commands are executing.
+We only recommend using the pinentry to input your passwords.
+
+## Python
+
+
+
+A Python wrapper is under development and already usable, but it
+introduces some vulnerabilities mentioned above. Find it in
+`extras/tomber`. For more information see [PYTHON](extras/PYTHON.md).
+
+## Graphical applications
+
+So far the only graphical application supporting Tomb volumes is
+[ZuluCrypt](https://github.com/mhogomchungu/zuluCrypt). One needs to
+activate the Tomb plugin included in its source and will be able to
+create, open and close tombs. It might still miss advanced Tomb
+functionalities that are only available from the command-line.
+
+## Let us know!
+
+If you plan to develop any kind of wrapper for Tomb you are welcome to
+let us know. Tomb is really meant to be maintained as a minimal tool
+for long-term compatibility when handling something so delicate as our
+secrets. For anything else we rely on your own initiative.
+
+Happy hacking! :&^)
(DIR) diff --git a/README.md b/README.md
t@@ -15,11 +15,10 @@
-Latest stable version: **2.0**
-
Updates on website: https://www.dyne.org/software/tomb
Get the stable .tar.gz signed release for production use!
+
Download it from https://files.dyne.org/tomb
# What is Tomb, the crypto undertaker?
t@@ -137,6 +136,9 @@ usability.
The code of Tomb is made to be read in literate programming style.
+The file [KNOWN_BUGS.md](KNOWN_BUGS) contains some notes on known
+vulnerabilities and threat model analysis.
+
In absence of the Tomb script it is always possible to access the
contents of a Tomb using a dm-crypt enabled Linux kernel, cryptsetup
and GnuPG issuing the following commands as root:
t@@ -183,7 +185,7 @@ tarball on https://files.dyne.org/tomb
# How can you help
-Donations are always welcome, see https://www.dyne.org/donate
+Donations are very welcome, please go to https://www.dyne.org/donate
Translations are also needed: they can be contributed via this website
https://poeditor.com/join/project?hash=33bdefea2e46b26f512a0caae55fbbb5
t@@ -195,53 +197,32 @@ to be further implemented.
For the bleeding edge visit https://github.com/dyne/Tomb
+If you plan to commit code into Tomb, please keep in mind this is a
+minimalist tool and its code should be readable. Guidelines on the
+coding style are illustrated in [doc/HACKING.txt](HACKING.txt).
+
Tomb's developers can be contacted using the issues on GitHub or over
IRC on https://irc.dyne.org channel **#dyne**
-Some enthusiastic ideas are in the [TODO](doc/TODO.org) file.
-
-Information on developers involved is found in the [AUTHORS](AUTHORS.md) file.
-
-# Can Tomb be used by applications?
-
-Sure as Hell it can! Licensing issues aside ([GNU GPLv3+](COPYING)
-terms) Tomb provides machine-readable output and interaction via some flags:
-
- flag | function
---------------- | ------------------------------------------------
- --no-color | avoids coloring output to allow parsing
- --unsafe | allows passwords options and cleartext key from stdin
- --tomb-pwd | specify the key password as argument
- --tomb-old-pwd | specify the old key password as argument
- --sudo-pwd | specify the sudo password as argument
- -k cleartext | reads the unencrypted key from stdin
-
-Yet please consider that these flags may introduce vulnerabilities and
-other people logged on the same system can easily log your passwords
-while such commands are executing.
-We only recommend using the pinentry to input your passwords.
-
-## Python
-
-
+# Licensing
-A Python wrapper is under development and already usable, but it
-introduces some vulnerabilities mentioned above. Find it in
-`extras/tomber`. For more information see [PYTHON](extras/PYTHON.md).
+Tomb is Copyright (C) 2007-2014 by the Dyne.org Foundation
-## Graphical applications
+Tomb is designed, written and maintained by Denis Roio <jaromil@dyne.org>
-So far the only graphical application supporting Tomb volumes is
-[ZuluCrypt](https://github.com/mhogomchungu/zuluCrypt). One needs to
-activate the Tomb plugin included in its source and will be able to
-create, open and close tombs. It might still miss advanced Tomb
-functionalities that are only available from the command-line.
+More information on all the developers involved is found in the
+[AUTHORS](AUTHORS.md) file.
-## Let us know!
+This source code is free software; you can redistribute it and/or
+modify it under the terms of the GNU Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
-If you plan to develop any kind of wrapper for Tomb you are welcome to
-let us know. Tomb is really meant to be maintained as a minimal tool
-for long-term compatibility when handling something so delicate as our
-secrets. For anything else we rely on your own initiative.
+This source code is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please refer
+to the GNU Public License for more details.
-Happy hacking! :&^)
+You should have received a copy of the GNU Public License along with
+this source code; if not, write to: Free Software Foundation, Inc.,
+675 Mass Ave, Cambridge, MA 02139, USA.
(DIR) diff --git a/doc/tomb.1 b/doc/tomb.1
t@@ -1,4 +1,4 @@
-.TH tomb 1 "November 14, 2014" "tomb"
+.TH tomb 1 "November 26, 2014" "tomb"
.SH NAME
Tomb \- the Crypto Undertaker
t@@ -410,18 +410,24 @@ One can also try to get in touch with developers via the #dyne chat channel on \
Tomb is designed, written and maintained by Denis Roio aka Jaromil.
-Tomb includes code by Anathema, Boyska and Hellekin O. Wolf.
+Tomb includes code by Anathema, Boyska, Hellekin O. Wolf and GDrooid.
-Tomb's artwork is contributed by Jordi aka Mon Mort
+Tomb's artwork is contributed by Jordi aka Mon Mort and Logan VanCuren.
-Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
-Asbesto Molesto and Nignux.
+Gettext internationalization and Spanish translation is contributed by
+GDrooid, French translation by Hellekin, Russian translation by fsLeg,
+German translation by x3nu.
-Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth
+Testing, reviews and documentation are contributed by Dreamer, Shining
+the Translucent, Mancausoft, Asbesto Molesto, Nignux, Vlax, The Grugq,
+Reiven, GDrooid, Alphazo, Brian May, TheJH, fsLeg, JoelMon and the
+Linux Action Show!
+
+Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth.
.SH COPYING
-This manual is Copyright (c) 2011-2013 by Denis Roio <\fIjaromil@dyne.org\fR>
+This manual is Copyright (c) 2011-2014 by Denis Roio <\fIjaromil@dyne.org\fR>
This manual includes contributions by Boyska.
(DIR) diff --git a/extras/gtk-tray/Makefile b/extras/gtk-tray/Makefile
t@@ -1,7 +1,12 @@
+PREFIX ?= /usr/local
all:
- gcc -I. `pkg-config --cflags libnotify gtk+-3.0` $(CFLAGS) -c tomb-gtk-tray.c
- gcc tomb-gtk-tray.o `pkg-config --libs libnotify gtk+-3.0` -o tomb-gtk-tray
+ $(CC) -I. `pkg-config --cflags libnotify gtk+-3.0` $(CFLAGS) -c tomb-gtk-tray.c
+ $(CC) tomb-gtk-tray.o `pkg-config --libs libnotify gtk+-3.0` -o tomb-gtk-tray
+
+install:
+ install -Dm666 gtkrc-2.0 ${DESTDIR}${PREFIX}/share/themes/tomb/gtk-2.0-key/gtkrc
+ install -Dm666 monmort.xpm ${DESTDIR}${PREFIX}/share/themes/tomb/gtk-2.0-key/monmort.xpm
clean:
- rm *.o tomb-gtk-tray
+ rm -f *.o tomb-gtk-tray
(DIR) diff --git a/extras/gtk-tray/gtkrc-2.0 b/extras/gtk-tray/gtkrc-2.0
t@@ -0,0 +1,3 @@
+pixmap_path "%prefix%/pixmaps"
+style "normal" { stock["gtk-dialog-authentication"] = {{"monmort.xpm"}} }
+widget "*" style "normal"
(DIR) diff --git a/extras/kdf-keys/Makefile b/extras/kdf-keys/Makefile
t@@ -2,10 +2,10 @@
PREFIX ?= /usr/local
all:
- gcc -O2 -o tomb-kdb-pbkdf2 pbkdf2.c -lgcrypt
- gcc -O2 -o tomb-kdb-pbkdf2-getiter benchmark.c -lgcrypt
- gcc -O2 -o tomb-kdb-pbkdf2-gensalt gen_salt.c -lgcrypt
- gcc -O2 -o tomb-kdb-hexencode hexencode.c
+ $(CC) -O2 -o tomb-kdb-pbkdf2 pbkdf2.c -lgcrypt
+ $(CC) -O2 -o tomb-kdb-pbkdf2-getiter benchmark.c -lgcrypt
+ $(CC) -O2 -o tomb-kdb-pbkdf2-gensalt gen_salt.c -lgcrypt
+ $(CC) -O2 -o tomb-kdb-hexencode hexencode.c
clean:
rm -f tomb-kdb-pbkdf2 tomb-kdb-pbkdf2-getiter tomb-kdb-pbkdf2-gensalt tomb-kdb-hexencode
(DIR) diff --git a/tomb b/tomb
t@@ -4,9 +4,6 @@
#
# A commandline tool to easily operate encryption of secret data
#
-# Homepage on: [tomb.dyne.org](http://tomb.dyne.org)
-#
-# In Emacs, you can use C-c @ C-q to (un)fold code using folding.el
# {{{ License
t@@ -16,10 +13,18 @@
#
# With contributions by Anathema, Boyska, Hellekin O. Wolf and GDrooid
#
-# Testing and reviews are contributed by Dreamer, Shining, Mancausoft,
-# Asbesto Molesto and Nignux.
+# Gettext internationalization and Spanish translation is contributed by
+# GDrooid, French translation by Hellekin, Russian translation by fsLeg,
+# German translation by x3nu.
+#
+# Testing, reviews and documentation are contributed by Dreamer, Shining
+# the Translucent, Mancausoft, Asbesto Molesto, Nignux, Vlax, The Grugq,
+# Reiven, GDrooid, Alphazo, Brian May, TheJH, fsLeg, JoelMon and the
+# Linux Action Show!
#
-# Tomb's artwork is contributed by Jordi aka Mon Mort.
+# Tomb's artwork is contributed by Jordi aka Mon Mort and Logan VanCuren.
+#
+# Cryptsetup was developed by Christophe Saout and Clemens Fruhwirth.
# This source code is free software; you can redistribute it and/or
# modify it under the terms of the GNU Public License as published by
t@@ -166,7 +171,8 @@ _cat() { local -a _arr;
_is_found() {
# returns 0 if binary if found in path
[[ "$1" = "" ]] && return 1
- return command -v "$1" 1>/dev/null 2>/dev/null
+ command -v "$1" 1>/dev/null 2>/dev/null
+ return $?
}
# Identify the running user