commit 22db5f7201b644fac298dc0aecfb0510ceb6ad11
parent cf66907fa2c891e71661970e0c1c198afab14227
Author: Jaromil <jaromil@dyne.org>
Date: Tue, 15 Apr 2014 12:56:00 +0200
documentation update
Diffstat:
| R | AUTHORS -> AUTHORS.md | | | 0 | |
| D | ChangeLog | | | 122 | ------------------------------------------------------------------------------- |
| A | ChangeLog.md | | | 154 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | INSTALL.md | | | 65 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| R | KNOWN_BUGS -> KNOWN_BUGS.md | | | 0 | |
| D | README | | | 96 | ------------------------------------------------------------------------------- |
| A | README.md | | | 101 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | doc/TODO.org | | | 76 | +++++++++++++++++++++++++++++++++++++++++----------------------------------- |
8 files changed, 361 insertions(+), 253 deletions(-)
diff --git a/AUTHORS b/AUTHORS.md
diff --git a/ChangeLog b/ChangeLog
@@ -1,122 +0,0 @@
-February 2014 - 1.5.2
-
- Removed automatic guessing of key file besides tomb to encourage
- users to keep tomb and key separated, but also to simplify the
- code in key retrieval and avoid a bug occurring in the previous
- version.
-
-February 2014 - 1.5.1
-
- Fix to stdin piping of keys, which were not correctly processed
- nor were deleted from volatile memory (tmpfs). Version is now
- updated accordingly.
-
-January 2014 - 1.5
- Minor bugfixes to documentation, error handling, support for
- multiple and encrypted swap partitions and qr code engraving.
- This release also includes some minor code refactoring of
- load_key() and loop mount checks. Also the tray app is updated
- to gtk-3 and works simply with a tomb name as argument.
- Documentation was updated accordingly.
-
-June 2013 - 1.4
-
- This release fixes an important bug affecting Tomb 1.3.* which
- breaks backward compatibility with older tombs and invalidates
- keys created using 1.3 or 1.3.1. For more information about it
- read the file KNOWN_BUGS. New features are also included:
- indexing and search of file contents, engraving of keys into paper
- printable QRCodes for backup purposes and improvements in key
- encryption. A setkey command is added to change the key file that
- is locking a Tomb. This release restores backward compatibility
- with tombs created before the 1.3 release series.
-
-June 2013 - 1.3.1 (DEPRECATED USAGE, see 1.4 and KNOWN_BUGS)
-
- Major bugfixes following the recent refactoring. This release
- fixes various advanced commands as search/index, KDF key
- protection against dictionary attacks and steganographic hiding of
- keys. It provides compatibility across GnuPG 1.4.11 and .12 which
- broke the decoding of keys. Usage of commandline option is made
- consistent and full paths are honored. A new test suite is
- included and documentation is updated accordingly.
-
-May 2013 - 1.3 (DEPRECATED USAGE, see 1.4 and KNOWN_BUGS)
-
- 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
- section in manpage) and warns the user when the tomb is almost
- 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
- colors and better messages. Different mount options (like
- read-only) can also be specified by hand on the commandline.
-
-March 2011 - 1.0
-
- Clean and stable. Now passwords are handled exclusively using
- pinentry. Also support for steganography of keys (bury and exhume)
- was added to the commandline. Commandline and desktop operations
- are well separated so that tomb can be used via remote terminal. A
- new command 'slam' immediately closes a tomb killing all processes
- that keep it busy.
-
-February 2011 - 0.9.2
-
- The tomb-open wizard now correctly guides you through the creation
- of new tombs and helps when saving the keys on external USB
- storage devices. The status tray now reliably closes its tomb.
-
-February 2011 - 0.9.1
-
- Sourcecode cleanup, debugging and testing.
- Integrated some feedback after filing Debian's ITP and RFS.
-
-January 2011 - 0.9
-
- Tomb is now a desktop application following freedesktop standards:
- it provides a status tray and integrates with file managers. The
- main program has been thoroughly tested and many bugs were fixed.
-
-August 2010
-
- The first usable version of Tomb goes public among hacker friends
-
-During the year 2009
-
- Tomb has been extensively tested, perfectioned and documented
- after being used by its author
-
-Sometime in 2007
-
- mknest was refactored to work on the Debian distribution and since
- then renamed to Tomb. dyne:bolic specific dependencies where
- removed, keeping Zsh as the shell script it is written with.
-
-Back in 2005
-
- The "nesting" feature of dyne:bolic GNU/Linux lets users encrypt
- their home in a file, using a shell script and a graphical
- interface called Taschino.
-
- Taschino included a shell script wrapping cryptsetup to encrypt
- loopback mounted partitions with the algo AES-256 (cbc-essiv
- mode): this script was called 'mkNest' and its the ancestor of
- Tomb.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -0,0 +1,154 @@
+# Tomb ChangeLog
+
+## 1.5.2
+### February 2014
+
+Removed automatic guessing of key file besides tomb to encourage
+users to keep tomb and key separated, but also to simplify the
+code in key retrieval and avoid a bug occurring in the previous
+version.
+
+## 1.5.1
+### February 2014
+
+Fix to stdin piping of keys, which were not correctly processed
+nor were deleted from volatile memory (tmpfs).
+
+Version is now updated accordingly.
+
+## 1.5
+### January 2014
+
+Minor bugfixes to documentation, error handling, support for
+multiple and encrypted swap partitions and qr code engraving.
+
+This release also includes some minor code refactoring of
+load_key() and loop mount checks. Also the tray app is updated
+to gtk-3 and works simply with a tomb name as argument.
+
+Documentation was updated accordingly.
+
+## 1.4
+### June 2013
+
+This release fixes an important bug affecting Tomb 1.3.* which
+breaks backward compatibility with older tombs and invalidates
+keys created using 1.3 or 1.3.1. For more information about it
+read the file KNOWN_BUGS.
+
+New features are also included:
+indexing and search of file contents, engraving of keys into paper
+printable QRCodes for backup purposes and improvements in key
+encryption. A setkey command is added to change the key file that
+is locking a Tomb.
+
+This release restores backward compatibility
+with tombs created before the 1.3 release series.
+
+## 1.3.1 (DEPRECATED, see [KNOWN_BUGS](KNOWN_BUGS.md))
+### June 2013
+
+Major bugfixes following the recent refactoring.
+
+This release fixes various advanced commands as search/index, KDF key
+protection against dictionary attacks and steganographic hiding of
+keys. It provides compatibility across GnuPG 1.4.11 and .12 which
+broke the decoding of keys. Usage of commandline option is made
+consistent and full paths are honored.
+
+A new test suite is included and documentation is updated accordingly.
+
+## 1.3 (DEPRECATED, see [KNOWN_BUGS](KNOWN_BUGS.md))
+### May 2013
+
+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.
+
+
+## 1.2
+### Nov 2011
+
+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
+section in manpage) and warns the user when the tomb is almost
+full.
+
+## 1.1
+### May 2011
+
+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
+colors and better messages.
+
+Different mount options (like read-only) can also be specified by hand on the commandline.
+
+## 1.0
+### March 2011
+
+Clean and stable. Now passwords are handled exclusively using
+pinentry. Also support for steganography of keys (bury and exhume)
+was added to the commandline.
+
+Commandline and desktop operations are well separated so that tomb can be used via remote terminal.
+
+A new command 'slam' immediately closes a tomb killing all processes that keep it busy.
+
+## 0.9.2
+### February 2011
+
+The tomb-open wizard now correctly guides you through the creation
+of new tombs and helps when saving the keys on external USB
+storage devices. The status tray now reliably closes its tomb.
+
+## 0.9.1
+### February 2011
+
+Sourcecode cleanup, debugging and testing.
+
+Integrated some feedback after filing Debian's ITP and RFS.
+
+## 0.9
+### January 2011
+
+Tomb is now a desktop application following freedesktop standards:
+it provides a status tray and integrates with file managers.
+
+The main program has been thoroughly tested and many bugs were fixed.
+
+## August 2010
+
+The first usable version of Tomb goes public among hacker friends
+
+## During the year 2009
+
+Tomb has been extensively tested, perfectioned and documented
+after being used by its author.
+
+## Sometime in 2007
+
+[MKNest](http://code.dyne.org/dynebolic/tree/dyneII/startup/bin/mknest)
+was refactored to work on the Debian distribution and since
+then renamed to Tomb. [dyne:bolic](http://www.dynebolic.org) specific dependencies where
+removed, keeping Zsh as the shell script it is written with.
+
+## Back in 2005
+
+The "nesting" feature of [dyne:bolic](http://www.dynebolic.org)
+GNU/Linux lets users encrypt their home in a file, using a shell script and a graphical
+interface called Taschino.
+
+Taschino included a shell script wrapping cryptsetup to encrypt
+loopback mounted partitions with the algo AES-256 (cbc-essiv
+mode): this script was called 'mkNest' and its the ancestor of
+Tomb.
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,65 @@
+
+# TOMB INSTALLATION INSTRUCTIONS
+
+## Install required tools
+
+Tomb needs a few programs to be installed on a system in order to work:
+
+ * zsh
+ * gnupg
+ * cryptsetup
+ * pinentry-curses (or -gtk or -qt as you prefer)
+
+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'
+
+## Install Tomb
+
+To install Tomb simply download the source distribution (the tar.gz file)
+and decompress it. From a terminal:
+
+ cd Downloads
+ tar xvfz Tomb-1.5.3.tar.gz (correct with actual file name)
+
+Then enter its directory and run 'make install' as root, this will install
+Tomb into /usr/local:
+
+ cd Tomb-1.5.3 (correct with actual directory name)
+ sudo make install
+
+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:
+
+ tomb dig -s 1000 secrets.tomb (be patient and wait a bit)
+ tomb forge -k secrets.tomb.key (be patient and follow instructions)
+ tomb lock -k secrets.tomb.key secrets.tomb
+
+## Install optional tools
+
+Tomb can use some optional tools to extend its functionalities:
+
+executable | function
+---------- | ---------------------------------------------------
+ dcfldd | show progress while executing long operations
+ steghide | bury and exhume keys inside images
+ resizefs | extend the size of existing tomb volumes
+ qrencode | engrave keys into printable qrcode tags
+ mlocate | have fast search of file names inside tombs
+ swish++ | have fast search of file contents inside tombs
+ unoconv | have fast search of contents in PDF and DOC files
+
+As for requirements, also optional tools may be easy to install using
+the packages provided by each distribution.
+
+Once any of the above is installed Tomb will find the tool automatically.
+
+## Install Tomb extras
+
+Tomb comes with a bunch of extra tools that contribute to enhance its
+functionality or integrate it into particular system environments.
+
diff --git a/KNOWN_BUGS b/KNOWN_BUGS.md
diff --git a/README b/README
@@ -1,96 +0,0 @@
-
- ..... ..
- .H8888888h. ~-. . uW8"
- 888888888888x `> u. .. . : `t888
-X~ `?888888hx~ ...ue888b .888: x888 x888. 8888 .
-' x8.^"*88*" 888R Y888r ~`8888~'888X`?888f` 9888.z88N
- `-:- X8888x 888R I888> X888 888X '888> 9888 888E
- 488888> 888R I888> X888 888X '888> 9888 888E
- .. `"88* 888R I888> X888 888X '888> 9888 888E
- x88888nX" . u8888cJ888 X888 888X '888> 9888 888E
- !"*8888888n.. : "*888*P" "*88%""*88" '888!` .8888 888"
-' "*88888888* 'Y" `~ " `"` `%888*%"
- ^"***"` "`
-
-A minimalistic commandline tool to manage encrypted volumes v1.5.2
-
- http://dyne.org/software/tomb
-
-
-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 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). Tomb can also produce machine parsable
-output to facilitate its use inside graphical applications.
-
-** How does it works
-
-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.
-
-** How secure is this?
-
-Death is the only sure thing in life. Said that, Tomb is a pretty
-secure tool especially because it keeps minimal, its source is always
-open and its code is easy to review with a bit of shell script
-knowledge.
-
-All encryption tools being used in Tomb are included as default in
-many GNU/Linux operating systems and therefore are regularly peer
-reviewed: we don't add anything else to them really, just a layer of
-usability.
-
-The code of Tomb can be read in a literate programming style on
-http://tomb.dyne.org/literate
-
-** 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, a system implemented already in
-2001. Since then, the same shell routines kept being maintained and in
-2007 they were adapted to work on various other GNU/Linux distributions.
-
-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
-
-Donations are always welcome, see https://dyne.org/donate
-
-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.
-
-For the bleeding edge visit https://github.com/dyne/Tomb
-
-Tomb's developers can be contacted via the "crypto" mailinglist on
-http://lists.dyne.org or via IRC on https://irc.dyne.org channel #dyne
-
-Some enthusiastic ideas are in the TODO file.
-
-Information on developers involved is found in the AUTHORS file.
-
diff --git a/README.md b/README.md
@@ -0,0 +1,101 @@
+
+ ..... ..
+ .H8888888h. ~-. . uW8"
+ 888888888888x `> u. .. . : `t888
+ X~ `?888888hx~ ...ue888b .888: x888 x888. 8888 .
+ ' x8.^"*88*" 888R Y888r ~`8888~'888X`?888f` 9888.z88N
+ `-:- X8888x 888R I888> X888 888X '888> 9888 888E
+ 488888> 888R I888> X888 888X '888> 9888 888E
+ .. `"88* 888R I888> X888 888X '888> 9888 888E
+ x88888nX" . u8888cJ888 X888 888X '888> 9888 888E
+ !"*8888888n.. : "*888*P" "*88%""*88" '888!` .8888 888"
+ ' "*88888888* 'Y" `~ " `"` `%888*%"
+ ^"***"` "`
+
+*A minimalistic commandline tool to manage encrypted volumes*
+
+Latest version: **1.5.3**
+
+http://dyne.org/software/tomb
+
+# What is Tomb, the crypto undertaker
+
+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 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). Tomb can also produce machine parsable
+output to facilitate its use inside graphical applications.
+
+# How does it works
+
+For the instructions on how to get started using Tomb, see [INSTALL](INSTALL.md).
+
+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.
+
+# How secure is this?
+
+Death is the only sure thing in life. Said that, Tomb is a pretty
+secure tool especially because it keeps minimal, its source is always
+open and its code is easy to review with a bit of shell script
+knowledge.
+
+All encryption tools being used in Tomb are included as default in
+many GNU/Linux operating systems and therefore are regularly peer
+reviewed: we don't add anything else to them really, just a layer of
+usability.
+
+The code of Tomb can be read in a literate programming style on
+http://tomb.dyne.org/literate
+
+# 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, a system implemented already in
+2001. Since then, the same shell routines kept being maintained and in
+2007 they were adapted to work on various other GNU/Linux distributions.
+
+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 AES-256
+(XTS plain) encryption algorithm.
+
+# How can you help
+
+Donations are always welcome, see https://dyne.org/donate
+
+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.
+
+For the bleeding edge visit https://github.com/dyne/Tomb
+
+Tomb's developers can be contacted via the "crypto" mailinglist on
+http://lists.dyne.org or via 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.
+
diff --git a/doc/TODO.org b/doc/TODO.org
@@ -7,6 +7,47 @@ Issue tracking is now handled via GitHub, see http://github.com/dyne/Tomb
Old roadmap notes:
+
+
+* TODO Release 2.0 :00%:
+
+Must be 100% backward compatible with tombs created with 1.0
+
+
+** New features
+*** [#A] support for ZFS filesystem (revisioning, bitrot)
+*** [#A] support for partition-based tombs
+*** [#B] system to split keys in parts (ssss)
+*** [#A] udev rules to avoid usb automount of keyplug in gnome
+*** [#B] sign and verify tomb script integrity (executed as root)
+*** TODO [#B] Internationalization using gettext :jaromil:
+
+ Started generating the strings, still need to figure out how to
+ install it
+
+*** [#B] make a gnome tomb undertaker using gnome-druid in glade
+*** DONE [#B] tomb locksmith for key management
+ a graphical tool or text wizard to move keys in/out steganography
+ as well split them
+
+*** DONE [#B] transport keys and integrity checksums on qrcodes
+*** [#B] analyse and show tomb entropy using libdisorder
+*** [#B] indeep security analysis of possible vulnerabilities
+*** [#C] use inotify on tomb
+
+ inotify can also count when was the last time tomb was used and
+ unmount it automatically after a timeout, see how much free space
+ is left and warn when the space is almost finished
+*** [#C] more gtk dialogs for configurations? keep it minimal!
+
+
+* Notes from #CybRes
+
+*** mlocall per swap )vecna) rompigli il caz su github
+*** steganografia migliore con outguess? (vecna)
+*** velocita' creazione : fallocate -l 10G (scuall8907@gm)
+
+
* DONE Release 1.0 :100%:
** TODO [#C] make one single status handle more tombs
@@ -56,41 +97,6 @@ Old roadmap notes:
** DONE [#A] Should refuse opening a tomb that is already open :jaromil:
-
-* TODO Release 2.0 :00%:
-
-Must be 100% backward compatible with tombs created with 1.0
-
-** New features
-
-*** [#A] system to split keys in parts (ssss)
-*** [#A] use inotify on tomb
-
- inotify can also count when was the last time tomb was used and
- unmount it automatically after a timeout, see how much free space
- is left and warn when the space is almost finished
-
-*** [#A] udev rules to avoid usb automount of keyplug in gnome
-
-*** [#A] sign and verify tomb script integrity (executed as root)
-*** TODO [#B] Internationalization using gettext :jaromil:
-
- Started generating the strings, still need to figure out how to
- install it
-
-*** [#B] make a gnome tomb undertaker using gnome-druid in glade
-*** [#B] tomb locksmith for key management
- a graphical tool or text wizard to move keys in/out steganography
- as well split them
-
-*** [#B] transport keys and integrity checksums on qrcodes
-
-*** [#B] analyse and show tomb entropy using libdisorder
-
-*** [#B] indeep security analysis of possible vulnerabilities
-*** [#C] more gtk dialogs for configurations? keep it minimal!
-
-
* TODO Porting to Win$loth
using FReeOTFE http://www.freeotfe.org
