ttomb.1 - tomb - the crypto undertaker
(HTM) git clone git://parazyd.org/tomb.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
ttomb.1 (19383B)
---
1 .TH tomb 1 "April 16, 2017" "tomb"
2
3 .SH NAME
4 Tomb \- the Crypto Undertaker
5
6 .SH SYNOPSIS
7 .B
8 .IP "tomb [options] command [arguments]"
9
10 .SH DESCRIPTION
11
12 Tomb is an application to manage the creation and access of encrypted
13 storage files: it can be operated from commandline and it can
14 integrate with a user's graphical desktop.
15
16 Tomb generates encrypted storage files to be opened and closed using
17 their associated keys, which are also protected with a password chosen
18 by the user. To create, open and close tombs a user will need super
19 user rights to execute the tomb commandline utility.
20
21 A tomb is like a locked folder that can be safely transported and
22 hidden in a filesystem; it encourages users to keep their keys
23 separate from tombs, for instance keeping a tomb file on your computer
24 harddisk and its key file on a USB stick.
25
26
27 .SH COMMANDS
28
29 .B
30 .IP "dig"
31 Generates a file that can be used as a tomb and will occupy as much
32 space as its desired initial size, the unlocked \fI.tomb\fR file can
33 then be locked using a \fIkey\fR. It takes a mandatory \fI-s\fR option
34 which is the size in megabytes (MiB). Tombs are digged using random
35 data gathered from a non-blocking source (/dev/urandom).
36
37 .B
38 .IP "forge"
39 Creates a new \fIkey\fR and prompts the user for a \fIpassword\fR to
40 protect its usage using symmetric encryption. This operation uses
41 random data from a blocking source (/dev/random) and it may take long
42 when run on a server with low entropy; to switch using a non-blocking
43 source the \fI--use-urandom\fR flag can be used. The \fI-g\fR option
44 switches on the use of a GPG key instead of a password (asymmetric
45 encryption), then the \fI-r\fR option indicates the recipient key;
46 more recipient GPG ids can be indicated (comma separated). The default
47 cipher to protect the key is AES256, a custom one can be specified
48 using the \fI-o\fR option, for a list of supported ciphers use
49 \fI-v\fR. For additional protection against dictionary attacks on
50 keys, the \fI--kdf\fR option can be used when forging a key, making
51 sure that the \fItomb-kdb-pbkdf2\fR binaries in \fIextras/kdf\fR were
52 compiled and installed on the system.
53
54 .B
55 .IP "lock"
56 Initializes and locks an empty tomb (made with \fIdig\fR) using a key
57 (made with \fIforge\fR), making it ready for usage. After this
58 operation, the tomb can only be opened in possession of the key and
59 knowing its password. As in any other command requiring a key, the
60 option \fI-k\fR should be used to specify a key file; in case of
61 encryption to GPG recipients the \fI-g\fR flag should be used followed
62 by \fI-r\fR and the recipient's secret GPG key id. The \fI-o\fR
63 option can be used to specify the cipher specification: default is
64 "aes-xts-plain64:sha256", old versions of Tomb used
65 "aes-cbc-essiv:sha256". If you are looking for something exotic, also
66 try "serpent-xts-plain64". More options may be found in cryptsetup(8)
67 and Linux documentation. This operation requires root privileges to
68 loopback mount, format the tomb (using LUKS and Ext4), then set the
69 key in its first LUKS slot.
70
71 .B
72 .IP "open"
73 Opens an existing \fItomb file\fR (first argument) using a key
74 (\fI-k\fR) which can also be an \fIjpeg image\fR (see
75 \fIbury\fR/\fIexhume\fR). If a second argument is given it will
76 indicate the \fImountpoint\fR where the tomb should be made
77 accessible, else the tomb is mounted in a directory inside /media (if
78 not available it uses /run/media/$USER). The option \fI-o\fR can be
79 used to pass mount(8) options (default: rw,noatime,nodev). The
80 \fI-g\fR option is needed when using GPG encryption to recipients.
81
82 .B
83 .IP "list"
84 List all the tombs found open, including information about the time
85 they were opened and the hooks that they mounted. If the first
86 argument is present, then shows only the tomb named that way or
87 returns an error if it's not found. If the option
88 \fI--get-mountpoint\fR is used then print a simple list of currently
89 open tomb mountpoint paths.
90
91 .B
92 .IP "index"
93 Creates or updates the search indexes of all tombs currently open:
94 enables use of the \fIsearch\fR command using simple word patterns on
95 file names. Indexes are created using mlocate's updatedb(8) and
96 swish-e(1) if they are found on the system. Indexes allow to search
97 very fast for filenames and contents inside a tomb, they are stored
98 inside it and are not accessible if the Tomb is closed. To avoid
99 indexing a specific tomb simply touch a \fI.noindex\fR file in it.
100
101 .B
102 .IP "search"
103 Takes any string as argument and searches for them through all tombs
104 currently open and previously indexed using the \fIindex\fR command.
105 The search matches filenames if mlocate is installed and then also
106 file contents if swish++ is present on the system, results are listed
107 on the console.
108
109 .B
110 .IP "close"
111 Closes a currently open tomb. If more tombs are open, the first
112 argument should be used to specify the name of the tomb to be closed,
113 or \fIall\fR to close all currently open tombs. This command fails if
114 the tomb is in use by running processes (to force close, see
115 \fIslam\fR below).
116
117 .B
118 .IP "slam"
119 Closes a tomb like the command \fIclose\fR does, but it doesn't fail
120 even if the tomb is in use by other application processes: it looks
121 for and closes each of them (in order: TERM, HUP, KILL). This command may
122 provoke unsaved data loss, but assists users to face surprise
123 situations. It requires \fIlsof\fR else it falls back to \fIclose\fR.
124
125
126 .B
127 .IP "passwd"
128 Changes the password protecting a key file specified using
129 \fI-k\fR. With keys encrypted for GPG recipients use \fI-g\fR followed
130 by \fI-r\fR to indicate the new recipient key, or a comma separated
131 list.. The user will need to know the key's current password, or
132 possess at least one of the current recipients GPG secret keys,
133 because the key contents will be decoded and reencoded using the new
134 passwords or keys. If the key file is broken (missing headers) this
135 function also attempts its recovery.
136
137 .B
138 .IP "setkey"
139 Changes the key file that locks a tomb, substituting the old one with
140 a new one. Both the old and the new key files are needed for this
141 operation and their passwords or GPG recipient(s) secret keys must be
142 available. The new key must be specified using the \fI-k\fR option,
143 the first argument should be the old key and the second and last
144 argument the tomb file. Use the \fI-g\fR option to unlock the tomb
145 with a GPG key, the \fI-r\fR to indicate the recipient or a comma
146 separated list for more than one recipient.
147
148 .B
149 .IP "resize"
150 Increase the size of a tomb file to the amount specified by the
151 \fI-s\fR option, which is the new size in megabytes (MiB). Full access to the tomb using
152 a key (\fI-k\fR) and its password is required. Tombs can only grow and
153 can never be made smaller. This command makes use of the cryptsetup(8)
154 resize feature and the resize2fs command: its much more practical than
155 creating a new tomb and moving everything into it.
156
157 .B
158 .IP "engrave"
159 This command transforms a tomb key into an image that can be printed
160 on paper and physically stored as backup, i.e. hidden in a book. It
161 Renders a QRCode of the tomb key, still protected by its password: a
162 PNG image (extension \fI.qr.png\fR) will be created in the current
163 directory and can be later printed (fits an A4 or Letter format). To
164 recover an engraved key one can use any QRCode reader on a smartphone:
165 save it into a file and then use that file as a key (\fI-k\fR).
166
167 .B
168 .IP "bury"
169 Hides a tomb key (\fI-k\fR) inside a \fIjpeg image\fR (first argument)
170 using \fIsteganography\fR: the image will change in a way that cannot
171 be noticed by human eye and hardly detected by data analysis. This
172 option is useful to backup tomb keys in unsuspected places; it depends
173 from the availability of \fIsteghide\fR. Use the \fI-g\fR flag and
174 \fI-r\fR option followed by recipient id to use GPG asymmetric
175 encryption.
176
177 .B
178 .IP "exhume"
179 This command recovers from jpeg images the keys that were previously
180 hidden into them using \fIbury\fR. Exhume requires a key filename
181 (\fI-k\fR) and a \fIjpeg image\fR file (first argument) known to be
182 containing a key. If the right key password is given, the key will be
183 exhumed. If the password is not known, it is very hard to verify if a
184 key is buried in any image or not.
185
186 .SH OPTIONS
187 .B
188 .B
189 .IP "-k \fI<keyfile>\fR"
190 For all operations requiring a key, this option specifies the location
191 of the key file to use. Arguments can also be \fIjpeg image\fR files
192 where keys have been hidden using the \fIbury\fR command, or text
193 files retrieved from \fIengraved\fR QR codes. If the \fIkeyfile\fR
194 argument is "-" (dash), Tomb will read the key from stdin (blocking).
195 .B
196 .IP "-n"
197 Skip processing of post-hooks and bind-hooks if found inside the tomb.
198 See the \fIHOOKS\fR section in this manual for more information.
199 .B
200 .IP "-o"
201 Manually specify mount options to be used when opening a tomb instead
202 of the default \fIrw,noatime,nodev\fR, i.e. to mount a tomb read-only
203 (ro) to prevent any modification of its data. Can also be used to
204 change the symmetric encryption algorithm for keys during \fIforge\fR
205 operations (default \fIAES256\fR) or the LUKS encryption method during
206 \fIlock\fR operations (default \fIaes-xts-plain64:sha256\fR).
207 .B
208 .IP "-f"
209 Force flag, currently used to override swap checks, might be
210 overriding more wimpy behaviours in future, but make sure you know
211 what you are doing if you force an operation.
212 .B
213 .IP "-s \fI<MBytes>\fR"
214 When digging or resizing a tomb, this option must be used to specify
215 the \fIsize\fR of the new file to be created. Units are megabytes (MiB).
216 .B
217 .IP "-g"
218 Tell tomb to use a asymmetric GnuPG key encryption instead of a
219 symmetric passphrase to protect a tomb key. This option can be followed by \fI-r\fR when the command needs to specify recipient(s).
220 .B
221 .IP "-r \fI<gpg_id>[,<gpg_id2>]\fR"
222 Provide a new set of recipient(s) to encrypt a tomb key. \fIgpg_ids\fR
223 can be one or more GPG key ID, comma separated.
224 .B
225 .IP "--kdf \fI<itertime>\fR"
226 Activate the KDF feature against dictionary attacks when creating a
227 key: forces a delay of \fI<itertime>\fR times every time this key is
228 used. The actual time to wait depends on the CPU speed of the
229 computer where the key is used. Using 5 or 10 is a sane amount for
230 modern computers, the value is multiplied by 1 million.
231 .B
232 .IP "-h"
233 Display a help text and quit.
234 .B
235 .IP "-v"
236 Display version and quit.
237 .B
238 .IP "-q"
239 Run more quietly
240 .B
241 .IP "-D"
242 Print more information while running, for debugging purposes
243
244 .SH DEV MODE
245 .B
246 .IP "--no-color"
247 Suppress colors in console output (needed for string parsing by
248 wrappers).
249 .B
250 .IP "--unsafe"
251 Enable using dev-mode arguments, i.e. to pass passwords from
252 commandline options. This is mostly used needed for execution by
253 wrappers and testing suite.
254 .B
255 .IP "--use-urandom"
256 Use a non-blocking random source to improve the speed of the
257 \fIforge\fR command (key generation): tomb uses /dev/urandom instead
258 of /dev/random. According to some people using the non-blocking source
259 of Linux kernel doesn't degrades the quality of random.
260 .B
261 .IP "--tomb-pwd <string>"
262 Use string as password when needed on tomb.
263 .B
264 .IP "--tomb-old-pwd <string>"
265 Use string as old password when needed in tomb commands requiring
266 multiple keys, like \fIpasswd\fR or \fIsetkey\fR.
267 .B
268 .IP "-U"
269 Switch to this user ID when dropping privileges.
270 .B
271 .IP "-G"
272 Switch to this group ID when dropping privileges.
273 .B
274 .IP "-T"
275 Switch to this TTY terminal when dropping privileges.
276
277 .SH HOOKS
278
279 Hooks are special files that can be placed inside the tomb and trigger
280 actions when it is opened and closed; there are two kinds of such
281 files: \fIbind-hooks\fR and \fIpost-hooks\fR can be placed in the
282 base root of the tomb.
283
284 .B
285 .IP "bind-hooks"
286 This hook file consists of a simple two column list of files or
287 directories inside the tomb to be made directly accessible inside the
288 current user's home directory. Tomb will use the "mount \-o bind"
289 command to bind locations inside the tomb to locations found in $HOME
290 so in the first column are indicated paths relative to the tomb and in
291 the second column are indicated paths relative to $HOME contents, for
292 example:
293 .EX
294 mail mail
295 .gnupg .gnupg
296 .fmrc .fetchmailrc
297 .mozilla .mozilla
298 .EE
299
300 .B
301 .IP "exec-hooks"
302 This hook file gets executed as user by tomb with the first argument
303 determining the step of execution: "open" or "close". The exec-hooks
304 file should be an executable (ELF or shell script) present inside the
305 Tomb. Tomb executes this hook as user supplying two or more arguments,
306 the first being the step, followed by the mountpoint of the tomb and,
307 on close events, its name, loopback device and dev-mapper device
308 paths.
309
310 .SH PRIVILEGE ESCALATION
311
312 The tomb commandline tool needs to acquire super user rights to
313 execute most of its operations: to do so it uses sudo(8), while
314 pinentry(1) is adopted to collect passwords from the user. Tomb
315 executes as super user only when required.
316
317 To be made available on multi user systems, the superuser execution of
318 the tomb script can be authorized for users without jeopardizing the
319 whole system's security: just add such a line to \fI/etc/sudoers\fR:
320
321 .EX
322 username ALL=NOPASSWD: /usr/local/bin/tomb
323 .EE
324
325 Password input is handled by the pinentry program: it can be text
326 based or graphical and is usually configured with a symlink. When
327 using Tomb in X11 it is better to use a graphical pinentry-gtk2 or
328 pinentry-qt because it helps preventing keylogging by other X
329 clients. When using it from a remote ssh connection it might be
330 necessary to force use of pinentry-curses for instance by unsetting
331 the DISPLAY environment var.
332
333
334 .SH SWAP
335
336 On execution of certain commands Tomb will complain about swap memory
337 on disk when present and \fIabort if your system has swap
338 activated\fR. You can disable this behaviour using the
339 \fI--force\fR. Before doing that, however, you may be interested in
340 knowing the risks of doing so:
341 .IP \(bu
342 During such operations a lack of available memory could cause the swap
343 to write your secret key on the disk.
344 .IP \(bu
345 Even while using an opened tomb, another application could occupy too
346 much memory so that the swap needs to be used, this way it is possible
347 that some contents of files contained into the tomb are physically
348 written on your disk, not encrypted.
349 .P
350
351 If you don't need swap, execute \fI swapoff -a\fR. If you really need
352 it, you could make an encrypted swap partition. Tomb doesn't detect if
353 your swap is encrypted, and will complain anyway.
354
355 .SH DENIABILITY
356
357 The possibility to have an encrypted volume which is invisible and
358 cannot be detected is called "deniability". The cryptographic layer of
359 the device mapper in Linux (dm-crypt) does not implement
360 deniability. Tomb is just a wrapper on top of that and it doesn't add
361 cryptographic deniability. However a certain way of using tomb can
362 facilitate a weak sort of deniability outside of the scenario of
363 seized devices and forensic analysis of files and blocks on disc.
364
365 For instance to eliminate any trace of tomb usage from the shell
366 history ZSh users can activate the "HISTIGNORESPACE" feature and
367 prefix all invokations of tomb with a blank space, including two lines
368 in ".zshrc":
369
370 .EX
371 export HISTIGNORESPACE=1
372 alias tomb=' tomb'
373 .EE
374
375 .SH PASSWORD INPUT
376
377 Tomb uses the external program "pinentry" to let users type the key password into a terminal or a graphical window. This program works in conjunction with "gpg-agent", a daemon running in background to facilitate secret key management with gpg. It is recommended one runs "gpg-agent" launching it from the X session initialization ("~/.xsession" or "~/.xinitrc" files) with this command:
378
379 .EX
380 eval $(gpg-agent --daemon --write-env-file "${HOME}/.gpg-agent-info")
381 .EE
382
383 In the future it may become mandatory to run gpg-agent when using tomb.
384
385 .SH SHARE A TOMB
386 A tomb key can be encrypted with more than one recipient. Therefore, a
387 tomb can be shared between different users. The recipients are given
388 using the \fI-r\fR (or/and \fI-R\fR) option and if multiple each GPG
389 key ID must be separated by a comma (\fI,\fR). Sharing a tomb is a
390 very sensitive action and the user needs to trust that all the GPG
391 public keys used are kept safe. If one of them its stolen or lost, it
392 will be always possible to use it to access the tomb key unless all
393 its copies are destroyed. The \fI-r\fR option can be used in the tomb
394 commands: \fIopen\fR, \fIforge\fR \fIsetkey\fR, \fIpasswd\fR,
395 \fIbury\fR, \fIexhume\fR and \fIresize\fR.
396
397 .SH EXAMPLES
398
399 .IP \(bu
400 Create a 128MB large "secret" tomb and its keys, then open it:
401
402 .EX
403 tomb dig -s 128 secret.tomb
404
405 tomb forge secret.tomb.key
406
407 tomb lock secret.tomb -k secret.tomb.key
408
409 tomb open secret.tomb -k secret.tomb.key
410 .EE
411
412 .IP \(bu
413 Open a Tomb using the key from a remote SSH shell, without saving any
414 local copy of it:
415
416 .EX
417 ssh user@my.shell.net 'cat .secrets/tomb.key' | tomb open secret.tomb -k -
418 .EE
419
420 .IP \(bu
421 Open a Tomb on a remote server passing the unencrypted local key on stdin via SSH,
422 without saving any remote copy of it:
423
424 .EX
425 gpg -d .secrets/tomb.key | ssh server tomb open secret.tomb -k cleartext --unsafe
426 .EE
427
428 .IP \(bu
429 Create a bind hook that places your GnuPG folder inside the tomb, but
430 makes it reachable from the standard $HOME/.gnupg location every time
431 the tomb will be opened:
432
433 .EX
434 tomb open GPG.tomb -k GPG.tomb.key
435 echo ".gnupg .gnupg" > /media/GPG.tomb/bind-hooks
436 mv ~/.gnupg /media/GPG.tomb/.gnupg && mkdir ~/.gnupg
437 tomb close GPG && tomb open GPG.tomb -k GPG.tomb.key
438 .EE
439
440 .IP \(bu
441 Script a tomb to launch the Firefox browser every time is opened,
442 keeping all its profile data inside it:
443
444 .EX
445 tomb open FOX.tomb -k FOX.tomb.key
446 cat <<EOF > /media/FOX.tomb/post-hooks
447 #!/bin/sh
448 if [ "$1" = "open" ]; then
449 firefox -no-remote -profile "$2"/firefox-pro &
450 fi
451 EOF
452 chmod +x /media/FOX.tomb/post-hooks
453 .EE
454
455 .IP \(bu
456 Script a tomb to archive Pictures using Shotwell, launching it on open:
457
458 .EX
459 tomb open Pictures.tomb -k Pictures.tomb.key
460 cat <<EOF > /media/Pictures.tomb/bind-hooks
461 Pictures Pictures
462 EOF
463 cat <<EOF > /media/Pictures.tomb/post-hooks
464 #!/bin/sh
465 if [ "$1" = "open" ]; then
466 which shotwell > /dev/null
467 if [ "$?" = "0" ]; then
468 shotwell -d "$2"/Pictures/.shotwell &
469 fi
470 fi
471 EOF
472 chmod +x /media/Pictures.tomb/post-hooks
473 .EE
474
475 .SH BUGS
476 Please report bugs on the Github issue tracker at
477 .UR https://github.com/dyne/Tomb/issues
478 .UE
479
480 One can also try to get in touch with developers via the #dyne chat
481 channel on \fIhttps://irc.dyne.org\fR.
482
483 .SH COPYING
484
485 This manual is Copyright (c) 2011-2017 by Denis Roio <\fIjaromil@dyne.org\fR>
486
487 This manual includes contributions by Boyska and Hellekin O. Wolf.
488
489 Permission is granted to copy, distribute and/or modify this manual
490 under the terms of the GNU Free Documentation License, Version 1.1 or
491 any later version published by the Free Software Foundation.
492 Permission is granted to make and distribute verbatim copies of this
493 manual page provided the above copyright notice and this permission
494 notice are preserved on all copies.
495
496 .SH AVAILABILITY
497
498 The most recent version of Tomb sourcecode and up to date
499 documentation is available for download from its website on
500 \fIhttps://tomb.dyne.org\fR.
501
502 .SH SEE ALSO
503
504 .B
505 .IP cryptsetup(8)
506 .B
507 .IP pinentry(1)
508 .B
509 .IP gpg-agent(1)
510
511 GnuPG website: https://www.gnupg.org
512
513 DM-Crypt website: https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt
514
515 LUKS website: https://gitlab.com/cryptsetup/cryptsetup/wikis/home