tREADME.md - tomb - the crypto undertaker (HTM) git clone git://parazyd.org/tomb.git (DIR) Log (DIR) Files (DIR) Refs (DIR) README (DIR) LICENSE --- tREADME.md (12414B) --- 1 ..... .. 2 .H8888888h. ~-. . uW8" 3 888888888888x `> u. .. . : `t888 4 X~ `?888888hx~ ...ue888b .888: x888 x888. 8888 . 5 ' x8.^"*88*" 888R Y888r ~`8888~'888X`?888f` 9888.z88N 6 `-:- X8888x 888R I888> X888 888X '888> 9888 888E 7 488888> 888R I888> X888 888X '888> 9888 888E 8 .. `"88* 888R I888> X888 888X '888> 9888 888E 9 x88888nX" . u8888cJ888 X888 888X '888> 9888 888E 10 !"*8888888n.. : "*888*P" "*88%""*88" '888!` .8888 888" 11 ' "*88888888* 'Y" `~ " `"` `%888*%" 12 ^"***"` "` 13 14 *A minimalistic commandline tool to manage encrypted volumes* aka **The Crypto Undertaker** 15 16 [![software by Dyne.org](https://www.dyne.org/wp-content/uploads/2015/12/software_by_dyne.png)](http://www.dyne.org) 17 18 More information and updates on website: https://www.dyne.org/software/tomb 19 20 Get the stable .tar.gz signed release for production use! 21 22 Download it from https://files.dyne.org/tomb 23 24 ![tomb's logo](https://github.com/dyne/Tomb/blob/master/extras/images/monmort.png) 25 26 [![Build Status](https://travis-ci.org/dyne/Tomb.svg?branch=master)](https://travis-ci.org/dyne/Tomb) 27 28 # What is Tomb, the crypto undertaker? 29 30 Tomb aims to be a free and open source system for easy encryption and 31 backup of personal files, written in code that is easy to review and 32 links shared GNU/Linux components. 33 34 At present, Tomb consists of a simple shell script (Zsh) using 35 standard filesystem tools (GNU) and the cryptographic API of the Linux 36 kernel (cryptsetup and LUKS). Tomb can also produce machine parsable 37 output to facilitate its use inside graphical applications. 38 39 # How does it work? 40 41 To create a Tomb, do: 42 ``` 43 $ tomb dig -s 100 secret.tomb 44 $ tomb forge secret.tomb.key 45 $ tomb lock secret.tomb -k secret.tomb.key 46 ``` 47 To open it, do 48 ``` 49 $ tomb open secret.tomb -k secret.tomb.key 50 ``` 51 and after you are done 52 ``` 53 $ tomb close 54 ``` 55 or if you are in a hurry 56 ``` 57 $ tomb slam all 58 ``` 59 60 For the instructions on how to get started using Tomb, see [INSTALL](INSTALL.md). 61 62 ``` 63 Syntax: tomb [options] command [arguments] 64 65 Commands: 66 67 // Creation: 68 dig create a new empty TOMB file of size -s in MiB 69 forge create a new KEY file and set its password 70 lock installs a lock on a TOMB to use it with KEY 71 72 // Operations on tombs: 73 open open an existing TOMB (-k KEY file or - for stdin) 74 index update the search indexes of tombs 75 search looks for filenames matching text patterns 76 list list of open TOMBs and information on them 77 close close a specific TOMB (or 'all') 78 slam slam a TOMB killing all programs using it 79 resize resize a TOMB to a new size -s (can only grow) 80 81 // Operations on keys: 82 passwd change the password of a KEY (needs old pass) 83 setkey change the KEY locking a TOMB (needs old key and pass) 84 85 // Backup on paper: 86 engrave makes a QR code of a KEY to be saved on paper 87 88 // Steganography: 89 bury hide a KEY inside a JPEG image (for use with -k) 90 exhume extract a KEY from a JPEG image (prints to stdout) 91 92 Options: 93 94 -s size of the tomb file when creating/resizing one (in MiB) 95 -k path to the key to be used ('-k -' to read from stdin) 96 -n don't process the hooks found in tomb 97 -o options passed to commands: open, lock, forge (see man) 98 -f force operation (i.e. even if swap is active) 99 -g use a GnuPG key to encrypt a tomb key 100 -r provide GnuPG recipients (separated by coma) 101 -R provide GnuPG hidden recipients (separated by coma) 102 --kdf forge keys armored against dictionary attacks 103 104 -h print this help 105 -v print version, license and list of available ciphers 106 -q run quietly without printing informations 107 -D print debugging information at runtime 108 ``` 109 110 # What is this for, exactly? 111 112 This tool can be used to dig .tomb files (LUKS volumes), forge keys 113 protected by a password (GnuPG symmetric encryption) and use the keys 114 to lock the tombs. Tombs are like single files whose contents are 115 inaccessible in the absence of the key they were locked with and its 116 password. 117 118 Once open, the tombs are just like normal folders and can contain 119 different files, plus they offer advanced functionalities like bind 120 and execution hooks and fast search, or they can be slammed close even 121 if busy. Keys can be stored on separate media like USB sticks, NFC, or 122 bluetooth devices to make the transport of data safer: one always 123 needs both the tomb and the key, plus its password, to access it. 124 125 The tomb script takes care of several details to improve user's 126 behaviour and the security of tombs in everyday usage: secures the 127 typing of passwords from keyloggers, facilitates hiding keys inside 128 images, indexes and search a tomb's contents, lists open tombs and 129 selectively closes them, warns the user about free space and last time 130 usage, etc. 131 132 # How secure is this? 133 134 Death is the only sure thing in life. That said, Tomb is a pretty 135 secure tool especially because it is kept minimal, its source is 136 always open to review (even when installed) and its code is easy to 137 read with a bit of shell script knowledge. 138 139 All encryption tools being used in Tomb are included as default in 140 many GNU/Linux operating systems and therefore are regularly peer 141 reviewed: we don't add anything else to them really, just a layer of 142 usability. 143 144 The file [KNOWN_BUGS.md](KNOWN_BUGS.md) contains some notes on known 145 vulnerabilities and threat model analysis. 146 147 In absence or malfunction of the Tomb script it is always possible to 148 access the contents of a Tomb only using a dm-crypt enabled Linux 149 kernel, cryptsetup, GnuPG and any shell interpreter issuing the 150 following commands as root: 151 ``` 152 lo=$(losetup -f) 153 losetup -f secret.tomb 154 pass="$(gpg -d secret.key)" 155 echo -n -e "$pass" | cryptsetup --key-file - luksOpen $lo secret 156 mount /dev/mapper/secret /mnt 157 unset pass 158 ``` 159 One can change the last argument `/mnt` to where the Tomb has to be 160 mounted and made accessible. To close the tomb then use: 161 ``` 162 umount /mnt 163 cryptsetup luksClose /dev/mapper/secret 164 ``` 165 166 # Stage of development 167 168 Tomb is an evolution of the 'mknest' tool developed for the 169 [dyne:bolic](http://www.dynebolic.org) 100% Free GNU/Linux 170 distribution in 2001: its 'nesting' mechanism allowed the liveCD users 171 to encrypt and make persistent home directories. Since then the same 172 shell routines kept being maintained and used for dyne:bolic until 173 2007, when they were ported to work on more GNU/Linux distributions. 174 175 As of today, Tomb is a very stable tool also used in mission critical 176 situations by a number of activists in dangerous zones. It has been 177 reviewed by forensics analysts and it can be considered to be safe for 178 military grade use where the integrity of information stored depends 179 on the user's behaviour and the strength of a standard AES-256 (XTS 180 plain) encryption algorithm. 181 182 ## Compatibility 183 184 Tomb can be used in conjunction with some other software applications, 185 some are developed by Dyne.org, but some also by third parties. 186 187 - [Secrets](https://secrets.dyne.org) is a software that can be operated on-line and on-site to split a Tomb key in shares to be distributed to peers: some of them have to agree to combine back the shares in order to retrieve the key. 188 189 - [zuluCrypt](https://mhogomchungu.github.io/zuluCrypt/) is a graphical application to manage various types of encrypted volumes on GNU/Linux, among them also Tombs, written in C++. 190 191 - [Mausoleum](https://github.com/mandeep/Mausoleum) is a graphical interface to facilitate the creation and management of tombs, written in Python. 192 193 194 - [pass-tomb](https://github.com/roddhjav/pass-tomb) is a console based wrapper of the excellent password keeping program [pass](https://www.passwordstore.org) that helps to keep the whole tree of password encrypted inside a tomb. It is written in Bash. 195 196 If you are writing a project supporting tomb volumes or wrapping tomb, let us know! 197 198 199 ## Compliancy 200 201 Tomb qualifies as sound for use on information rated as "top secret" when used on an underlying stack of carefully reviewed hardware (random number generator and other components) and software (Linux kernel build, crypto modules, device manager, compiler used to built, shell interpreter and packaged dependencies). 202 203 Tomb volumes are fully compliant with the FIPS 197 advanced encryption standard published by NIST and with the following industry standards: 204 205 - Information technology -- Security techniques -- Encryption algorithms 206 - [ISO/IEC 18033-1:2015](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=54530) -- Part 1: General 207 - [ISO/IEC 18033-3:2010](http://www.iso.org/iso/home/store/catalogue_ics/catalogue_detail_ics.htm?csnumber=54531) -- Part 3: Block ciphers 208 209 Tomb implementation is known to address at least partially issues raised in: 210 211 - Information technology -- Security techniques -- Key management 212 - [ISO/IEC 11770-1:2010](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=53456) -- Part 1: Framework 213 - [ISO/IEC 11770-2:2008](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=46370) -- Part 2: Mechanisms using symmetric techniques 214 - [ISO/IEC 27005:2011](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=56742) Information technology -- Security techniques -- Information security risk management 215 - [ISO/IEC 24759:2014](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=59142) Information technology -- Security techniques -- Test requirements for cryptographic modules 216 217 Any help on further verification of compliancy is very welcome, as the access to ISO/IEC document is limited due to its expensive nature. 218 219 220 # Use stable releases in production! 221 222 Anyone planning to use Tomb to store and access secrets should not use 223 the latest development version in Git, but use instead the .tar.gz 224 release on https://files.dyne.org/tomb . The stable version will 225 always ensure backward compatibility with older tombs: we make sure it 226 creates sane tombs and keys by running various tests before releasing 227 it. The development version in Git might introduce sudden bugs and is 228 not guaranteed to produce backward- or forward-compatible tombs and keys. 229 The development version in Git should be used to report bugs, test new 230 features and develop patches. 231 232 So be warned: do not use the latest Git version in production 233 environments, but use a stable release versioned and packed as 234 tarball on https://files.dyne.org/tomb 235 236 # How can you help 237 238 Donations are very welcome, please go to https://www.dyne.org/donate 239 240 Translations are also needed: they can be contributed via this website 241 https://poeditor.com/join/project/b276xMGAmB 242 or simply sending the .po file. Start from `extras/po/tomb.pot`. 243 244 The code is pretty short and readable: start looking around and the 245 materials found in `doc/` which are good pointers at security measures 246 to be further implemented. 247 248 For the bleeding edge visit https://github.com/dyne/Tomb 249 250 If you plan to commit code into Tomb, please keep in mind this is a 251 minimalist tool and its code should be readable. Guidelines on the 252 coding style are illustrated in [doc/HACKING.txt](doc/HACKING.txt). 253 254 Tomb's developers can be contacted using the issues on GitHub or over 255 IRC on https://irc.dyne.org channel **#dyne** (or direct port 9999 SSL) 256 257 # Licensing 258 259 Tomb is Copyright (C) 2007-2017 by the Dyne.org Foundation and 260 maintained by Denis Roio <jaromil@dyne.org>. More information on all 261 the developers involved is found in the [AUTHORS](AUTHORS.md) file. 262 263 This source code is free software; you can redistribute it and/or 264 modify it under the terms of the GNU Public License as published by 265 the Free Software Foundation; either version 3 of the License, or 266 (at your option) any later version. 267 268 This source code is distributed in the hope that it will be useful, 269 but WITHOUT ANY WARRANTY; without even the implied warranty of 270 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please refer 271 to the GNU Public License for more details. 272 273 You should have received a copy of the GNU Public License along with 274 this source code; if not, write to: Free Software Foundation, Inc., 275 675 Mass Ave, Cambridge, MA 02139, USA.