INSTALL.md (7394B)
1 # TOMB INSTALLATION INSTRUCTIONS 2 3 ## Install required tools 4 5 Tomb needs a few programs to be installed on a system in order to work: 6 7 * zsh 8 * sudo 9 * gnupg 10 * cryptsetup 11 * pinentry-curses (and/or -gtk-2, -x11, -qt) 12 13 Most systems provide these tools in their package collection, for 14 instance on Debian/Ubuntu one can use `apt-get install` on Fedora and 15 CentOS one can use `yum install` and `pacman` on Arch. 16 17 ## Install Tomb 18 19 To install Tomb simply download the source distribution (the tar.gz file) 20 from https://files.dyne.org/tomb and decompress it. From a terminal: 21 22 cd Downloads 23 tar xvfz Tomb-2.4.tar.gz (correct with actual file name) 24 25 Then enter its directory and run 'make install' as root, this will install 26 Tomb into /usr/local: 27 28 cd Tomb-2.4 (correct with actual directory name) 29 sudo make install 30 31 After installation one can read the commandline help or read the manual: 32 33 tomb -h (print a short help on the commandline) 34 man tomb (show the full usage manual) 35 36 # Basic usage 37 38 Once installed one can proceed creating a tomb, for instance: 39 40 tomb dig -s 10 secrets.tomb (dig a 10MB Tomb) 41 tomb forge -k secrets.tomb.key (create a new key and set its password) 42 tomb lock -k secrets.tomb.key secrets.tomb (format the tomb, lock it with key) 43 44 When this is done, the tomb can be opened with: 45 46 tomb open -k secrets.tomb.key secrets.tomb (will ask for password) 47 48 The key can also be hidden in an image, to be used as key later 49 50 tomb bury -k secrets.tomb.key nosferatu.jpg (hide the key in a jpeg image) 51 tomb open -k nosferatu.jpg secrets.tomb (use the jpeg image to open the tomb) 52 53 Or backupped to a QRCode that can be printed on paper and hidden in 54 books. QRCodes can be scanned with any mobile application, resulting 55 into a block of text that can be used with `-k` just as a normal key. 56 57 tomb engrave -k secrets.tomb.key (also an image will work) 58 59 There are some more things that tomb can do for you, make sure you 60 have a look at the manpage and at the commandline help to find out 61 more. 62 63 # Optional tools 64 65 Tomb can use some optional tools to extend its functionalities: 66 67 executable | function 68 ---------- | --------------------------------------------------- 69 lsof | slam a tomb (close even if open programs) 70 dcfldd | show progress while digging tombs and keys 71 steghide | bury and exhume keys inside images 72 resizefs | extend the size of existing tomb volumes 73 qrencode | engrave keys into printable qrcode sheets 74 mlocate | fast search of file names inside tombs 75 swish++ | fast search of file contents inside tombs 76 unoconv | fast search of contents in PDF and DOC files 77 lesspipe | fast search of contents in compressed archives 78 haveged | fast entropy generation for key forging 79 80 As for requirements, also optional tools may be easy to install using 81 the packages provided by each distribution. 82 83 Once any of the above is installed Tomb will find the tool automatically. 84 85 # Extras 86 87 Tomb comes with a bunch of extra tools that contribute to enhance its 88 functionality or integrate it into particular system environments. 89 90 ## extras/gtk-tray 91 92 The Gtk tray adds a nifty tomb skull into the desktop toolbar: one can 93 use it to close, slam and explore the open tomb represented by it. 94 95 When using pinentry-gtk-2 it also adds a little skull on the password 96 input, useful to not confuse it with other password inputs. 97 98 To have it change directory `extras/gtk-tray` then 99 100 1. make sure libnotify and gtk+-2.0 dev packages are available 101 2. run `make` inside the directory to build `tomb-gtk-tray` 102 3. run `sudo make install` (default PREFIX is `/usr/local`) 103 4. start `tomb-gtk-tray tombname` after the tomb is open 104 105 Of cource one can include the launch of tomb-gtk-tray scripts. 106 107 ## extras/qt-tray 108 109 The QT tray adds a tomb tray in a QT desktop toolbar. It requires at 110 least QT libraries of version 5.4 or above. 111 Build with 'qmake' and then 'make'. 112 113 ## extras/kdf-keys 114 115 The KDF wrapper programs allows one to use KDF rounds on passwords in 116 order to obstruct dictionary based and similar brute-forcing attacks. 117 118 In case an attacker comes in possession of both a tomb and its key, 119 the easy to memorize password can be guessed by rapidly trying 120 different combinations. With KDF every try will require a significant 121 amount of computation that will slow down the process avoiding tight 122 loops and in fact making such attacks very onerous and almost 123 impossible. 124 125 To have it enter `extras/kdf-keys` then 126 127 1. make sure libgcrypt dev packages are available 128 2. run `make` inside the directory to build tomb-kdb-* executables 129 3. run `sudo make install` (default PREFIX is `/usr/local`) 130 4. use `--kdf 100` when forging a key (tune the number to your cpu) 131 132 KDF keys are recognized automatically by Tomb, which will always need 133 the `extras/kdf-keys` program to be installed on a machine in order to 134 open the Tomb. 135 136 Please note that it doesn't makes much sense to use KDF keys and 137 steganography, since the latter will invalidate the brute-forcing 138 protection. For details on the issue see [KNOWN_BUGS.md](KNOWN_BUGS). 139 140 ## extras/translations/ 141 142 There are translations available for Tomb and they are installed by 143 default. If you wish to update them manually navigate to extras/po 144 and run 'make install' as root: 145 146 cd extras/translations 147 sudo make install 148 149 ## extras/gtomb/ 150 151 This is a minimalistic graphical user interface scripted in ZSh 152 depending from Zenity to display dialog boxes. It covers all basic 153 operations in Tomb and facilitates the setup of hooks. 154 155 cd extras/gtomb 156 ./gtomb 157 158 # Tomb support in other applications 159 160 Can Tomb be used by other applications? 161 162 Sure as Hell it can! Licensing issues aside ([GNU GPLv3+](COPYING) 163 terms) Tomb provides machine-readable output and interaction via some 164 flags: 165 166 flag | function 167 --------------- | ------------------------------------------------ 168 --no-color | avoids coloring output to allow parsing 169 --unsafe | allows passwords options and cleartext key from stdin 170 --tomb-pwd | specify the key password as argument 171 --tomb-old-pwd | specify the old key password as argument 172 -k cleartext | reads the unencrypted key from stdin 173 174 Yet please consider that these flags may introduce vulnerabilities and 175 other people logged on the same system can easily log your passwords 176 while such commands are executing. 177 We only recommend using the pinentry to input your passwords. 178 179 At the time of writing another free software graphical application 180 supports opening and closing Tombs via a plugin installed by 181 default: [zuluCrypt](https://mhogomchungu.github.io/zuluCrypt/). One 182 needs to activate the Tomb plugin included in the zuluCrypt source to 183 be able to create, open and close tombs. Beware zuluCrypt may miss 184 advanced Tomb functionalities that are only available from the 185 command-line. 186 187 ## Python 188 189  190 191 A Python wrapper is under development and already usable, but it 192 introduces some vulnerabilities mentioned above. Find it in 193 `extras/tomber`. For more information see [PYTHON](extras/PYTHON.md). 194 195 ## Let us know! 196 197 If you plan to develop any kind of wrapper for Tomb you are welcome to 198 let us know. Tomb is really meant to be maintained as a minimal tool 199 for long-term compatibility when handling something so delicate as our 200 secrets. For anything else we rely on your own initiative. 201 202 Happy hacking! ;^)