Tomb/INSTALL.md

# 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 digging tombs and keys
  steghide | bury and exhume keys inside images
  resizefs | extend the size of existing tomb volumes
  qrencode | engrave keys into printable qrcode sheets
  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.

### extras/gtk-tray

The Gtk3 tray adds a nifty tomb skull into the desktop toolbar: one can use it to close, slam and explore the open tomb represented by it.

To have it enter `extras/gtk-tray` then

 1- make sure libnotify and gtk+-3.0 dev packages are available
 2- run `make` inside the directory to build `tomb-gtk-tray`
 3- optionally copy tomb-gtk-tray into your PATH (/usr/local/bin)
 4- start `tomb-gtk-tray tombname` for each tomb

One can include the launch of tomb-gtk-tray from scripts.

### extras/kdf-keys

The KDF wrapper programs allows one to use KDF rounds on passwords in order to obstruct dictionary based and similar brute-forcing attacks.

In case an attacker comes in possession of both a tomb and its key, the easy to memorize password can be guessed by rapidly trying different combinations. With KDF every try will require a significant amount of computation that will slow down the process avoiding tight loops and in fact making such attacks very onerous and almost impossible.

To have it enter `extras/kdf-keys` then

 1- make sure libgcrypt dev packages are available
 2- run `make` inside the directory to build tomb-kdb-* executables
 3- optionally copy tomb-kdb-* into your PATH (/usr/local/bin)
 4- always use tomb using the `--kdf` flag: forge, lock, open etc.

In case one creates and uses KDF keys then the --kdf flag must be always present for tomb to work correctly. It might be handy to create an alias tomb=`tomb --kdf`.

### extras/po (translations)

There are translations available for Tomb. If you wish to install them
navigate to extras/po and run 'make install' as root:

    cd extras/po
    sudo make install