tdocumentation update - tomb - the crypto undertaker (HTM) git clone git://parazyd.org/tomb.git (DIR) Log (DIR) Files (DIR) Refs (DIR) README (DIR) LICENSE --- (DIR) commit 22db5f7201b644fac298dc0aecfb0510ceb6ad11 (DIR) parent cf66907fa2c891e71661970e0c1c198afab14227 (HTM) 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(-) --- (DIR) diff --git a/AUTHORS b/AUTHORS.md (DIR) diff --git a/ChangeLog b/ChangeLog t@@ -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. (DIR) diff --git a/ChangeLog.md b/ChangeLog.md t@@ -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. (DIR) diff --git a/INSTALL.md b/INSTALL.md t@@ -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. + (DIR) diff --git a/KNOWN_BUGS b/KNOWN_BUGS.md (DIR) diff --git a/README b/README t@@ -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. - (DIR) diff --git a/README.md b/README.md t@@ -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. + (DIR) diff --git a/doc/TODO.org b/doc/TODO.org t@@ -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 t@@ -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