tINSTALL.md - tomb - the crypto undertaker
(HTM) git clone git://parazyd.org/tomb.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tINSTALL.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! ;^)