Tomb/tomb

#!/usr/bin/env zsh
#
# Tomb, the Crypto Undertaker
#
# A commandline tool to easily operate encryption of secret data
#

# {{{ License

# Copyright (C) 2007-2024 Dyne.org Foundation
#
# Tomb is designed, written and maintained by Denis Roio <jaromil@dyne.org>
#
# Please refer to the AUTHORS file for more information.
#
# This source code is free software; you can redistribute it and/or
# modify it under the terms of the GNU Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
#
# This source code is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	Please refer
# to the GNU Public License for more details.
#
# You should have received a copy of the GNU Public License along with
# this source code; if not, , see <https://www.gnu.org/licenses/>.

# }}} - License

# {{{ Global variables

typeset VERSION="2.11.0"
typeset DATE="Jul/2024"
typeset TOMBEXEC=$0
typeset TMPDIR=${${TMPPREFIX%/*}:-/tmp}
# TODO: configure which tmp dir to use from a cli flag

# Tomb is using some global variables set by the shell:
# TMPPREFIX, UID, GID, PATH, TTY, USERNAME
# You can grep 'global variable' to see where they are used.

# Keep a reference of the original command line arguments
typeset -a OLDARGS
for arg in "${(@)argv}"; do OLDARGS+=("$arg"); done

# Special command requirements
typeset -a DD WIPE PINENTRY SUDO
DD=(dd)
WIPE=(rm -f)

# load zsh regex module
zmodload zsh/mapfile
zmodload -F zsh/stat b:zstat

# make sure variables aren't exported
unsetopt allexport

# Flag optional commands if available (see _ensure_dependencies())
typeset -i KDF=1
typeset -i STEGHIDE=1
typeset -i CLOAKIFY=1
typeset -i DECLOAKIFY=1
typeset -i RESIZER=1
typeset -i RECOLL=1
typeset -i QRENCODE=1

# Default mount options
typeset		 MOUNTOPTS="rw,noatime,nodev"

# Makes glob matching case insensitive
unsetopt CASE_MATCH

typeset -AH OPTS			  # Command line options (see main())

# Command context (see _whoami())
typeset -H _USER			  # Running username
typeset -Hi _UID			  # Running user identifier
typeset -Hi _GID			  # Running user group identifier
typeset -H  _TTY			  # Connected input terminal

# Tomb context (see is_valid_tomb())
typeset -H TOMBPATH			  # Full path to the tomb
typeset -H TOMBDIR			  # Directory where the tomb is
typeset -H TOMBFILE			  # File name of the tomb
typeset -H TOMBNAME			  # Name of the tomb

# Tomb secrets
typeset -H TOMBKEY			  # Encrypted key contents (see forge_key(), recover_key())
typeset -H TOMBKEYFILE		  # Key file			   (ditto)
typeset -H TOMBSECRET		  # Raw deciphered key	   (see forge_key(), gpg_decrypt())
typeset -H TOMBPASSWORD		  # Raw tomb passphrase	   (see gen_key(), ask_key_password())
typeset -H TOMBTMP			  # Filename of secure temp just created (see _tmp_create())

typeset -aH TOMBTMPFILES	  # Keep track of temporary files
typeset -aH TOMBLOOPDEVS	  # Keep track of used loop devices
typeset -A TOMBFILESSTAT      # Keep track of access date attributes

typeset _MSG_FD_OVERRIDE # if set, _msg will write to this file descriptor

# Make sure sbin is in PATH (man zshparam)
path+=( /sbin /usr/sbin )

# For gettext
export TEXTDOMAIN=tomb

# }}}

# {{{ Safety functions

# Wrap sudo with a more visible message or apply user-supplied alternative to sudo
_sudo() {
	if option_is_set --sudo; then
               pescmd=`option_value --sudo`
		case `basename $pescmd` in
			"doas"|"sup"|"sud"|"pkexec")
				command -v $pescmd > /dev/null || _failure "$pescmd executable not found"
				_verbose "Super user execution using $pescmd"
				${pescmd} ${@}
				return $?
				;;
			"skip"|"none")
				_verbose "Super user execution skipped (SUID caller)"
				${@}
				return $?
				;;
			 *)
				_failure "Super user execution not supported: ::1 sudo::" "`option_value --sudo`"
				;;
		esac

	else
    if [[ "`id -u`" = "0" ]]; then
			_verbose "Super user execution skipped (SUID caller)"
			${@}
			return $?
    elif command -v sudo 1>/dev/null 2>/dev/null; then
		  local msg="[sudo] Enter password for user ::1 user:: to gain superuser privileges"
		  command -v gettext 1>/dev/null 2>/dev/null && msg="$(gettext -s "$msg")"
		  msg=${(S)msg//::1*::/$USER}
		  [[ -n "$SUDO_ASKPASS" ]] && local sudo_askpass="--askpass"
		  sudo $sudo_askpass -p "
$msg

" ${@}
		  return $?
    elif command -v doas 1>/dev/null 2>/dev/null; then
		  local msg="Enter password for user ::1 user:: to gain superuser privileges"
		  command -v gettext 1>/dev/null 2>/dev/null && msg="$(gettext -s "$msg")"
		  msg=${(S)msg//::1*::/$USER}
      doas ${@}
      return $?
    else
      _failure "No way found to escalate privileges to super user."
    fi
	fi
}

# Cleanup anything sensitive before exiting.
_endgame() {

	option_value_contains -o ro || {
		# Restore access time of sensitive files
		[[ -z $TOMBFILESSTAT ]] || _restore_stat
	}

	# Prepare some random material to overwrite vars
	local rr="$RANDOM"
	while [[ ${#rr} -lt 500 ]]; do
		rr+="$RANDOM"
	done

	# Ensure no information is left in unallocated memory
	TOMBPATH="$rr";		 unset TOMBPATH
	TOMBDIR="$rr";		 unset TOMBDIR
	TOMBFILE="$rr";		 unset TOMBFILE
	TOMBNAME="$rr";		 unset TOMBNAME
	TOMBKEY="$rr";		 unset TOMBKEY
	TOMBKEYFILE="$rr";	 unset TOMBKEYFILE
	TOMBSECRET="$rr";	 unset TOMBSECRET
	TOMBPASSWORD="$rr";	 unset TOMBPASSWORD

	# Clear temporary files
	for f in $TOMBTMPFILES; do
		${=WIPE} "$f"
	done
	unset TOMBTMPFILES

	# Clear information regarding loop devices
	# No need for an explicit detach as cryptsetup
	# sets the AUTOCLEAR flag
	unset TOMBLOOPDEVS
}

# Trap functions for the _endgame event
TRAPINT()  { _endgame INT;	}
TRAPEXIT() { _endgame EXIT;	}
TRAPHUP()  { _endgame HUP;	}
TRAPQUIT() { _endgame QUIT;	}
TRAPABRT() { _endgame ABORT;    }
TRAPKILL() { _endgame KILL;	}
TRAPPIPE() { _endgame PIPE;	}
TRAPTERM() { _endgame TERM;	}
TRAPSTOP() { _endgame STOP;	}

_is_found() {
	# returns 0 if binary is found in path
	[[ -z $1 ]] && return 1
	command -v "$1" 1>/dev/null 2>/dev/null
	return $?
}

# Track acces and modification time of tomb files.
# $1: file to track
# date format: seconds since Epoch
# stat format: <last access>:<last modified>
_track_stat() {
    local file="$1"
    local stat=$(stat --format="%X:%Y" "$file")
    TOMBFILESSTAT+=("$file" "$stat")
}

# Restore files stats
_restore_stat() {
    local file stat
    for file stat in "${(@kv)TOMBFILESSTAT}"; do
        stats=("${(@s.:.)stat}")
        _verbose "Restoring access and modification time for ::1 file::" $file
        [[ -z "${stats[1]}" ]] || touch -a --date="@${stats[1]}" "$file"
        [[ -z "${stats[2]}" ]] || touch -m --date="@${stats[2]}" "$file"
    done
}

# Identify the running user
# Set global variables _UID, _GID, _TTY, and _USER, either from the
# command line, -U, -G, -T, respectively, or from the environment.
# Also update USERNAME and HOME to maintain consistency.
_whoami() {

	# Set username from UID or environment
	_USER=$SUDO_USER
	[[ -z $_USER ]] && { _USER=$USERNAME }
	[[ -z $_USER ]] && { _USER=$(id -un) }
	[[ -z $_USER ]] && {
		_failure "Failing to identify the user who is calling us" }

	# Get GID from option -G or the environment
	option_is_set -G \
		&& _GID=$(option_value -G) || _GID=$(id -g $_USER)

	# Get UID from option -U or the environment
	option_is_set -U \
		&& _UID=$(option_value -U) || _UID=$(id -u $_USER)

	_verbose "Identified caller: ::1 username:: (::2 UID:::::3	GID::)" $_USER $_UID $_GID

	# Update USERNAME accordingly if possible
	# [[ $EUID == 0 && $_USER != $USERNAME ]] && {
	#	  _verbose "Updating USERNAME from '::1 USERNAME::' to '::2 _USER::')" $USERNAME $_USER
	#	  USERNAME=$_USER
	# }

	# Force HOME to _USER's HOME if necessary
	local home=`_get_home $_USER`
	[[ $home == $HOME ]] || {
		_verbose "Updating HOME to match user's: ::1 home:: (was ::2 HOME::)" \
				 $home $HOME
		HOME=$home }

	# Get connecting TTY from option -T or the environment
	option_is_set -T && _TTY=$(option_value -T)
	[[ -z $_TTY ]]	 && _TTY=$TTY

}

# Provide a random filename in shared memory
_tmp_create() {
	[[ -d "$TMPDIR" ]] || {
		# we create the tempdir with the sticky bit on
		_sudo mkdir -m 1777 "$TMPDIR"
		[[ $? == 0 ]] || _failure "Fatal error creating the temporary directory: ::1 temp dir::" "$TMPDIR"
	}

	# We're going to add one more $RANDOM for each time someone complains
	# about this being too weak of a random.
	tfile="${TMPDIR}/$RANDOM$RANDOM$RANDOM$RANDOM"	# Temporary file
	umask 066
	[[ $? == 0 ]] || {
		_failure "Fatal error setting the permission umask for temporary files" }

	[[ -r "$tfile" ]] && {
		_failure "Someone is messing up with us trying to hijack temporary files." }

	touch "$tfile"
	[[ $? == 0 ]] || {
		_failure "Fatal error creating a temporary file: ::1 temp file::" "$tfile" }

	_verbose "Created tempfile: ::1 temp file::" "$tfile"
	TOMBTMP="$tfile"
	TOMBTMPFILES+=("$tfile")

	return 0
}

# Check if a *block* device is encrypted
# Check if a *block* device is a zram device
# Synopsis: _is_zramswap /path/to/block/device
# Return 0 if it is a zramswap
# Return 1 if it is not a zramswap
_is_zramswap() {
	local	b=$1 # Path to a block device

	# check if device b is a zram block device
	zramctl --raw -o NAME | grep "^$b" >/dev/null

	return $?
}

# Check if a zram device uses the writeback feature that writes data onto a disk
# Synopsis: _zramswap_uses_writeback /path/to/block/device
# Return 0 if the zram device writes to disk
# Return 1 if the zram device does not write to disk
_zramswap_uses_writeback() {
	local	b=$1 # Path to a block device
	local	m="" # major device number
	local	n="" # minor device number

	read n m < <(stat -c '%T %t' $b) # get major and minor device number in hex
	printf -v m %d $((16#$m)) # get major device number in decimal
	printf -v n %d $((16#$n)) # get minor device number in decimal

	if grep '^none$' "/sys/dev/block/$m:$n/backing_dev" > /dev/null; then
		return 1
	fi

	return 0
}

# Check if a *block* device is a zram device
# Synopsis: _is_zramswap /path/to/block/device
# Return 0 if it is a zramswap
# Return 1 if it is not a zramswap
_is_zramswap() {
	local	b=$1 # Path to a block device

	zramctl --raw -o NAME | grep "^$b" >/dev/null
	# @todo How to do this without zramctl?
	# - device node major is dynamically allocated to zram0
	# - in /sys/ there seems to be no file identifying a zram device

	return $?
}

# Check if a zram device uses the writeback feature that writes data onto a disk
# Synopsis: _zramswap_uses_writeback /path/to/block/device
# Return 0 if the zram device writes to disk
# Return 1 if the zram device does not write to disk
_zramswap_uses_writeback() {
	local	b=$1 # Path to a block device
	local	m="" # major device number
	local	n="" # minor device number

	read n m < <(stat -c '%T %t' $b) # get major and minor device number in hex
	printf -v m %d $((16#$m)) # get major device number in decimal
	printf -v n %d $((16#$n)) # get minor device number in decimal

	if grep '^none$' "/sys/dev/block/$m:$n/backing_dev" > /dev/null; then
		return 1
	fi

	return 0
}

# Synopsis: _is_encrypted_block /path/to/block/device
# Return 0 if it is an encrypted block device
_is_encrypted_block() {
	local	 b=$1 # Path to a block device
	local	 s="" # lsblk option -s (if available)

	# Issue #163
	# lsblk --inverse appeared in util-linux 2.22
	# but --version is not consistent...
	lsblk --help | grep -Fq -- --inverse
	[[ $? -eq 0 ]] && s="--inverse"

	_sudo lsblk $s -o type -n $b 2>/dev/null \
		| egrep -q '^crypt$'

	return $?
}

# Check if swap is activated
# Return 0 if NO swap is used, 1 if swap is used.
# Return 1 if any of the swaps is not encrypted.
# Return 2 if swap(s) is(are) used, but ALL encrypted or zramswap without writeback to disk.
# Use _check_swap in functions. It will call this function and
# exit if unsafe swap is present.
_ensure_safe_swap() {

	local -i r=1	# Return code: 0 no swap, 1 unsafe swap, 2 encrypted
	local -a swaps	# List of swap partitions
	local	 bone is_crypt

	swaps="$(awk '/^\// { print $1 }' /proc/swaps 2>/dev/null)"
	[[ -z "$swaps" ]] && return 0 # No swap partition is active

	_message "An active swap partition is detected..."
	for s in $=swaps; do
		if _is_encrypted_block $s; then
			r=2;
		elif _is_zramswap $s; then
			if _zramswap_uses_writeback $s; then
				# We're dealing with unencrypted stuff written to disk.
				# Maybe it lives on an encrypted filesystem anyway.
				# @todo verify it's actually written to an encrypted FS
				# Well, no: bail out.
				_message "Found zramswap with writeback enabled."
				r=1; break;
			else
				_message "Found zramswap without writeback to disk."
				r=2
			fi
		else
			# We're dealing with unencrypted stuff written to disk.
			# Maybe it lives on an encrypted filesystem anyway.
			# @todo: verify it's actually on an encrypted FS (see #163 and !189)
			# Well, no: bail out.
			r=1; break;
		fi
	done

	if [[ $r -eq 2 ]]; then
		_success "The undertaker found that all swap partitions are encrypted. Good."
	else
		_warning "This poses a security risk."
		_warning "You can deactivate all swap partitions using the command:"
		_warning " swapoff -a"
		_warning "[#163] I may not detect plain swaps on an encrypted volume."
		_warning "But if you want to proceed like this, use the -f (force) flag."
	fi
	return $r

}

# Wrapper to allow encrypted swap and remind the user about possible
# data leaks to disk if swap is on, which shouldn't be ignored. It could
# be run once in main(), but as swap evolves, it's better to run it
# whenever swap may be needed.
# Exit if unencrypted swap is active on the system.
_check_swap() {
	if ! option_is_set -f && ! option_is_set --ignore-swap; then
		_ensure_safe_swap
		case $? in
			0|2)	 # No, or encrypted swap
				return 0
				;;
			*)		 # Unencrypted swap
				_failure "Operation aborted."
				;;
		esac
	fi
}

pinentry_assuan_getpass() {
	# simply prints out commands for pinentry's stdin to activate the
	# password dialog
	cat <<EOF
OPTION ttyname=$TTY
OPTION lc-ctype=$LANG
SETTITLE $title
SETDESC $description
SETPROMPT Password:
GETPIN
EOF
}

# Ask user for a password
# Wraps around the pinentry command, from the GnuPG project, as it
# provides better security and conveniently use the right toolkit.
ask_password() {

	local description="$1"
	local title="${2:-Enter tomb password.}"
	local output
	local password
	local gtkrc
	local theme
	local pass_asked

	# Distributions have broken wrappers for pinentry: they do
	# implement fallback, but they disrupt the output somehow.	We are
	# better off relying on less intermediaries, so we implement our
	# own fallback mechanisms. Pinentry supported: curses, gtk-2, qt4, qt5
	# and x11.

	# make sure LANG is set, default to C
	LANG=${LANG:-C}

	_verbose "asking password with tty=$TTY lc-ctype=$LANG"

	pass_asked=0

	while true; do
		[[ ! -z $WAYLAND_DISPLAY ]] && {
			_verbose "wayland display detected"
			_is_found "pinentry-gnome3" && {
				_verbose "using pinentry-gnome3 on wayland"
				output=$(pinentry_assuan_getpass | pinentry-gnome3)
				break; }
			# TODO: pinentry on KDE running in wayland?
		}
		[[ ! -z $DISPLAY ]] && [[ $pass_asked == 0 ]] && {
			_verbose "X11 display detected"
			_is_found "pinentry-gtk-2" && {
				_verbose "using pinentry-gtk2"
				output=$(pinentry_assuan_getpass | pinentry-gtk-2)
				break; }
			_is_found "pinentry-x11" && {
				_verbose "using pinentry-x11"
				output=$(pinentry_assuan_getpass | pinentry-x11)
				break; }
			_is_found "pinentry-gnome3" && {
				_verbose "using pinentry-gnome3 on X11"
				output=$(pinentry_assuan_getpass | pinentry-gnome3)
				break; }
			_is_found "pinentry-qt5" && {
				_verbose "using pinentry-qt5"
				output=$(pinentry_assuan_getpass | pinentry-qt5)
				break; }
			_is_found "pinentry-qt4" && {
				_verbose "using pinentry-qt4"
				output=$(pinentry_assuan_getpass | pinentry-qt4)
				break; }
		}
		_verbose "no display detected"
		_is_found "pinentry-curses" && {
			_verbose "using pinentry-curses with no display"
			output=$(pinentry_assuan_getpass | pinentry-curses)
			break; }
		_is_found "pinentry-tty" && {
			_verbose "using pinentry-tty with no display"
			output=$(pinentry_assuan_getpass | pinentry-tty)
			break; }
		# TODO: fallback using read -s - and beware
		# using read with or without -r may break
		# passwords, so this must be covered by a test
		# for compatibility
		_failure "Cannot find any pinentry and no DISPLAY detected."
		exit 1
	done

	# parse the pinentry output
	local pinentry_error
	for i in ${(f)output}; do
		[[ "$i" =~ "^ERR.*" ]] && {
			pinentry_error="${i[(w)3]}"
		}

		# here the password is found
		[[ "$i" =~ "^D .*" ]] && password="${i##D }";
	done

	[[ ! -z $pinentry_error ]] && [[ -z $password ]] && {
		_warning "Pinentry error: ::1 error::" ${pinentry_error}
		print "canceled"
		return 1
	}

	[[ -z $password ]] && {
		_warning "Empty password"
		print "empty"
		return 1
	}

	print "$password"
	return 0
}

# Check if a filename is a valid tomb
is_valid_tomb() {

	_verbose "is_valid_tomb ::1 tomb file::" $1

	# First argument must be the path to a tomb
	[[ ! -z $1 ]] ||	_failure "Tomb file is missing from arguments."

	local _fail=0
	# Tomb file must be a readable, writable, non-empty regular file.
	# If passed the "ro" mount option, the writable check is skipped.
	while true; do
		option_value_contains -o ro || {
			[[ ! -w "$1" ]] && {
				_warning "Tomb file is not writable: ::1 tomb file::" $1
				_fail=1; break; }
		}
		_verbose "tomb file is readable"
		[[ ! -f "$1" ]] && {
			_warning "Tomb file is not a regular file: ::1 tomb file::" $1
			_fail=1; break; }
		_verbose "tomb file is a regular file"
		[[ ! -s "$1" ]] && {
			_warning "Tomb file is empty (zero length): ::1 tomb file::" $1
			_fail=1; break; }
		_verbose "tomb file is not empty"
		break;
	done
	[[ $_fail == 1 ]] && {
		_failure "Tomb command failed: ::1 command name::" $subcommand
	}

	# Tomb file may be a LUKS FS (or we are creating it)
	[[ "`file $1`" =~ "luks encrypted file" ]] || {
		_message "File is not yet a tomb: ::1 tomb file::" $1 }

	# We set global variables
	typeset -g TOMBPATH TOMBDIR TOMBFILE TOMBNAME TOMBMAPPER

	TOMBPATH="$1"

	TOMBDIR=$(dirname $TOMBPATH)

	TOMBFILE=$(basename $TOMBPATH)

	# The tomb name is TOMBFILE without an extension and underscores instead of spaces (for mount and cryptsetup)
	# It can start with dots: ..foo bar baz.tomb -> ..foo_bar_baz
	TOMBNAME=${${TOMBFILE// /_}%.*}
	# use the entire filename if the previous transformation returns
	# an empty string. This handles the corner case of tomb being
	# hidden files (starting with a dot) and have no extension (only
	# one dot in string)
	TOMBNAME=${TOMBNAME:-${TOMBFILE}}
	[[ -z $TOMBNAME ]] &&
		_failure "Tomb won't work without a TOMBNAME."

	# checks if Tomb already mounted (or we cannot alter it)
	local maphash=`realpath $TOMBPATH | sha256sum`
	lo_check # fills TOMBLOOP with next loop if available
	TOMBMAPPER="tomb.$TOMBNAME.${maphash[(w)1]}.`basename $TOMBLOOP`"
	local mounted_tombs=(`list_tomb_mounts`)
	local usedmapper
	for t in ${mounted_tombs}; do
		usedmapper=`basename "${t[(ws:;:)1]}"`
		[[ "${usedmapper%.*}" == "${TOMBMAPPER%.*}" ]] &&
			_failure "Tomb file already in use: ::1 tombname::" $TOMBPATH
	done
	_verbose "Mapper: ::1 mapper::" $TOMBMAPPER

	_verbose "tomb file is not currently in use"

	_message "Valid tomb file found: ::1 tomb path::" $TOMBPATH
	return 0
}

# $1 is the tomb file which needs a loop device
lo_check() {
	tpath="$1"

	# check if we have support for loop mounting
	TOMBLOOP=`_sudo losetup -f`
	[[ $? = 0 ]] || {
		_warning "Loop mount of volumes is not possible on this machine, this error"
		_warning "often occurs on VPS and kernels that don't provide the loop module."
		_warning "It is impossible to use Tomb on this machine under these conditions."
		_failure "Operation aborted."
	}

	[[ "$tpath" == "" ]] && return 0

	TOMBLOOPDEVS+=("$TOMBLOOP") # add to array of lodevs used

	return 0
}

# eventually used for debugging
dump_secrets() {
	print "TOMBPATH: $TOMBPATH"
	print "TOMBNAME: $TOMBNAME"

	print "TOMBKEY len: ${#TOMBKEY}"
	print "TOMBKEYFILE: $TOMBKEYFILE"
	print "TOMBSECRET len: ${#TOMBSECRET}"
	print "TOMBPASSWORD: $TOMBPASSWORD"

	print "TOMBTMPFILES: ${(@)TOMBTMPFILES}"
	print "TOMBLOOPDEVS: ${(@)TOMBLOOPDEVS}"
}

# }}}

# {{{ Commandline interaction

usage() {
	_print "Syntax: tomb [options] command [arguments]"
	echo
	_print "Commands:"
	echo
	_print " // Creation:"
	_print " dig          create a new empty TOMB file of size -s in MiB"
	_print " forge        create a new KEY file and set its password"
	_print " lock         installs a lock on a TOMB to use it with KEY"
	echo
	_print " // Operations on tombs:"
	_print " open         open an existing TOMB (-k KEY file or - for stdin)"
	_print " index        update the search indexes of tombs"
	_print " search       looks for filenames matching text patterns"
	_print " list         list of open TOMBs and information on them"
	_print " ps           list of running processes inside open TOMBs"
	_print " close        close a specific TOMB (or 'all')"
	_print " slam         slam a TOMB killing all programs using it"
	[[ $RESIZER == 1 ]] && {
		_print " resize       resize a TOMB to a new size -s (can only grow)"
	}
	echo
	_print " // Operations on keys:"
	_print " passwd       change the password of a KEY (needs old pass)"
	_print " setkey       change the KEY locking a TOMB (needs old key and pass)"
	echo
	[[ $QRENCODE == 1 ]] && {
		_print " // Backup on paper:"
		_print " engrave      makes a QR code of a KEY to be saved on paper"
		echo
	}
	[[ $STEGHIDE == 1 || $CLOAKIFY == 1 || $DECLOAKIFY == 1 ]] && {
		_print " // Steganography:"
		[[ $STEGHIDE == 1 ]] && {
			_print " bury         hide a KEY inside a JPEG image (for use with -k)"
			_print " exhume       extract a KEY from a JPEG image (prints to stdout)"
		}
		[[ $CLOAKIFY == 1 ]] && {
			_print " cloak        transform a KEY into TEXT using CIPHER (for use with -k)"
		}
		[[ $DECLOAKIFY == 1 ]] && {
			_print " uncloak      extract a KEY from a TEXT using CIPHER (prints to stdout)"
		}
		echo
	}
	_print "Options:"
	echo
	_print " -s           size of the tomb file when creating/resizing one (in MiB)"
	_print " -k           path to the key to be used ('-k -' to read from stdin)"
	_print " -n           don't launch the execution hooks found in tomb"
	_print " -p           preserve the ownership of all files in tomb"
	_print " -o           options passed to commands: open, lock, forge (see man)"
	_print " -f           force operation (i.e. even if swap is active)"
	_print " -g           use a GnuPG key to encrypt a tomb key"
	_print " -r           provide GnuPG recipients (separated by comma)"
	_print " -R           provide GnuPG hidden recipients (separated by comma)"
	_print " --sudo       super user exec alternative to sudo (doas or none)"

	[[ $KDF == 1 ]] && {
		_print " --kdf        forge keys armored against dictionary attacks"
	}

	echo
	_print " -h           print this help"
	_print " -v           print version, license and list of available ciphers"
	_print " -q           run quietly without printing informations"
	_print " -D           print debugging information at runtime"
	echo
	_print "For more information on Tomb read the manual: man tomb"
	_print "Please report bugs on <http://github.com/dyne/tomb/issues>."
}


# Check whether a commandline option is set.
#
# Synopsis: option_is_set -flag [out]
#
# First argument is the commandline flag (e.g., "-s").
# If the second argument is present and set to 'out', print out the
# result: either 'set' or 'unset' (useful for if conditions).
#
# Return 0 if is set, 1 otherwise
option_is_set() {
	local -i r	 # the return code (0 = set, 1 = unset)

	[[ -n ${(k)OPTS[$1]} ]];
	r=$?

	[[ $2 == "out" ]] && {
		[[ $r == 0 ]] && { print 'set' } || { print 'unset' }
	}

	return $r;
}

# Print the option value matching the given flag
# Unique argument is the commandline flag (e.g., "-s").
option_value() {
	print -n - "${OPTS[$1]}"
}

# check if the option value contains a string between commas
option_value_contains() {
	local opt="${OPTS[$1]}"
	local str="$2"
	for i in ${(s:,:)opt}; do
		[[ "$i" == "$2" ]] && return 0
	done
	return 1
}

# Messaging function with pretty coloring
function _msg() {
	local msg="$2"
	local i
	command -v gettext 1>/dev/null 2>/dev/null && msg="$(gettext -s "$2")"
	for i in {3..${#}}; do
		msg=${(S)msg//::$(($i - 2))*::/$*[$i]}
	done

	local command="print -P"
	local progname="${TOMBEXEC##*/}"
	local pchars=""
	local pcolor="normal"
	local fd=2
	local -i returncode

	case "$1" in
		inline)
			command+=" -n"; pchars=" > "; pcolor="yellow"
			;;
		message)
			pchars=" . "; pcolor="white"
			;;
		verbose)
			pchars="[D]"; pcolor="blue"
			;;
		success)
			pchars="(*)"; pcolor="green"
			;;
		warning)
			pchars="[W]"; pcolor="yellow"
			;;
		failure)
			pchars="[E]"; pcolor="red"
			returncode=1
			;;
		print)
			progname=""
			fd=1
			;;
		*)
			pchars="[F]"; pcolor="red"
			msg="Developer oops!  Usage: _msg MESSAGE_TYPE \"MESSAGE_CONTENT\""
			returncode=127
			;;
	esac

	[[ -n $_MSG_FD_OVERRIDE ]] && fd=$_MSG_FD_OVERRIDE

	if [[ -t $fd ]]; then
	       [[ -n "$progname" ]] && progname="$fg[magenta]$progname$reset_color"
	       [[ -n "$pchars" ]] && pchars="$fg_bold[$pcolor]$pchars$reset_color"
	       msg="$fg[$pcolor]$msg$reset_color"
	fi

	${=command} "${progname}" "${pchars}" "${msg}" >&$fd
	return $returncode
}

function _message() {
	local notice="message"
	[[ "$1" = "-n" ]] && shift && notice="inline"
	option_is_set -q || _msg "$notice" $@
	return 0
}

function _verbose() {
	option_is_set -D && _msg verbose $@
	return 0
}

function _success() {
	option_is_set -q || _msg success $@
	return 0
}

function _warning() {
	option_is_set -q || _msg warning $@
	return 1
}

function _failure() {
	typeset -i exitcode=${exitv:-1}
	option_is_set -q || _msg failure $@
	# be sure we forget the secrets we were told
	exit $exitcode
}

function _print() {
	option_is_set -q || _msg print $@
	return 0
}

_list_optional_tools() {
	typeset -a _deps
	_deps=(gettext dcfldd shred steghide)
	_deps+=(resize2fs tomb-kdb-pbkdf2 argon2 qrencode recoll unoconv lsof)
	for d in $_deps; do
		_print "`which $d`"
	done
	return 0
}


# Check program dependencies
#
# Tomb depends on system utilities that must be present, and other
# functionality that can be provided by various programs according to
# what's available on the system.  If some required commands are
# missing, bail out.
_ensure_dependencies() {

	# Check for required programs
	for req in cryptsetup gpg mkfs.ext4 e2fsck; do
		command -v $req 1>/dev/null 2>/dev/null || {
			_failure "Missing required dependency ::1 command::.  Please install it." $req; }
	done
	# Check for pinentry or at least pinentry-tty (which has no alias)
	if ! command -v pinentry 1>/dev/null 2>/dev/null; then
		if ! command -v pinentry-tty 1>/dev/null 2>/dev/null; then
			_failure "Missing required dependency ::1 command::.  Please install it." pinentry
		fi
	fi
	# Ensure system binaries are available in the PATH
	path+=(/sbin /usr/sbin) # zsh magic

	# use pkexec in place of sudo if found in path and polkitd is running
	# command -v pkexec 1>/dev/null 2>/dev/null
	# [[ $? == 0 ]] && ps ax | grep '[p]olkitd' 1>/dev/null 2>/dev/null && {
	#     SUDO=(pkexec)	}
	# [[ "$SUDO" == "sudo" ]] && {
	#     command -v sudo 1>/dev/null 2>/dev/null ||
	# 	_failure "No privilege escalation tool found, not even sudo"
	# }

	# Which dd command to use
	command -v dcfldd 1>/dev/null 2>/dev/null && DD=(dcfldd statusinterval=1)

	# Which wipe command to use
	command -v shred 1>/dev/null 2>/dev/null && WIPE=(shred -f -u)

	# Check for lsof for slamming tombs
	command -v lsof 1>/dev/null 2>/dev/null || LSOF=0
	# Check for steghide
	command -v steghide 1>/dev/null 2>/dev/null || STEGHIDE=0
	# Check for cloakify
	command -v cloakify 1>/dev/null 2>/dev/null || CLOAKIFY=0
	# Check for decloakify
	command -v decloakify 1>/dev/null 2>/dev/null || DECLOAKIFY=0
	# Check for resize
	command -v resize2fs 1>/dev/null 2>/dev/null || RESIZER=0
	# Check for KDF auxiliary tools
	command -v tomb-kdb-pbkdf2 1>/dev/null 2>/dev/null || KDF=0
	# Check for ARGON2 KDF auxiliary tools
	command -v argon2 1>/dev/null 2>/dev/null || ARGON2=0
	# Check for Recoll file content indexer
	command -v recoll 1>/dev/null 2>/dev/null || RECOLL=0
	# Check for QREncode for paper backups of keys
	command -v qrencode 1>/dev/null 2>/dev/null || QRENCODE=0
}

# }}} - Commandline interaction

# {{{ Key operations

# $@ is the list of all the recipient used to encrypt a tomb key
is_valid_recipients() {
	typeset -a recipients
	recipients=($@)
	trusted=(m f u w s)

	_verbose "is_valid_recipients"

	# All the keys ID must be valid (the public keys must be present in the database)
	for gpg_id in ${recipients[@]}; do
		trust="$(gpg --with-colons --batch --list-keys "$gpg_id" 2> /dev/null |
				 	awk 'BEGIN { FS=":" } /^pub/ { print $2; exit}')"
		[[ "${trust}" == "" ]] && {
			_warning "Not a valid GPG key ID: ::1 gpgid:: " $gpg_id
			return 1
		}
		[[ ${trusted[(r)$trust]} != $trust ]] && {
			_warning "The key ::1 gpgid:: is not trusted enough" $gpg_id
			return 1
		}
	done

	# At least one private key must be present
#	for gpg_id in ${recipients[@]}; do
#		gpg --with-colons --batch --list-secret-keys "$gpg_id" &> /dev/null
#		[[ $? = 0 ]] && {
#			return 0
#		}
#	done

	return 0
}

# $@ is the list of all the recipient used to encrypt a tomb key
# Print the recipient arg to be used in gpg.
_recipients_arg() {
	local arg="$1"; shift
	typeset -a recipients
	recipients=($@)

	for gpg_id in ${recipients[@]}; do
		print -R -n "$arg $gpg_id "
	done
	return 0
}

# $1 is a GPG key recipient
# Print the fingerprint of the GPG key
_gpg_fingerprint() {
	gpg --with-colons --fingerprint "$1" |
		awk 'BEGIN { FS=":" } /^fpr/ { print $10; exit }' }
_gpg_uid() {
	gpg --with-colons --list-key "$1" |
		awk 'BEGIN { FS=":" } /^uid/ { print $10; exit}' }

# helpers to retrieve data from passwd using getent
_get_username() { getent passwd ${1} | awk -F: '{print $1}' }
_get_home()     { getent passwd ${1} | awk -F: '{print $6}' }

# $1 is the encrypted key contents we are checking
is_valid_key() {
	local key="$1"		 # Unique argument is an encrypted key to test

	_verbose "is_valid_key"

	[[ -z $key ]] && key=$TOMBKEY
	[[ "$key" = "cleartext" ]] && {
		{ option_is_set --unsafe } || {
			_warning "cleartext key from stdin selected: this is unsafe."
			exitv=127 _failure "please use --unsafe if you really want to do this."
		}
		_warning "received key in cleartext from stdin (unsafe mode)"
		return 0 }

	[[ -z $key ]] && {
		_warning "is_valid_key() called without an argument."
		return 1
	}

	# If the key file is an image don't check file header
	[[ -r $TOMBKEYFILE ]] \
		&& [[ $(file $TOMBKEYFILE) =~ "JP.G" ]] \
		&& {
		_message "Key is an image, it might be valid."
		return 0 }

	[[ $KDF == 1 ]] && { ! option_is_set -g } && { option_is_set --kdf } && {
		_head="${key[(f)1]}"
		[[ $_head =~ '^_KDF_' ]] || {
			_warning "Key is missing KDF header."
			return 1
		}
	}

	[[ $key =~ "BEGIN PGP" ]] && {
		_message "Key is valid."
		return 0 }

	return 1
}

# $1 is a string containing an encrypted key
recover_key() {
	local key="${1}"	# Unique argument is an encrypted key

	_warning "Attempting key recovery."

	_head="${key[(f)1]}" # take the first line

	TOMBKEY=""		  # Reset global variable

	[[ $_head =~ "^_KDF_" ]] && TOMBKEY+="$_head\n"

	TOMBKEY+="-----BEGIN PGP MESSAGE-----\n"
	TOMBKEY+="$key\n"
	TOMBKEY+="-----END PGP MESSAGE-----\n"

	return 0
}

# Retrieve the tomb key from the file specified from the command line,
# or from stdin if -k - was selected.  Run validity checks on the
# file.	 On success, return 0 and print out the full path of the key.
# Set global variables TOMBKEY and TOMBKEYFILE.
_load_key() {
	local keyfile="$1"	  # Unique argument is an optional keyfile

	[[ -z $keyfile ]] && keyfile=$(option_value -k)
	[[ -z $keyfile ]] && {
		_failure "This operation requires a key file to be specified using the -k option." }

	while true; do
		[[ $keyfile == "-" ]] && {
			_verbose "load_key reading from stdin."
			_message "Waiting for the key to be piped from stdin... "
			TOMBKEYFILE=stdin
			TOMBKEY=$(cat)
			break; }
		[[ $keyfile == "cleartext" ]] && {
			_verbose "load_key reading SECRET from stdin"
			_message "Waiting for the key to be piped from stdin... "
			TOMBKEYFILE=cleartext
			TOMBKEY=cleartext
			TOMBSECRET=$(cat)
			break; }
		_verbose "load_key argument: ::1 key file::" $keyfile
		[[ -r $keyfile ]] || _failure "Key not found, specify one using -k."
		_track_stat "$keyfile"
		TOMBKEYFILE=$keyfile
		TOMBKEY="${mapfile[$TOMBKEYFILE]}"
		break
	done

	_verbose "load_key: ::1 key::" $TOMBKEYFILE

	[[ -z $TOMBKEY ]] && {
		# something went wrong, there is no key to load
		# this occurs especially when piping from stdin and aborted
		_failure "Key not found, specify one using -k."
	}

	is_valid_key $TOMBKEY || {
		_warning "The key seems invalid or its format is not known by this version of Tomb."
		recover_key $TOMBKEY
	}

	# Declared TOMBKEYFILE (path)
	# Declared TOMBKEY (contents)

	return 0
}

# takes two args just like get_lukskey
# prints out the decrypted content
# contains tweaks for different gpg versions
# support both symmetric and asymmetric encryption
gpg_decrypt() {
	# fix for gpg 1.4.11 where the --status-* options don't work ;^/
	local gpgver=$(gpg --version --no-permission-warning | awk '/^gpg/ {print $3}')
	local gpgpass="$1\n$TOMBKEY"
	local tmpres ret
	typeset -a gpgopt
	gpgpopt=(--batch --no-tty --passphrase-fd 0 --no-options)

	{ option_is_set -g } && {
		gpgpass="$TOMBKEY"
		gpgpopt=(--yes)

		# GPG option '--try-secret-key' exist since GPG 2.1
		{ option_is_set -R } && { autoload -U is-at-least && is-at-least "2.1" $gpgver } && {
			typeset -a recipients
			recipients=(${(s:,:)$(option_value -R)})
			{ is_valid_recipients $recipients } || {
				_failure "You set an invalid GPG ID."
			}
			gpgpopt+=(`_recipients_arg "--try-secret-key" $recipients`)
		}
	}

	[[ $gpgver == "1.4.11" ]] && {
		_verbose "GnuPG is version 1.4.11 - adopting status fix."
		TOMBSECRET=`print - "$gpgpass" | \
			gpg --decrypt ${gpgpopt[@]}`
		ret=$?
		unset gpgpass
		return $ret
	}

	_tmp_create
	tmpres=$TOMBTMP
	TOMBSECRET=`print - "$gpgpass" | \
		gpg --decrypt ${gpgpopt[@]} \
			--status-fd 2 --no-mdc-warning --no-permission-warning \
			--no-secmem-warning 2> $tmpres`
	unset gpgpass
	ret=1
	for i in ${(f)"$(cat $tmpres)"}; do
		_verbose "$i"
		[[ "$i" =~ "DECRYPTION_OKAY" ]] && ret=0;
	done
	return $ret

}


# Gets a key file and a password, prints out the decoded contents to
# be used directly by Luks as a cryptographic key
get_lukskey() {
	# $1 is the password
	_verbose "get_lukskey"

	_password="$1"


	firstline="${TOMBKEY[(f)1]}"

	# key is KDF encoded
	if [[ $firstline =~ '^_KDF_' ]]; then
		kdf_hash="${firstline[(ws:_:)2]}"
		_verbose "KDF: ::1 kdf::" "$kdf_hash"
		case "$kdf_hash" in
			"pbkdf2sha1")
				kdf_salt="${firstline[(ws:_:)3]}"
				kdf_ic="${firstline[(ws:_:)4]}"
				kdf_len="${firstline[(ws:_:)5]}"
				_message "Unlocking KDF key protection (::1 kdf::)" $kdf_hash
				_verbose "KDF salt: $kdf_salt"
				_verbose "KDF ic: $kdf_ic"
				_verbose "KDF len: $kdf_len"
				_password=$(tomb-kdb-pbkdf2 $kdf_salt $kdf_ic $kdf_len 2>/dev/null <<<$_password)
				;;

			"argon2")
				kdf_salt="${firstline[(ws:_:)3]}"
				kdf_ic="${firstline[(ws:_:)4]}"
				kdf_mem="${firstline[(ws:_:)5]}"
				_message "Unlocking KDF key protection (::1 kdf::)" $kdf_hash
				_verbose "KDF salt: $kdf_salt"
				_verbose "KDF ic: $kdf_ic"
				_verbose "KDF mem: $kdf_mem"
				_password=$(argon2 $kdf_salt -m $kdf_mem -t $kdf_ic -l 64 -r 2>/dev/null <<<$_password)
				;;

			*)
				_failure "No suitable program for KDF ::1 program::." $pbkdf_hash
				unset _password
				return 1
				;;
		esac

		# key needs to be exhumed from an image
	elif [[ -r $TOMBKEYFILE && $(file $TOMBKEYFILE) =~ "JP.G" ]]; then
		if option_is_set -g; then
			# When using a GPG key, the tomb key is buried using a steganography password
			if option_is_set --tomb-pwd; then
				_password="`option_value --tomb-pwd`"
				_verbose "tomb-pwd = ::1 tomb pass::" $_password
			else
				_password=$(ask_password "Insert password to exhume key from $imagefile")
				[[ $? != 0 ]] && {
					_warning "User aborted password dialog."
					return 1
				}
			fi
			exhume_key $TOMBKEYFILE "$_password"
			unset _password
		else
			exhume_key $TOMBKEYFILE "$_password"
		fi
	fi

	gpg_decrypt "$_password" # Save decrypted contents into $TOMBSECRET

	ret="$?"

	_verbose "get_lukskey returns ::1::" $ret
	return $ret
}

# This function asks the user for the password to use the key it tests
# it against the return code of gpg on success returns 0 and saves
# the password in the global variable $TOMBPASSWORD
ask_key_password() {
	[[ -z "$TOMBKEYFILE" ]] && {
		_failure "Internal error: ask_key_password() called before _load_key()." }

	[[ "$TOMBKEYFILE" = "cleartext" ]] && {
		_verbose "no password needed, using secret bytes from stdin"
		return 0 }

	if option_is_set -g; then
		_verbose "no password needed, using GPG key"
		get_lukskey
		return $?
	fi

	_message "A password is required to use key ::1 key::" $TOMBKEYFILE
	passok=0
	tombpass=""
	if [[ -z $1 ]]; then

		for c in 1 2 3; do
			if [[ $c == 1 ]]; then
				tombpass=$(ask_password "Insert password to: $TOMBKEYFILE")
			else
				tombpass=$(ask_password "Insert password to: $TOMBKEYFILE (attempt $c)")
			fi
			[[ $? = 0 ]] || {
				_warning "User aborted password dialog."
				return 1
			}

			get_lukskey "$tombpass"

			[[ $? = 0 ]] && {
				passok=1; _message "Password OK."
				break;
			}
		done

	else
		# if a second argument is present then the password is already known
		tombpass="$1"
		_verbose "ask_key_password with tombpass: ::1 tomb pass::" $tombpass

		get_lukskey "$tombpass"

		[[ $? = 0 ]] && {
			passok=1; _message "Password OK."
		}

	fi
	[[ $passok == 1 ]] || return 1

	TOMBPASSWORD=$tombpass
	return 0
}

# call cryptsetup with arguments using the currently known secret
# echo flags eliminate newline and disable escape (BSD_ECHO)
_cryptsetup() {
	if option_is_set -q; then
		print -R -n - "$TOMBSECRET" | _sudo cryptsetup --type luks1 --key-file - ${@} 2> /dev/null
	else
		print -R -n - "$TOMBSECRET" | _sudo cryptsetup --type luks1 --key-file - ${@}
	fi
	return $?
}

# change tomb key password
change_passwd() {
	local tmpnewkey lukskey c tombpass tombpasstmp

	_check_swap	 # Ensure swap is secure, if any
	_load_key	 # Try loading key from option -k and set TOMBKEYFILE

	{ option_is_set -g } && {
		_message "Commanded to change GnuPG key for tomb key ::1 key::" $TOMBKEYFILE
	} || {
		_message "Commanded to change password for tomb key ::1 key::" $TOMBKEYFILE
	}

	_tmp_create
	tmpnewkey=$TOMBTMP

	if option_is_set --tomb-old-pwd; then
		local tomboldpwd="`option_value --tomb-old-pwd`"
		_verbose "tomb-old-pwd = ::1 old pass::" $tomboldpwd
		ask_key_password "$tomboldpwd"
	else
		ask_key_password
	fi
	[[ $? == 0 ]] || _failure "No valid password supplied."

	{ option_is_set -g } && {
		_success "Changing GnuPG key for ::1 key file::" $TOMBKEYFILE
	} || {
		_success "Changing password for ::1 key file::" $TOMBKEYFILE
	}

	# Here $TOMBSECRET contains the key material in clear

	{ option_is_set --tomb-pwd } && {
		local tombpwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 new pass::" $tombpwd
		gen_key "$tmpnewkey" "$tombpwd"
	} || {
		gen_key "$tmpnewkey"
	}

	{ is_valid_key "${mapfile[$tmpnewkey]}" } || {
		_failure "Error: the newly generated keyfile does not seem valid." }

	# Copy the new key as the original keyfile name
	cp -f "${tmpnewkey}" $TOMBKEYFILE
	{ option_is_set -g } && {
		_success "Your GnuPG key was successfully changed"
	} || {
		_success "Your passphrase was successfully updated."
	}

	return 0
}


# takes care to encrypt a key
# honored options: --kdf  --tomb-pwd -o -g -r
gen_key() {
	# $1 key file
	# $2 the password to use; if not set ask user
	# -o is the --cipher-algo to use (string taken by GnuPG)
	local algopt="`option_value -o`"
	local algo="${algopt:-AES256}"
	local gpgpass opt
	local recipients_opt
	typeset -a gpgopt
	local sphx_host_tmp
	local sphx_user_tmp
	# here user is prompted for key password
	tombpass=""
	tombpasstmp=""

	if option_is_set -g; then
		gpgopt=(--encrypt)

		if option_is_set -r || option_is_set -R; then
			typeset -a recipients
			if option_is_set -r; then
				recipients=(${(s:,:)$(option_value -r)})
				recipients_opt="--recipient"
			else
				recipients=(${(s:,:)$(option_value -R)})
				recipients_opt="--hidden-recipient"
			fi

		    is_valid_recipients $recipients || {
				_failure "You set an invalid GPG ID."
			}

			_warning "You are going to encrypt a tomb key with ::1 nrecipients:: recipient(s)."	 ${#recipients}
			_warning "It is your responsibility to check these fingerprints."
			_warning "The fingerprints are:"
			for gpg_id in ${recipients[@]}; do
				_warning "	  `_gpg_fingerprint "$gpg_id"` :: `_gpg_uid "$gpg_id"`"
			done

			gpgopt+=(`_recipients_arg "$recipients_opt" $recipients`)
		else
			_message "No recipient specified, using default GPG key."
			gpgopt+=("--default-recipient-self")
		fi

		# Set gpg inputs and options
		gpgpass="$TOMBSECRET"
		opt=''
	else
		if [ "$2" = "" ]; then
			while true; do
				# 3 tries to write two times a matching password
				tombpass=`ask_password "Type the new password to secure your key"`
				if [[ $? != 0 ]]; then
					_failure "User aborted."
				fi
				if [ -z $tombpass ]; then
					_failure "You set empty password, which is not possible."
				fi
				tombpasstmp=$tombpass
				tombpass=`ask_password "Type the new password to secure your key (again)"`
				if [[ $? != 0 ]]; then
					_failure "User aborted."
				fi
				if [ "$tombpasstmp" = "$tombpass" ]; then
					break;
				fi
				unset tombpasstmp
				unset tombpass
			done
		else
			tombpass="$2"
			_verbose "gen_key takes tombpass from CLI argument: ::1 tomb pass::" $tombpass
		fi

		header=""
		[[ $KDF == 1 ]] && {
			{ option_is_set --kdf } && {
				# KDF is a new key strenghtening technique against brute forcing
				# see: https://github.com/dyne/Tomb/issues/82
				itertime="`option_value --kdf`"
				# removing support of floating points because they can't be type checked well
				# if [[ "$itertime" != <-> ]]; then
				# 	unset tombpass
				# 	unset tombpasstmp
				# 	_warning "Wrong argument for --kdf: must be an integer number (iteration seconds)."
				# 	_failure "Depending on the speed of machines using this tomb, use 1 to 10, or more"
				# 	return 1
				# fi
				# # --kdf takes one parameter: iter time (on present machine) in seconds

				kdftype="`option_value --kdftype`"
				kdftype=${kdftype:-pbkdf2}
				case ${kdftype} in
				    pbkdf2)
					local -i microseconds
					microseconds=$(( itertime * 1000000 ))
					_success "Using KDF, iteration time: ::1 microseconds::" $microseconds
					_message "generating salt"
					pbkdf2_salt=`tomb-kdb-pbkdf2-gensalt`
					_message "calculating iterations"
					pbkdf2_iter=`tomb-kdb-pbkdf2-getiter $microseconds`
					_message "encoding the password"
					# We use a length of 64bytes = 512bits (more than needed!?)
					tombpass=`tomb-kdb-pbkdf2 $pbkdf2_salt $pbkdf2_iter 64 <<<"${tombpass}"`

					header="_KDF_pbkdf2sha1_${pbkdf2_salt}_${pbkdf2_iter}_64\n"
					;;
				    argon2)
					_success "Using KDF Argon2"
					kdfmem="`option_value --kdfmem`"
					kdfmem=${kdfmem:-18}
					_message "memory used: 2^::1 kdfmemory::" $kdfmem
          itertime="`option_value --kdf`"
          itertime=${itertime:-3}
					kdfsalt=`tomb-kdb-pbkdf2-gensalt`
					_message "kdf salt: ::1 kdfsalt::" $kdfsalt
					_message "kdf iterations: ::1 kdfiterations::" $itertime
					tombpass=`argon2 $kdfsalt -m $kdfmem -t $itertime -l 64 -r <<<"${tombpass}"`
					header="_KDF_argon2_${kdfsalt}_${itertime}_${kdfmem}_64\n"
					;;
				esac
			}
		}
		print $header >> "$1"

		# Set gpg inputs and options
		gpgpass="${tombpass}\n$TOMBSECRET"
		gpgopt=(--passphrase-fd 0 --symmetric --no-options)
		opt='-n'
	fi

	_tmp_create
	local tmpres=$TOMBTMP
	print $opt - "$gpgpass" \
		| gpg --openpgp --force-mdc --cipher-algo ${algo} \
			  --batch --no-tty ${gpgopt} \
			  --status-fd 2 -o - --armor 2> $tmpres >> "$1"
	unset gpgpass
	# check result of gpg operation
	for i in ${(f)"$(cat $tmpres)"}; do
		_verbose "$i"
	done

	# print -n "${tombpass}" \
		#	  | gpg --openpgp --force-mdc --cipher-algo ${algo} \
		#	  --batch --no-options --no-tty --passphrase-fd 0 --status-fd 2 \
		#	  -o - -c -a ${lukskey}

	TOMBPASSWORD="$tombpass"	# Set global variable
	unset tombpass
	unset tombpasstmp
}

# prints an array of ciphers available in gnupg (to encrypt keys)
list_gnupg_ciphers() {
	# On gpg1 and gpg2 line 10 always point to available ciphers.
	# Print those until the next section is found
	ciphers=(`gpg --version | awk '
BEGIN { ciphers=0 }
NR==11 { gsub(/,/,""); sub(/^.*:/,""); print; ciphers=1; next }
/^.*:/ { ciphers=0 }
{ if(ciphers==0) { next } else { gsub(/,/,""); print; } }
'`)
	print "${ciphers}"
	return 1
}

# Steganographic function to bury a key inside an image.
# Requires steghide(1) to be installed
bury_key() {

	_load_key	 # Try loading key from option -k and set TOMBKEY

	imagefile=$PARAM

	[[ "`file $imagefile`" =~ "JPEG" ]] || {
		_warning "Encode failed: ::1 image file:: is not a jpeg image." $imagefile
		return 1
	}

	_success "Encoding key ::1 tomb key:: inside image ::2 image file::" $TOMBKEY $imagefile
	{ option_is_set -g } && {
		_message "Using GnuPG Key ID"
	} || {
		_message "Please confirm the key password for the encoding"
	}

	# We ask the password and test if it is the same encoding the
	# base key, to insure that the same password is used for the
	# encryption and the steganography. This is a standard enforced
	# by Tomb, but it isn't strictly necessary (and having different
	# password would enhance security). Nevertheless here we prefer
	# usability.
	# However, steganography cannot be done with GPG key. Therefore,
	# if using a GPG key, we test if the user can decrypt the tomb
	# with its key and we ask for a steganography password.

	{ option_is_set --tomb-pwd } && { ! option_is_set -g } && {
		local tombpwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 tomb pass::" $tombpwd
		ask_key_password "$tombpwd"
	} || {
		ask_key_password
	}
	[[ $? != 0 ]] && {
		_warning "Wrong password/GnuPG ID supplied."
		_failure "You shall not bury a key whose password is unknown to you." }

	if option_is_set -g && option_is_set --tomb-pwd; then
		TOMBPASSWORD="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 tomb pass::" $TOMBPASSWORD
	elif option_is_set -g; then
		tombpass=""
		tombpasstmp=""
		while true; do
			# 3 tries to write two times a matching password
			tombpass=`ask_password "Type a password to bury your key"`
			if [[ $? != 0 ]]; then
				_failure "User aborted."
			fi
			if [ -z $tombpass ]; then
				_failure "You set empty password, which is not possible."
			fi
			tombpasstmp=$tombpass
			tombpass=`ask_password "Type a password to bury your key (again)"`
			if [[ $? != 0 ]]; then
				_failure "User aborted."
			fi
			if [ "$tombpasstmp" = "$tombpass" ]; then
				break;
			fi
			unset tombpasstmp
			unset tombpass
		done
		TOMBPASSWORD="$tombpass"
	fi

	# We omit armor strings since having them as constants can give
	# ground to effective attacks on steganography
	print - "$TOMBKEY" | awk '
/^-----/ {next}
/^Version/ {next}
{print $0}' \
		| steghide embed --embedfile - --coverfile ${imagefile} \
				   -p $TOMBPASSWORD -z 9 -e serpent cbc
	if [ $? != 0 ]; then
		_warning "Encoding error: steghide reports problems."
		res=1
	else
		_success "Tomb key encoded succesfully into image ::1 image file::" $imagefile
		res=0
	fi

	return $res
}

# mandatory 1st arg: the image file where key is supposed to be
# optional 2nd arg: the password to use (same as key, internal use)
# optional 3rd arg: the key where to save the result (- for stdout)
exhume_key() {
	[[ -z $1 ]] && {
		_failure "Exhume failed, no image specified" }

	local imagefile="$1"  # The image file where to look for the key
	local tombpass="$2"	  # (Optional) the password to use (internal use)
	local destkey="$3"	  # (Optional) the key file where to save the
	# result (- for stdout)
	local r=1			  # Return code (default: fail)

	# write all messages to stderr to avoid polluting stdout
	_MSG_FD_OVERRIDE=2

	# Ensure the image file is a readable JPEG
	[[ ! -r $imagefile ]] && {
		_failure "Exhume failed, image file not found: ::1 image file::" "${imagefile:-none}" }
	[[ ! $(file "$imagefile") =~ "JP.G" ]] && {
		_failure "Exhume failed: ::1 image file:: is not a jpeg image." $imagefile }

	# When a password is passed as argument then always print out
	# the exhumed key on stdout without further checks (internal use)
	[[ -n "$tombpass" ]] && {
		TOMBKEY=$(steghide extract -sf $imagefile -p $tombpass -xf -)
		[[ $? != 0 ]] && {
			_failure "Wrong password or no steganographic key found" }

		recover_key $TOMBKEY

		return 0
	}

	# Ensure we have a valid destination for the key
	[[ -z $destkey ]] && { option_is_set -k } && destkey=$(option_value -k)
	[[ -z $destkey ]] && {
		destkey="-" # No key was specified: fallback to stdout
		_message "printing exhumed key on stdout" }

	# Bail out if destination exists, unless -f (force) was passed
	[[ $destkey != "-" && -s $destkey ]] && {
		_warning "File exists: ::1 tomb key::" $destkey
		{ option_is_set -f } && {
			_warning "Use of --force selected: overwriting."
			rm -f $destkey
		} || {
			_warning "Make explicit use of --force to overwrite."
			_failure "Refusing to overwrite file. Operation aborted." }
	}

	_message "Trying to exhume a key out of image ::1 image file::" $imagefile
	{ option_is_set --tomb-pwd } && {
		tombpass=$(option_value --tomb-pwd)
		_verbose "tomb-pwd = ::1 tomb pass::" $tombpass
	} || {
		[[ -n $TOMBPASSWORD ]] && tombpass=$TOMBPASSWORD
	} || {
		tombpass=$(ask_password "Insert password to exhume key from $imagefile")
		[[ $? != 0 ]] && {
			_warning "User aborted password dialog."
			return 1
		}
	}

	# Extract the key from the image
	steghide extract -sf $imagefile -p ${tombpass} -xf $destkey
	r=$?

	# Report to the user
	[[ "$destkey" = "-" ]] && destkey="stdout"
	[[ $r == 0 ]] && {
		_success "Key succesfully exhumed to ::1 key::." $destkey
	} || {
		_warning "Nothing found in ::1 image file::" $imagefile
	}

	unset _MSG_FD_OVERRIDE

	return $r
}

# Steganographic function to transform a key into harmless-looking text
# using a cipher
# Requires cloakify to be installed
#
# mandatory 1st arg: the cipher to use
# optional 2nd arg: the output file where to save the result (none for stdout)
cloakify_key() {

	_load_key	 # Try loading key from option -k and set TOMBKEY
	local cipher="$1"    # The cipher to use
	local destfile="$2"  # (Optional) the output file where to save the
	# result (none for stdout)
  [[ -r "${cipher}" ]] ||
    _failure "Cloak cipher file not found, see tomb/extras/cloak/ciphers"

	_success "Encoding key ::1 tomb key:: using cipher ::2 cipher file::" $TOMBKEYFILE $cipher

	# Ensure we have a valid destination for the cloaked key
	[[ -z $destfile ]] && {
		  destfile="/dev/stdout" # No file was specified: fallback to stdout
		  _message "printing cloaked key on stdout" }

	# Bail out if destination exists, unless -f (force) was passed
	[[ $destfile != "/dev/stdout" && -s $destfile ]] && {
		  _warning "File exists: ::1 output file::" $destfile
		  { option_is_set -f } && {
			    _warning "Use of --force selected: overwriting."
			    rm -f $destfile
		  } || {
			    _warning "Make explicit use of --force to overwrite."
			    _failure "Refusing to overwrite file. Operation aborted." }
	}

	# Cipher the key
	cloakify -i $TOMBKEYFILE -c $cipher >$destfile
	if [ $? != 0 ]; then
		_warning "Encoding error: cloakify reports problems."
		res=1
	else
		_success "Tomb key encoded succesfully"
		res=0
	fi

	return $res
}

# mandatory 1st arg: the text file where key is supposed to be
# mandatory 2nd arg: the cipher to use
# optional 3rd arg: the key where to save the result (none for stdout)
decloakify_key() {
	[[ -z $1 ]] && {
		  _failure "Uncloak failed, no text file specified" }
	[[ -z $2 ]] && {
		  _failure "Uncloak failed, no cipher file specified" }

	local textfile="$1"   # The text file where to look for the key
	local cipher="$2"     # The cipher to use
	local destkey="$3"    # (Optional) the key file where to save the
	# result (none for stdout)
	local r=1			  # Return code (default: fail)

	# write all messages to stderr to avoid polluting stdout
	_MSG_FD_OVERRIDE=2

	# Ensure the text file is readable
	[[ ! -r $textfile ]] && {
		_failure "Uncloak failed, text file not found: ::1 text file::" "${textfile:-none}" }
	# Ensure the cipher file is readable
	[[ ! -r $cipher ]] && {
		_failure "Uncloak failed, cipher file not found: ::1 cipher file::" "${cipher:-none}" }

	# Ensure we have a valid destination for the key
	[[ -z $destkey ]] && { option_is_set -k } && destkey=$(option_value -k)
	[[ -z $destkey ]] && {
		# No key was specified: fallback to stdout
		_message "printing uncloaked key on stdout" }

	# Bail out if destination exists, unless -f (force) was passed
	[[ $destkey != "/dev/stdout" && -s $destkey ]] && {
		_warning "File exists: ::1 tomb key::" $destkey
		{ option_is_set -f } && {
			_warning "Use of --force selected: overwriting."
			rm -f $destkey
		} || {
			_warning "Make explicit use of --force to overwrite."
			_failure "Refusing to overwrite file. Operation aborted." }
	}

	# Extract the key from the text file
  if [[ -z "$destkey" ]]; then
	  decloakify -i "${textfile}" -c "${cipher}"
  else
	  decloakify -i "${textfile}" -c "${cipher}" -o "${destkey}"
  fi
	r=$?

	# Report to the user
	[[ -z "$destkey" ]] && destkey="stdout"
	[[ $r == 0 ]] && {
		_success "Key succesfully uncloaked to ::1 key::." $destkey
	} || {
		_warning "Nothing found in ::1 text file::" $textfile
	}

	unset _MSG_FD_OVERRIDE

	return $r
}

# Produces a printable image of the key contents so a backup on paper
# can be made and hidden in books etc.
engrave_key() {

	_load_key	 # Try loading key from option -k and set TOMBKEYFILE

	local keyname=$(basename $TOMBKEYFILE)
	local pngname="$keyname.qr.png"

	_success "Rendering a printable QRCode for key: ::1 tomb key file::" $TOMBKEYFILE
	# we omit armor strings to save space
	awk '/^-----/ {next}; /^Version/ {next}; {print $0}' $TOMBKEYFILE \
		| qrencode --size 4 --level H --casesensitive -o $pngname
	[[ $? != 0 ]] && {
		_failure "QREncode reported an error." }

	_success "Operation successful:"
	# TODO: only if verbose and/or not silent
	ls -lh $pngname
	file $pngname
}

# }}} - Key handling

# {{{ Create

# Since version 1.5.3, tomb creation is a three-step process that replaces create_tomb():
#
# * dig a .tomb (the large file) using /dev/urandom (takes some minutes at least)
#
# * forge a .key (the small file) using /dev/random (good entropy needed)
#
# * lock the .tomb file with the key, binding the key to the tomb (requires dm_crypt format)

# Step one - Dig a tomb
#
# Synopsis: dig_tomb /path/to/tomb -s sizemebibytes
#
# It will create an empty file to be formatted as a loopback
# filesystem.  Initially the file is filled with random data taken
# from /dev/urandom to improve overall tomb's security and prevent
# some attacks aiming at detecting how much data is in the tomb, or
# which blocks in the filesystem contain that data.

dig_tomb() {
	# $1 arg is path to tomb

	# Require the specification of the size of the tomb (-s) in MiB
	local -i tombsize=$(option_value -s)

	_message "Commanded to dig tomb ::1 tomb path::" $tombpath

	[[ ! -z $1 ]] || _failure "Missing path to tomb"
	[[ -n "$tombsize"	]] || _failure "Size argument missing, use -s"
	[[ $tombsize == <-> ]] || _failure "Size must be an integer (mebibytes)"
	[[ $tombsize -ge 10 ]] || _failure "Tombs can't be smaller than 10 mebibytes"

	[[ -e $1 ]] && {
		_warning "A tomb exists already. I'm not digging here:"
		ls -lh $1
		return 1
	}

	_success "Creating a new tomb in ::1 tomb path::" $1
	_message "Generating ::1 tomb file:: of ::2 size::MiB" $1 $tombsize

	touch "$1"
	[[ $? = 0 ]] || {
		_warning "Error creating the tomb ::1 tomb path::" $1
		_failure "Operation aborted."
	}
	# Ensure that file permissions are safe even if interrupted
	[[ -n $SUDO_USER ]] && chown ${_UID}:${_GID} "$1"
	chmod 0600 $1
	_verbose "Data dump using ::1:: from /dev/urandom" ${DD[1]}
	${=DD} if=/dev/urandom bs=1048576 count=$tombsize of=$1
	ls -lh "$1"

	_success "Done digging ::1 tomb name::" $1
	_message "Your tomb is not yet ready, you need to forge a key and lock it:"
	_message "tomb forge ::1 tomb path::.key" $1
	_message "tomb lock ::1 tomb path:: -k ::1 tomb path::.key" $1

	return 0
}

# Step two -- Create a detached key to lock a tomb with
#
# Synopsis: forge_key [destkey|-k destkey] [-o cipher] [-r|-R gpgid]
#
# Arguments:
# -k				path to destination keyfile
# -o				Use an alternate algorithm
# -r				GPG recipients to be used
#
forge_key() {
	# can be specified both as simple argument or using -k
	local destkey="$1"
	{ option_is_set -k } && { destkey=$(option_value -k) }

	local algo="AES256"	 # Default encryption algorithm

	[[ -z "$destkey" ]] && {
		_failure "A filename needs to be specified using -k to forge a new key." }

	#	 _message "Commanded to forge key ::1 key::" $destkey

	_check_swap # Ensure the available memory is safe to use

	# Ensure GnuPG won't exit with an error before first run
	local gpghome=${GNUPGHOME:-$HOME/.gnupg}
	[[ -r $gpghome/pubring.gpg ]] || {
        mkdir -p -m 0700 $gpghome
        touch $gpghome/pubring.gpg }

	# Do not overwrite any files accidentally
	[[ -r "$destkey" ]] && {
		ls -lh $destkey
		_failure "Forging this key would overwrite an existing file. Operation aborted." }

	touch $destkey
	[[ $? == 0 ]] || {
		_warning "Cannot generate encryption key."
		_failure "Operation aborted." }
	chmod 0600 $destkey

	# Update algorithm if it was passed on the command line with -o
	{ option_is_set -o } && algopt="$(option_value -o)"
	[[ -n "$algopt" ]] && algo=$algopt

	_message "Commanded to forge key ::1 key:: with cipher algorithm ::2 algorithm::" \
			 $destkey $algo

	[[ $KDF == 1 ]] && { ! option_is_set -g } && {
		_message "Using KDF to protect the key password (`option_value --kdf` rounds)"
	}

	TOMBKEYFILE="$destkey"	  # Set global variable

	_warning "This operation takes time. Keep using this computer on other tasks."
	_warning "Once done you will be asked to choose a password for your tomb."
	_warning "To make it faster you can move the mouse around."
	_warning "If you are on a server, you can use an Entropy Generation Daemon."

	# Use /dev/urandom as the entropy source, unless --use-random is specified
	local random_source=/dev/urandom
	{ option_is_set --use-random } && random_source=/dev/random

	_verbose "Data dump using ::1:: from ::2 source::" ${DD[1]} $random_source
	TOMBSECRET=$(${=DD} bs=1 count=512 if=$random_source)
	[[ $? == 0 ]] || {
		_warning "Cannot generate encryption key."
		_failure "Operation aborted." }

	# Here the global variable TOMBSECRET contains the naked secret

	{ option_is_set -g } && {
		_success "Using GnuPG key(s) to encrypt your key: ::1 tomb key::" $TOMBKEYFILE
	} || {
		_success "Choose the password of your key: ::1 tomb key::" $TOMBKEYFILE
	}
	_message "(You can also change it later using 'tomb passwd'.)"
	# _user_file $TOMBKEYFILE

	tombname="$TOMBKEYFILE" # XXX ???
	# the gen_key() function takes care of the new key's encryption
	{ option_is_set --tomb-pwd } && {
		local tombpwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 new pass::" $tombpwd
		gen_key $TOMBKEYFILE "$tombpwd"
	} || {
		gen_key $TOMBKEYFILE
	}

	# load the key contents (set global variable)
	TOMBKEY="${mapfile[$TOMBKEYFILE]}"

	# this does a check on the file header
	is_valid_key $TOMBKEY || {
		_warning "The key does not seem to be valid."
		_warning "Dumping contents to screen:"
		print "${mapfile[$TOMBKEY]}"
		_warning "--"
		rm -f ${TOMBKEYFILE}
		_failure "Operation aborted."
	}

	[[ -n $SUDO_USER ]] && chown ${_UID}:${_GID} "$TOMBKEYFILE"
	_message "Done forging ::1 key file::" $TOMBKEYFILE
	_success "Your key is ready:"
	ls -lh $TOMBKEYFILE
}

# Step three -- Lock tomb
#
# Synopsis: tomb_lock file.tomb file.tomb.key [-o cipher] [-r gpgid]
#
# Lock the given tomb with the given key file, in fact formatting the
# loopback volume as a LUKS device.
# Default cipher 'aes-xts-plain64'can be overridden with -o
lock_tomb_with_key() {
	# old default was aes-cbc-essiv:sha256
	# Override with -o
	# for more alternatives refer to cryptsetup(8)
	local cipher="aes-xts-plain64"

	local tombpath="$1"		 # First argument is the path to the tomb

	[[ -n $tombpath ]] || {
		_warning "No tomb specified for locking."
		_warning "Usage: tomb lock file.tomb -k file.tomb.key"
		return 1
	}


	is_valid_tomb $tombpath

	_message "Commanded to lock tomb ::1 tomb file::" $TOMBFILE

	[[ -f $TOMBPATH ]] || {
		_failure "There is no tomb here. You have to dig it first." }

	_verbose "Tomb found: ::1 tomb path::" $TOMBPATH

	local filesystem=ext4
	option_is_set --filesystem && {
		filesystem=`option_value --filesystem`
		local tombsize=`stat --format '%s' $tombpath`
		case $filesystem in
			ext3|ext4) ;;
			ext3maxinodes|ext4maxinodes) ;;
			btrfs)
				if [[ $tombsize -lt 114294784 ]]; then
					_failure "Filesystem ::1 filesystem:: not supported on tombs smaller than ::2 size::" \
						 $filesystem "114MB"
				fi
				;;
			btrfsmixedmode)
				if [[ $tombsize -lt 18874368 ]]; then
					_failure "Filesystem ::1 filesystem:: not supported on tombs smaller than ::2 size::" \
						 $filesystem "18MB"
				fi
				;;
			*)
				_failure "Filesystem not supported: ::1 filesystem::" $filesystem
				return 1
				;;
		esac
		_success "Selected filesystem type $filesystem."
	}

	lo_check "$TOMBPATH"

	_message "Checking if the tomb is empty (we never step on somebody else's bones)."
	_sudo cryptsetup isLuks ${TOMBPATH}
	if [ $? = 0 ]; then
		# is it a LUKS encrypted nest? then bail out and avoid reformatting it
		_warning "The tomb was already locked with another key."
		_failure "Operation aborted. I cannot lock an already locked tomb. Go dig a new one."
	else
		_message "Fine, this tomb seems empty."
	fi

	_load_key	 # Try loading key from option -k and set TOMBKEYFILE

	# the encryption cipher for a tomb can be set when locking using -c
	{ option_is_set -o } && algopt="$(option_value -o)"
	[[ -n "$algopt" ]] && cipher=$algopt
	_message "Locking using cipher: ::1 cipher::" $cipher

	# get the pass from the user and check it
	if option_is_set --tomb-pwd; then
		tomb_pwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 tomb pass::" $tomb_pwd
		ask_key_password "$tomb_pwd"
	else
		ask_key_password
	fi
	[[ $? == 0 ]] || _failure "No valid password supplied."

	_success "Locking ::1 tomb file:: with ::2 tomb key file::" $TOMBFILE $TOMBKEYFILE

	_message "Formatting Luks mapped device."
	_cryptsetup --batch-mode \
				--cipher ${cipher} --hash sha512 --key-size 512 --key-slot 0 \
				luksFormat ${TOMBPATH}
	[[ $? == 0 ]] || {
		_warning "cryptsetup luksFormat returned an error."
		_failure "Operation aborted." }

	_cryptsetup --cipher ${cipher} --hash sha512 luksOpen ${TOMBPATH} tomb.tmp
	[[ $? == 0 ]] || {
		_warning "cryptsetup luksOpen returned an error."
		_failure "Operation aborted." }

	_message "Formatting your Tomb with $filesystem filesystem."
	case $filesystem in
		ext3|ext4)
			_sudo mkfs.${filesystem} -q -F -j -L $TOMBNAME /dev/mapper/tomb.tmp
			;;
		ext3maxinodes|ext4maxinodes) # TODO: cover with test
			filesystem=${filesystem:0:4}
			_sudo mkfs.${filesystem} -q -F -j -i 1024 -b 1024 -L $TOMBNAME /dev/mapper/tomb.tmp
			;;
		btrfs) # TODO: cover with test
			_sudo mkfs.${filesystem} -q -L $TOMBNAME /dev/mapper/tomb.tmp
			;;
		btrfsmixedmode) # TODO: cover with test
			filesystem=${filesystem:0:5}
			_sudo mkfs.${filesystem} -q -M -L $TOMBNAME /dev/mapper/tomb.tmp
			;;
	esac

	[[ $? == 0 ]] || {
		_warning "Tomb format returned an error."
		_sudo cryptsetup luksClose tomb.tmp
		_failure "Your tomb ::1 tomb file:: may be corrupted." $TOMBFILE }

	# Sync
	_sudo cryptsetup luksClose tomb.tmp

	_message "Done locking ::1 tomb name:: using Luks dm-crypt ::2 cipher::" $TOMBNAME $cipher
	_success "Your tomb is ready in ::1 tomb path:: and secured with key ::2 tomb key::" \
			 $TOMBPATH $TOMBKEYFILE
	return 0
}

# This function changes the key that locks a tomb
change_tomb_key() {
	local tombkey="$1"		# Path to the tomb's key file
	local tombpath="$2"		# Path to the tomb

	_message "Commanded to reset key for tomb ::1 tomb path::" $tombpath

	[[ -z "$tombpath" ]] && {
		_warning "Command 'setkey' needs two arguments: the old key file and the tomb."
		_warning "I.e:	tomb -k new.tomb.key old.tomb.key secret.tomb"
		_failure "Execution aborted."
	}

	_check_swap

	is_valid_tomb $tombpath
	lo_check "$TOMBPATH"
	_sudo cryptsetup isLuks ${TOMBPATH}
	# is it a LUKS encrypted nest? we check one more time
	[[ $? == 0 ]] || {
		_failure "Not a valid LUKS encrypted volume: ::1 volume::" $TOMBPATH }

	_load_key $tombkey	  # Try loading given key and set TOMBKEY


	# TOMBKEYFILE
	local oldkey=$TOMBKEY
	local oldkeyfile=$TOMBKEYFILE

	# we have everything, prepare to mount
	_success "Changing lock on tomb ::1 tomb name::" $TOMBNAME
	_message "Old key: ::1 old key::" $oldkeyfile

	# load the old key
	if option_is_set --tomb-old-pwd; then
		tomb_old_pwd="`option_value --tomb-old-pwd`"
		_verbose "tomb-old-pwd = ::1 old pass::" $tomb_old_pwd
		ask_key_password "$tomb_old_pwd"
	else
		ask_key_password
	fi
	[[ $? == 0 ]] || {
		_failure "No valid password supplied for the old key." }
	old_secret=$TOMBSECRET

	# luksOpen the tomb (not really mounting, just on the loopback)
	print -R -n - "$old_secret" | _sudo cryptsetup --key-file - \
										luksOpen ${TOMBPATH} ${TOMBMAPPER}
	[[ $? == 0 ]] || _failure "Unexpected error in luksOpen."

	_load_key # Try loading new key from option -k and set TOMBKEYFILE

	_message "New key: ::1 key file::" $TOMBKEYFILE

	if option_is_set --tomb-pwd; then
		tomb_new_pwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 tomb pass::" $tomb_new_pwd
		ask_key_password "$tomb_new_pwd"
	else
		ask_key_password
	fi
	[[ $? == 0 ]] || {
		_failure "No valid password supplied for the new key." }

	_tmp_create
	tmpnewkey=$TOMBTMP
	print -R -n - "$TOMBSECRET" >> $tmpnewkey

	print -R -n - "$old_secret" | _sudo cryptsetup --key-file - \
										luksChangeKey "$TOMBPATH" "$tmpnewkey"

	[[ $? == 0 ]] || _failure "Unexpected error in luksChangeKey."

	_sudo cryptsetup luksClose "${TOMBMAPPER}" || _failure "Unexpected error in luksClose."

	_success "Successfully changed key for tomb: ::1 tomb file::" $TOMBFILE
	_message "The new key is: ::1 new key::" $TOMBKEYFILE

	return 0
}

# }}} - Creation

# {{{ Open

_update_control_file() {
	# make sure a control file exists, gives it user ownership
	# and replaces it with new contents
	# stdin = contents
	# $1 = path to control file
	# $2 = contents
	[[ -z $2 ]] && return 1
	_sudo touch "$1"
	_sudo chown ${_UID}:${_GID} "$1"
	print "$2" > "$1"
	_verbose "updated control file $1 = $2"
}

_detect_filesystem() {
	local device=$1
	_verbose "detecting filesystem of ::1 device::" $device
	print "`lsblk -in -o FSTYPE $device`"
}

# $1 = tombfile $2(optional) = mountpoint
mount_tomb() {
	[[ -n "$1" ]] || _failure "No tomb name specified for opening."

	_message "Commanded to open tomb ::1 tomb name::" $1

	_check_swap

	is_valid_tomb $1

	_track_stat "$TOMBPATH"

	_load_key # Try loading new key from option -k and set TOMBKEYFILE

	tombmount="$2"
	[[ -z "$tombmount" ]] && {
		tombmount="/media/$TOMBNAME"
		[[ -d /media ]] || { # no /media found, adopting /run/media/$USER (udisks2 compat)
			tombmount="/run/media/$_USER/$TOMBNAME"
		}
		_message "Mountpoint not specified, using default: ::1 mount point::" "$tombmount"
	}

	_success "Opening ::1 tomb file:: on ::2 mount point::" $TOMBNAME "$tombmount"

	# check if the mountpoint is already used
	mounted_tombs=(`list_tomb_mounts`)
	for t in ${mounted_tombs}; do
		usedmount=${t[(ws:;:)2]}
		[[ "$usedmount" == "$tombmount" ]] &&
			_failure "Mountpoint already in use: ::1 mount point::" "$tombmount"
	done


	lo_check "$TOMBPATH"
	_sudo cryptsetup isLuks ${TOMBPATH} || {
		# is it a LUKS encrypted nest? see cryptsetup(1)
		_failure "::1 tomb file:: is not a valid Luks encrypted storage file." $TOMBFILE }

	_message "This tomb is a valid LUKS encrypted device."

	luksdump="`_sudo cryptsetup luksDump ${TOMBPATH}`"
	tombdump=(`print $luksdump | awk '
		/^Cipher name/ {print $3}
		/^Cipher mode/ {print $3}
		/^Hash spec/   {print $3}'`)
	_message "Cipher is \"::1 cipher::\" mode \"::2 mode::\" hash \"::3 hash::\"" $tombdump[1] $tombdump[2] $tombdump[3]

	slotwarn=`print $luksdump | awk '
		BEGIN { zero=0 }
		/^Key slot 0/ { zero=1 }
		/^Key slot.*ENABLED/ { if(zero==1) print "WARN" }'`
	[[ "$slotwarn" == "WARN" ]] && {
		_warning "Multiple key slots are enabled on this tomb. Beware: there can be a backdoor." }

	_verbose "Tomb key: ::1 key file::" $TOMBKEYFILE

	# take the name only, strip extensions
	_verbose "Tomb name: ::1 tomb name:: (to be engraved)" $TOMBNAME

	{ option_is_set --tomb-pwd } && { ! option_is_set -g } && {
		tomb_pwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 tomb pass::" $tomb_pwd
		ask_key_password "$tomb_pwd"
	} || {
		ask_key_password
	}
	[[ $? == 0 ]] || _failure "No valid password supplied."

	_cryptsetup luksOpen ${TOMBPATH} ${TOMBMAPPER}
	[[ $? = 0 ]] || {
		_failure "Failure mounting the encrypted file." }

	# array: [ cipher, keysize, loopdevice ]
	tombstat=(`_sudo cryptsetup status ${TOMBMAPPER} | awk '
	/cipher:/  {print $2}
	/keysize:/ {print $2}
	/device:/  {print $2}'`)
	_success "Success unlocking tomb ::1 tomb name::" $TOMBNAME
	_verbose "Key size is ::1 size:: for cipher ::2 cipher::" $tombstat[2] $tombstat[1]

	filesystem=`_detect_filesystem /dev/mapper/${TOMBMAPPER}`
	_message "Filesystem detected: ::1 filesystem::" $filesystem
	# TODO: check if FS is supported, else close luks

	_verbose "Tomb engraved as ::1 tomb name::" $TOMBNAME

	if option_value_contains -o ro; then
		_message "Skipping filesystem checks in read-only"
	else
		_message "Checking filesystem via ::1::" $tombstat[3]
		case $filesystem in
			ext3|ext4)
				if option_is_set -q; then
					_sudo fsck -p -C0 /dev/mapper/${TOMBMAPPER} > /dev/null
				else
					_sudo fsck -p -C0 /dev/mapper/${TOMBMAPPER}
				fi
				# TODO:     btrfs filesystem label [<device>|<mount_point>] [<newlabel>]
				_sudo tune2fs -L $TOMBNAME /dev/mapper/${TOMBMAPPER} > /dev/null
				;;
			btrfs)
				_sudo btrfs check /dev/mapper/${TOMBMAPPER}
				_sudo btrfs filesystem label /dev/mapper/${TOMBMAPPER} ${TOMBNAME}
				;;
		esac
	fi

	# we need root from here on
	_sudo mkdir -p "$tombmount"

	# Default mount options are overridden with the -o switch
	{ option_is_set -o } && {
		local oldmountopts=$MOUNTOPTS
		MOUNTOPTS="$(option_value -o)" }
	# TODO: safety check MOUNTOPTS
	# safe_mount_options &&
	_sudo mount -o $MOUNTOPTS /dev/mapper/${TOMBMAPPER} "${tombmount}"
	# Clean up if the mount failed
	[[ $? == 0 ]] || {
		_warning "Error mounting ::1 mapper:: on ::2 tombmount::" $TOMBMAPPER "$tombmount"
		[[ $oldmountopts != $MOUNTOPTS ]] && \
			_warning "Are mount options '::1 mount options::' valid?" $MOUNTOPTS
		# TODO: move cleanup to _endgame()
		[[ -d "$tombmount" ]] && _sudo rmdir "$tombmount"
		[[ -e /dev/mapper/$TOMBMAPPER ]] && _sudo cryptsetup luksClose $TOMBMAPPER
		_failure "Cannot mount ::1 tomb name::" $TOMBNAME
	}

	_success "Success opening ::1 tomb file:: on ::2 mount point::" $TOMBFILE "$tombmount"
	local tombtty tombhost tombuid tombuser

	# print out when it was opened the last time, by whom and where
	[[ -r "${tombmount}/.last" ]] && {
		tombsince=$(cat "${tombmount}/.last")
		tombsince=$(date --date=@$tombsince +%c)
		tombtty=$(cat "${tombmount}/.tty")
		tombhost=$(cat "${tombmount}/.host")
		tomblast=$(cat "${tombmount}/.last")
		tombuid=$(cat "${tombmount}/.uid" | tr -d ' ')

		tombuser=`_get_username $tombuid`

		_message "Last visit by ::1 user::(::2 tomb build::) from ::3 tty:: on ::4 host::" $tombuser $tombuid $tombtty $tombhost
		_message "on date ::1 date::" $tombsince
		[[ -r "${tombmount}"/.cleanexit ]] || _message "the door was slammed or shutdown called before umount."
	}

	# write down the UID and TTY that opened the tomb
	option_value_contains -o ro || {
		_update_control_file "${tombmount}/.uid" $_UID
		_update_control_file "${tombmount}/.tty" $_TTY
		# also the hostname
		if command -v hostname >/dev/null; then
			_update_control_file "${tombmount}/.host" `hostname`
		elif [[ -r /etc/hostname ]]; then
			_update_control_file "${tombmount}/.host" $(cat /etc/hostname)
		else
			_update_control_file "${tombmount}/.host" localhost
		fi
		# and the "last time opened" information
		# in minutes since 1970, this is printed at next open
		_update_control_file "${tombmount}/.last" `date +%s`
		# human readable: date --date=@"`cat .last`" +%c
	}
	# process bind-hooks (mount -o bind of directories)
	# and exec-hooks (execute on open)
	option_is_set -n || {
		exec_safe_bind_hooks "${tombmount}"
		exec_safe_func_hooks open "${tombmount}"
	}

	# Changes ownership to current user. This facilitates a lot
	# usability by single users. If a Tomb is opened read-only or it
	# is "multiuser" and contains ACL "by convention" using UNIX
	# ownership that needs to be preserved, then this behavior can be
	# deactivated using -p
	local dochown=true
	option_value_contains -o ro && dochown=false
	option_is_set -p            && dochown=false
	$dochown && _sudo chown -R ${_UID}:${_GID} "${tombmount}"

	return 0
}

## HOOKS EXECUTION
#
# Execution of code inside a tomb may present a security risk, e.g.,
# if the tomb is shared or compromised, an attacker could embed
# malicious code.  When in doubt, open the tomb with the -n switch in
# order to skip this feature and verify the files mount-hooks and
# bind-hooks inside the tomb yourself before letting them run.

# Mount files and directories from the tomb to the current user's HOME.
#
# Synopsis: exec_safe_bind_hooks /path/to/mounted/tomb
#
# This can be a security risk if you share tombs with untrusted people.
# In that case, use the -n switch to turn off this feature.
exec_safe_bind_hooks() {
	local mnt="$1"	 # First argument is the mount point of the tomb

	# Default mount options are overridden with the -o switch
	[[ -n ${(k)OPTS[-o]} ]] && MOUNTOPTS=${OPTS[-o]}

	# No HOME set? Note: this should never happen again.
	[[ -z $HOME ]] && {
		_warning "How pitiful!	A tomb, and no HOME."
		return 1 }

	[[ -z $mnt || ! -d $mnt ]] && {
		_warning "Cannot exec bind hooks without a mounted tomb."
		return 1 }

	[[ -r "$mnt/bind-hooks" ]] || {
		_verbose "bind-hooks not found in ::1 mount point::" $mnt
		return 0 }

	typeset -Al maps		# Maps of files and directories to mount
	typeset -al mounted		# Track already mounted files and directories

	# better parsing for bind hooks checks for two separated words on
	# each line, using zsh word separator array subscript
	_bindhooks="${mapfile[${mnt}/bind-hooks]}"
	for h in ${(f)_bindhooks}; do
		h=${h//\\ /__ESC_SPACE__}
		s="${h[(w)1]}"
		d="${h[(w)2]}"
		s=${s//__ESC_SPACE__/ }
		d=${d//__ESC_SPACE__/ }
		[[ -z $s ]] && { _warning "bind-hooks file is broken"; return 1 }
		[[ -z $d ]] && { _warning "bind-hooks file is broken"; return 1 }
		maps+=($s $d)
		_verbose "bind-hook found: $s -> $d"
	done
	unset _bindhooks

	for dir in ${(k)maps}; do
		[[ "${dir[1]}" == "/" || "${dir[1,2]}" == ".." ]] && {
			_warning "bind-hooks map format: local/to/tomb local/to/\$HOME"
			continue }

		[[ "${${maps[$dir]}[1]}" == "/" || "${${maps[$dir]}[1,2]}" == ".." ]] && {
			_warning "bind-hooks map format: local/to/tomb local/to/\$HOME.	 Rolling back"
			for dir in ${mounted}; do _sudo umount $dir; done
			return 0 }

		while true; do
			[[ ! -r "$mnt/$dir" ]] && {
				_warning "bind-hook source not found in tomb, skipping ::1 mount point::/::2 subdir::" $mnt $dir
				break; }
			[[ ! -r "$HOME/${maps[$dir]}" ]] && {
				_warning "bind-hook target not existent, skipping ::1 home::/::2 subdir::" $HOME ${maps[$dir]}
				break; }
			_sudo mount -o bind,$MOUNTOPTS \
			      $mnt/$dir $HOME/${maps[$dir]} \
				&& mounted+=("$HOME/${maps[$dir]}")
			break
		done
	done
}

# Execute automated actions configured in the tomb.
#
# Synopsis: exec_safe_func_hooks /path/to/mounted/tomb
#
# If an executable file named 'exec-hooks' is found inside the tomb,
# run it as a user.	 This might need a dialog for security on what is
# being run, however we expect you know well what is inside your tomb.
# If you're mounting an untrusted tomb, be safe and use the -n switch
# to verify what it would run if you let it.  This feature opens the
# possibility to make encrypted executables.
exec_safe_func_hooks() {
	local mnt
	mnt="$2"
	# Only run if post-hooks has the executable bit set
	[[ -x $mnt/exec-hooks ]] && {
		_success "Exec hook: ::1 exec hook:: ::2 action::" \
				 "${mnt}/exec-hooks" "$1"
		# here call two actions: open or close. Synopsis:
		# $1	 $2			  $3		  $4		  $5
		# open	"$tombmount"
		# close "$tombmount" "$tombname" "$tombloop" "$TOMBMAPPER"
		$mnt/exec-hooks "$1" "$2" "$3" "$4" "$5"
		return $?
	}
	return 0
}

# }}} - Tomb open

# {{{ List

# list all tombs mounted in a readable format
# $1 is optional, to specify a tomb
list_tombs() {

	local tombname tombmount tombfs tombfsopts tombloop
	local ts tombtot tombused tombavail tombpercent tombp tombsince
	local tombtty tombhost tombuid tombuser
	# list all open tombs
	mounted_tombs=(`list_tomb_mounts $1`)
	[[ ${#mounted_tombs} == 0 ]] && {
		_failure "I can't see any open tomb, may they all rest in peace." }

	for t in ${mounted_tombs}; do
		mapper=`basename ${t[(ws:;:)1]}`
		tombname=${t[(ws:;:)5]}
		tombmount="${t[(ws:;:)2]}"
		tombfs=${t[(ws:;:)3]}
		tombfsopts=${t[(ws:;:)4]}
		tombloop=${mapper[(ws:.:)4]}

		# calculate tomb size
		ts=`df -hP /dev/mapper/$mapper |
awk "/mapper/"' { print $2 ";" $3 ";" $4 ";" $5 }'`
		tombtot=${ts[(ws:;:)1]}
		tombused=${ts[(ws:;:)2]}
		tombavail=${ts[(ws:;:)3]}
		tombpercent=${ts[(ws:;:)4]}
		tombp=${tombpercent%%%}

		# obsolete way to get the last open date from /dev/mapper
		# which doesn't work when tomb filename contain dots
		# tombsince=`date --date=@${mapper[(ws:.:)3]} +%c`

		# find out who opens it from where
		[[ -r "${tombmount}/.tty" ]] && {
			tombsince=$(cat "${tombmount}/.last")
			tombsince=$(date --date=@$tombsince +%c)
			tombtty=$(cat "${tombmount}/.tty")
			tombhost=$(cat "${tombmount}/.host")
			tombuid=$(cat "${tombmount}/.uid" | tr -d ' ')

			tombuser=`_get_username $tombuid`
		}

		{ option_is_set --get-mountpoint } && { print "$tombmount"; continue }

		_message "::1 tombname:: open on ::2 tombmount:: using ::3 tombfsopts::" \
				 $tombname "$tombmount" $tombfsopts

		_verbose "::1 tombname:: attached to /dev/::2 tombloop:: device" $tombname $tombloop

		_message "::1 tombname:: open since ::2 tombsince::" $tombname $tombsince

		[[ -z "$tombtty" ]] || {
			_message "::1 tombname:: open by ::2 tombuser:: from ::3 tombtty:: on ::4 tombhost::" \
					 $tombname $tombuser $tombtty $tombhost
		}

		_message "::1 tombname:: size ::2 tombtot:: of which ::3 tombused:: (::5 tombpercent::%) is used: ::4 tombavail:: free " \
				 $tombname $tombtot $tombused $tombavail $tombpercent

		[[ ${tombp} -ge 90 ]] && {
			_warning "::1 tombname:: warning: your tomb is almost full!" $tombname
		}

		# Now check hooks
		mounted_hooks=(`list_tomb_binds "$mapper"`)
		for h in ${mounted_hooks}; do
			_message "::1 tombname:: hooks ::2 hookdest::" \
					 $tombname ${h[(ws:;:)2]}
		done
	done
	return 0
}


# Print out an array of mounted tombs (internal use)
# Format is semi-colon separated list of attributes
# if 1st arg is supplied, then list only that tomb
#
# String positions in the semicolon separated array:
#
# 1. full mapper path
#
# 2. mountpoint
#
# 3. filesystem type
#
# 4. mount options
#
# 5. tomb name
list_tomb_mounts() {
	# execute in subshell to avoid ZSH non-POSIX behaviour if globbing doesn't match something
	( for dev in /dev/mapper/tomb*$1.*; do
		findmnt --source ${dev} -rnvo SOURCE,TARGET,FSTYPE,OPTIONS,LABEL \
			| awk '
BEGIN { main="" }
{
  if(main==$1) next;
  print $1 ";" $2 ";" $3 ";(" $4 ");[" $5 "]"
  main=$1
}
'
	done ) 2>/dev/null
}

# list_tomb_binds
# print out an array of mounted bind hooks (internal use)
# format is semi-colon separated list of attributes
# needs two arguments: name of tomb whose hooks belong
#					   mount tomb
list_tomb_binds() {
	[[ -z "$1" ]] && {
		_failure "Internal error: list_tomb_binds called without argument." }

	# ignore the first line of the result for the respective source (mapper),
	# as this will be the canonical first mount (aka main mount)
	findmnt --source=/dev/mapper/"$1" -rno SOURCE,TARGET,FSTYPE,OPTIONS,LABEL \
		| awk '
FNR==1 {next}
{
  print $1 ";" $2 ";" $3 ";(" $4 ");[" $5 "]"
}
'
}

# }}} - Tomb list

# {{{ Index and search

# index files in all tombs for search
# $1 is optional, to specify a tomb
index_tombs() {
	mounted_tombs=(`list_tomb_mounts $1`)
	[[ ${#mounted_tombs} == 0 ]] && {
		# Considering one tomb
		[[ -n "$1" ]] && {
			_failure "There seems to be no open tomb engraved as [::1::]" $1 }
		# Or more
		_failure "I can't see any open tomb, may they all rest in peace." }

	_success "Creating and updating search indexes."

	# # start the LibreOffice document converter if installed
	# { command -v unoconv 1>/dev/null 2>/dev/null } && {
	# 	unoconv -l 2>/dev/null &
	# 	_verbose "unoconv listener launched."
	# 	sleep 1 }

	for t in ${mounted_tombs}; do
		mapper=`basename ${t[(ws:;:)1]}`
		tombname=${t[(ws:;:)5]}
		tombmount="${t[(ws:;:)2]}"
		[[ -r "${tombmount}/.noindex" ]] && {
			_message "Skipping ::1 tomb name:: (.noindex found)." $tombname
			continue }

	  { command -v updatedb 1>/dev/null 2>/dev/null } && {
	    updatedbver=`updatedb --version | grep '^updatedb'`
	    if [[ "$updatedbver" =~ "GNU findutils" ]]; then
		    _warning "Cannot use GNU findutils for index/search commands."
      # elif [[ "$updatedbver" =~ "locate" ]]; then
		  #   _warning "Index command needs 'mlocate/plocate' to be installed."
      else
		    _message "Indexing ::1 tomb name:: filenames..." $tombname
	      _verbose "$updatedbver"
		    updatedb -l 0 -o "${tombmount}/.updatedb" -U "${tombmount}"
      fi
    }

		# here we use recoll to index file contents
		[[ $RECOLL == 1 ]] && {
			_message "Indexing ::1 tomb name:: contents..." $tombname
			rm -f "${tombmount}/recoll.conf"
			_message "Generating a new search index configuration: ::1 recoll conf::" "${tombmount}/recoll.conf"
      mkdir -p "${tombmount}/.recoll"
			cat <<EOF > "${tombmount}/recoll.conf"
topdirs = ${tombmount}
cachedir = ${tombmount}/.recoll
EOF
			recollindex -c "${tombmount}"
		}
		_message "Search index updated."
	done
	return 0
}

search_tombs() {
	{ command -v locate 1>/dev/null 2>/dev/null } || {
		_failure "Cannot index tombs on this system: updatedb (mlocate/plocate) not installed." }

	updatedbver=`updatedb --version | grep '^updatedb'`
	[[ "$updatedbver" =~ "GNU findutils" ]] && {
		_warning "Cannot use GNU findutils for index/search commands." }
	[[ "$updatedbver" =~ "locate" ]] || {
		_failure "Index command needs 'mlocate/plocate' to be installed." }

	_verbose "$updatedbver"

	# list all open tombs
	mounted_tombs=(`list_tomb_mounts`)
	[[ ${#mounted_tombs} == 0 ]] && {
		_failure "I can't see any open tomb, may they all rest in peace." }

	_success "Searching for: ::1::" ${(f)@}
	for t in ${mounted_tombs}; do
		_verbose "Checking for index: ::1::" ${t}
		mapper=`basename ${t[(ws:;:)1]}`
		tombname=${t[(ws:;:)5]}
		tombmount="${t[(ws:;:)2]}"
		[[ -r "${tombmount}/.updatedb" ]] && {
			# Use mlocate/plocate to search hits on filenames
			_message "Searching filenames in tomb ::1 tomb name::" $tombname
			locate -d "${tombmount}/.updatedb" -e -i "${(f)@}"
			_message "Matches found: ::1 matches::" \
					 $(locate -d "${tombmount}/.updatedb" -e -i -c ${(f)@})

			# Use recoll to search over contents
			[[ $RECOLL == 1 && -r "$tombmount/recoll.conf" ]] && {
				_message "Searching contents in tomb ::1 tomb name::" $tombname
				recollq -c "${tombmount}" ${@} }
		} || {
			_warning "Skipping tomb ::1 tomb name::: not indexed." $tombname
			_warning "Run 'tomb index' to create indexes." }
	done
	_message "Search completed."
	return 0
}

# }}} - Index and search

# {{{ Resize

# resize tomb file size
resize_tomb() {
	local tombpath="$1"	   # First argument is the path to the tomb

	_message "Commanded to resize tomb ::1 tomb name:: to ::2 size:: mebibytes." $1 $OPTS[-s]

	[[ -z "$1" ]] && _failure "No tomb name specified for resizing."
	[[ ! -r "$1" ]] && _failure "Cannot find ::1::" $1

	newtombsize="`option_value -s`"
	[[ -z "$newtombsize" ]] && {
		_failure "Aborting operations: new size was not specified, use -s" }

	is_valid_tomb $tombpath

	_load_key # Try loading new key from option -k and set TOMBKEYFILE

	if option_is_set --tomb-pwd; then
		tomb_pwd="`option_value --tomb-pwd`"
		_verbose "tomb-pwd = ::1 tomb pass::" $tomb_pwd
		ask_key_password "$tomb_pwd"
	else
		ask_key_password
	fi
	[[ $? == 0 ]] || _failure "No valid password supplied."

	local oldtombsize=$(( `stat -c %s "$TOMBPATH" 2>/dev/null` / 1048576 ))

	# New tomb size must be specified
	[[ -n "$newtombsize" ]] || {
		_failure "You must specify the new size of ::1 tomb name::" $TOMBNAME }
	# New tomb size must be an integer
	[[ $newtombsize == <-> ]] || _failure "Size is not an integer."

	# Tombs can only grow in size
	if [[ "$newtombsize" -gt "$oldtombsize" ]]; then

		delta="$(( $newtombsize - $oldtombsize ))"

		_message "Generating ::1 tomb file:: of ::2 size::MiB" $TOMBFILE $newtombsize

		_verbose "Data dump using ::1:: from /dev/urandom" ${DD[1]}
		${=DD} if=/dev/urandom bs=1048576 count=${delta} >> $TOMBPATH
		[[ $? == 0 ]] || {
			_failure "Error creating the extra resize ::1 size::, operation aborted." \
					 $tmp_resize }

		# If same size this allows to re-launch resize if pinentry expires
		# so that it will continue resizing without appending more space.
		# Resizing the partition to the file size cannot harm data anyway.
	elif [[ "$newtombsize" = "$oldtombsize" ]]; then
		_message "Tomb seems resized already, operating filesystem stretch"
	else
		_failure "The new size must be greater then old tomb size."
	fi

	lo_check "$TOMBPATH"

	_message "opening tomb"
	_cryptsetup luksOpen ${TOMBPATH} ${TOMBMAPPER} || {
		_failure "Failure mounting the encrypted file." }

	_sudo cryptsetup resize "${TOMBMAPPER}" || {
		_failure "cryptsetup failed to resize ::1 mapper::" $TOMBMAPPER }


	filesystem=`_detect_filesystem /dev/mapper/${TOMBMAPPER}`
	_message "Filesystem detected: ::1 filesystem::" $filesystem
	case $filesystem in
		ext3|ext4)
			_sudo e2fsck -p -f /dev/mapper/${TOMBMAPPER} || {
				_sudo cryptsetup luksClose "${TOMBMAPPER}"
				_failure "e2fsck failed to check ::1 mapper::" $TOMBMAPPER }
			_sudo resize2fs /dev/mapper/${TOMBMAPPER} || {
				_sudo cryptsetup luksClose "${TOMBMAPPER}"
				_failure "resize2fs failed to resize ::1 mapper::" $TOMBMAPPER }
			;;
		btrfs)
			_sudo btrfs check /dev/mapper/${TOMBMAPPER} || {
				_sudo cryptsetup luksClose "${TOMBMAPPER}"
				_failure "filesystem check failed on ::1 mapper::" $TOMBMAPPER }
			# btrfs requires mounting before resize
			local mp=${TOMBNAME}.tomb.resize
			mkdir -p /tmp/${mp}
			_sudo mount /dev/mapper/${TOMBMAPPER} /tmp/${mp}
			_sudo btrfs filesystem resize max /tmp/${mp} || {
				_sudo umount /tmp/${mp}
				_sudo cryptsetup luksClose "${TOMBMAPPER}"
				rmdir /tmp/${mp}
				_failure "filesystem resize failed on ::1 mapper::" $TOMBMAPPER }
			_sudo umount /tmp/${mp}
			rmdir /tmp/${mp}
			;;
		# TODO: report error on unrecognized filesystem
	esac

	# close and free the loop device
	_sudo cryptsetup luksClose "${TOMBMAPPER}"

	return 0
}

# }}}

# {{{ Close

umount_tomb() {
	local tombs how_many_tombs
	local pathmap mapper tombname tombmount loopdev
	local ans pidk pname

	if [ "$1" = "all" ]; then
		mounted_tombs=(`list_tomb_mounts`)
	else
		mounted_tombs=(`list_tomb_mounts $1`)
	fi

	[[ ${#mounted_tombs} == 0 ]] && {
		_failure "There is no open tomb to be closed." }

	[[ ${#mounted_tombs} -gt 1 && -z "$1" ]] && {
		_warning "Too many tombs mounted, please specify one (see tomb list)"
		_warning "or issue the command 'tomb close all' to close them all."
		_failure "Operation aborted." }

	for t in ${mounted_tombs}; do
		mapper=`basename ${t[(ws:;:)1]}`

		# strip square parens from tombname
		tombname=${t[(ws:;:)5]}
		tombmount="${t[(ws:;:)2]}"
		tombfs=${t[(ws:;:)3]}
		tombfsopts=${t[(ws:;:)4]}
		tombloop=${mapper[(ws:.:)4]}

		_verbose "Name: ::1 tomb name::" $tombname
		_verbose "Mount: ::1 mount point::" "$tombmount"
		_verbose "Loop: ::1 mount loop::" $tombloop
		_verbose "Mapper: ::1 mapper::" $mapper

		[[ -e "$mapper" ]] && {
			_warning "Tomb not found: ::1 tomb file::" $1
			_warning "Please specify an existing tomb."
			return 0 }

		option_is_set -n || {
			exec_safe_func_hooks \
				close "$tombmount" "$tombname" "$tombloop" "$mapper"
			exec_hook_res=$?
			[[ $exec_hook_res = 0 ]] || {
				_warning "close exec-hook returns a non-zero error code: ::1 error::" $exec_hook_res
				_failure "Operation aborted"
			}
		}

		_message "Closing tomb ::1 tomb name:: mounted on ::2 mount point::" \
				 $tombname "$tombmount"

		# check if there are bind mounted dirs and close them first
		# Can be due to bind-hooks or outside --bind mounts
		bind_tombs=(`list_tomb_binds "$mapper"`)
		for b in ${bind_tombs}; do
			bind_mapper="${b[(ws:;:)1]}"
			bind_mount="${b[(ws:;:)2]}"
			_message "Closing tomb bind hook: ::1 hook::" "$bind_mount"
			_sudo umount "$(echo "$bind_mount")" ||
				_failure "Tomb bind hook ::1 hook:: is busy, cannot close tomb." "$bind_mount"
		done

		# umount the main mount
		_verbose "Performing umount of ::1 mount point::" "$tombmount"
		touch "${tombmount}"/.cleanexit
		_sudo umount "${tombmount}"
		[[ $? = 0 ]] || {
			rm -f "${tombmount}"/.cleanexit
			_failure "Tomb is busy, cannot umount!"
		}

		# If we used a default mountpoint and is now empty, delete it
		tombname_regex=${tombname//\[/}
		tombname_regex=${tombname_regex//\]/}

		[[ "$tombmount" =~ "(/run)?/media(/$_USER)?/$tombname_regex" ]] && {
			_sudo rmdir "$tombmount" }

		_sudo cryptsetup luksClose $mapper ||
			_failure "Error occurred in cryptsetup luksClose ::1 mapper::" $mapper

		_success "Tomb ::1 tomb name:: closed: your bones will rest in peace." $tombname

	done # loop across mounted tombs

	return 0
}

list_processes() {
	# $1 = (optional) name of tomb
	# runs lsof on the mounted_tombs
	local mounted_tombs i
	mounted_tombs=(`list_tomb_mounts $1`)
	if [[ "${#mounted_tombs}" -gt 0 ]]; then
		if [[ -z $1 ]]; then
			_success "Listing processes running inside all open tombs..."
		else
			_success "Listing processes running inside tomb '::1 tombname::'..." "$1"
		fi

		for i in ${mounted_tombs}; do
			_verbose "scanning tomb: ::1 tombmount::" $i
			tombmount="${i[(ws:;:)2]}"
			_sudo lsof +D "${i[(ws:;:)2]}"
		done
	fi
	return 0
}

# Kill all processes using the tomb
slam_tomb() {
	# $1 = (optional) name of tomb to slam, or "all" if more mounted

	if [ "$1" = "all" ]; then
		mounted_tombs=(`list_tomb_mounts`)
	else
		mounted_tombs=(`list_tomb_mounts $1`)
	fi

	[[ ${#mounted_tombs} == 0 ]] && {
		_failure "There is no open tomb to be closed." }

	[[ ${#mounted_tombs} -gt 1 && -z "$1" ]] && {
		_warning "Too many tombs mounted, please specify one (see tomb list)"
		_warning "or issue the command 'tomb close all' to close them all."
		_failure "Operation aborted." }

	local pnum puid pcmd powner result
	result=0
	# iterate through all mounted tomb affected
	for i in ${mounted_tombs}; do
		tombname=${i[(ws:;:)5]}
		tombmount="${i[(ws:;:)2]}"
		_success "Slamming tomb ::1 tombname:: mounted on ::2 tombmount::" \
				 ${tombname} "${tombmount}"
		# iterate through all processes running in mounted tombs
		for pnum in ${(f)"$(_sudo lsof -t +D "$tombmount")"}; do
			puid=$(cat /proc/${pnum}/loginuid)
			pcmd=$(cat /proc/${pnum}/cmdline)
			powner=`_get_username $puid`
			_verbose "process found: $pnum $pcmd ($powner)"
			# iterate through 3 different signals to send, break on success
			for s in TERM HUP KILL; do
				_message "::1 tombname:: sending ::2 sig:: to ::3 cmd:: (::4 uid::)" \
						 ${tombname} ${s} ${pcmd} ${powner}
				_sudo kill -$s $pnum
				# give some time to the process for a clean quit
				sleep .5
				# stop sending other signals if kill was succesfull
				[[ -r /proc/$pnum ]] || break
			done
			# if process still running then signal failure
			[[ -r /proc/$pnum ]] && {
				_warning "Can't kill ::1 process:: ::2 pcmd:: (::3 powner::)" \
						 $pnum $pcmd $powner
				result=1 }
		done
		# if it failed killing a process, report it
		[[ $result = 0 ]] && umount_tomb "${tombname:1:-1}"
	done
	return $result
}

# }}} - Tomb close

# {{{ Main routine

main() {

	_ensure_dependencies  # Check dependencies are present or bail out

	local -A subcommands_opts
	### Options configuration
	#
	# Hi, dear developer!  Are you trying to add a new subcommand, or
	# to add some options?	Well, keep in mind that option names are
	# global: they cannot bear a different meaning or behaviour across
	# subcommands.	The only exception is "-o" which means: "options
	# passed to the local subcommand", and thus can bear a different
	# meaning for different subcommands.
	#
	# For example, "-s" means "size" and accepts one argument. If you
	# are tempted to add an alternate option "-s" (e.g., to mean
	# "silent", and that doesn't accept any argument) DON'T DO IT!
	#
	# There are two reasons for that:
	#	 I. Usability; users expect that "-s" is "size"
	#	II. Option parsing WILL EXPLODE if you do this kind of bad
	#		things (it will complain: "option defined more than once")
	#
	# If you want to use the same option in multiple commands then you
	# can only use the non-abbreviated long-option version like:
	# -force and NOT -f
	#
	main_opts=(q -quiet=q D -debug=D h -help=h v -version=v f -force=f -tmp: U: G: T: -no-color -unsafe g -gpgkey=g -sudo:)
	subcommands_opts[__default]=""
	# -o in open and mount is used to pass alternate mount options
	subcommands_opts[open]="n -nohook=n k: -kdf: -kdftype: -kdfmem: o: -ignore-swap -tomb-pwd: r: R: -sphx-host: -sphx-user: p -preserve-ownership=p"
	subcommands_opts[mount]=${subcommands_opts[open]}

	subcommands_opts[create]="" # deprecated, will issue warning

	# -o in forge and lock is used to pass an alternate cipher.
	subcommands_opts[forge]="-ignore-swap k: -kdf: -kdftype: -kdfmem: o: -tomb-pwd: -use-random r: R: -sphx-host: -sphx-user: "
	subcommands_opts[dig]="-ignore-swap s: -size=s "
	subcommands_opts[lock]="-ignore-swap k: -kdf: -kdftype: -kdfmem: o: -tomb-pwd: r: R: -sphx-host: -sphx-user: -filesystem: "
	subcommands_opts[setkey]="k: -ignore-swap -kdf: -kdftype: -kdfmem: -tomb-old-pwd: -tomb-pwd: r: R: -sphx-host: -sphx-user: "
	subcommands_opts[engrave]="k: "

	subcommands_opts[passwd]="k: -ignore-swap -kdf: -kdftype: -kdfmem: -tomb-old-pwd: -tomb-pwd: r: R: -sphx-host: -sphx-user: "
	subcommands_opts[close]=""
	subcommands_opts[help]=""
	subcommands_opts[slam]=""
	subcommands_opts[ps]=""
	subcommands_opts[list]="-get-mountpoint "

	subcommands_opts[index]=""
	subcommands_opts[search]=""

	subcommands_opts[bury]="k: -tomb-pwd: r: R: -sphx-host: -sphx-user: "
	subcommands_opts[exhume]="k: -tomb-pwd: r: R: -sphx-host: -sphx-user: "
	subcommands_opts[cloak]="k: "
	subcommands_opts[uncloak]="k: "
	# subcommands_opts[decompose]=""
	# subcommands_opts[recompose]=""
	# subcommands_opts[install]=""
	subcommands_opts[askpass]=""
	subcommands_opts[source]=""
	subcommands_opts[resize]="-ignore-swap s: -size=s k: -tomb-pwd: r: R: -sphx-host: -sphx-user: "
	subcommands_opts[check]="-ignore-swap "
	#	 subcommands_opts[translate]=""

	### Detect subcommand
	local -aU every_opts #every_opts behave like a set; that is, an array with unique elements
	for optspec in $subcommands_opts$main_opts; do
		for opt in ${=optspec}; do
			every_opts+=${opt}
		done
	done
	local -a oldstar
	oldstar=("${(@)argv}")
	#### detect early: useful for --option-parsing
	zparseopts -M -D -Adiscardme ${every_opts}
	if [[ -n ${(k)discardme[--option-parsing]} ]]; then
		print $1
		if [[ -n "$1" ]]; then
			return 1
		fi
		return 0
	fi
	unset discardme
	if ! zparseopts -M -E -D -Adiscardme ${every_opts}; then
		_failure "Error parsing."
		return 127
	fi
	unset discardme
	subcommand=$1
	if [[ -z $subcommand ]]; then
		subcommand="__default"
	fi

	if [[ -z ${(k)subcommands_opts[$subcommand]} ]]; then
		_warning "There's no such command \"::1 subcommand::\"." $subcommand
		exitv=127 _failure "Please try -h for help."
	fi
	argv=("${(@)oldstar}")
	unset oldstar

	### Parsing global + command-specific options
	# zsh magic: ${=string} will split to multiple arguments when spaces occur
	set -A cmd_opts ${main_opts} ${=subcommands_opts[$subcommand]}
	# if there is no option, we don't need parsing
	if [[ -n $cmd_opts ]]; then
		zparseopts -M -E -D -AOPTS ${cmd_opts}
		if [[ $? != 0 ]]; then
			_warning "Some error occurred during option processing."
			exitv=127 _failure "See \"tomb help\" for more info."
		fi
	fi
	#build PARAM (array of arguments) and check if there are unrecognized options
	ok=0
	PARAM=()
	for arg in $*; do
		if [[ $arg == '--' || $arg == '-' ]]; then
			ok=1
			continue #it shouldn't be appended to PARAM
		elif [[ $arg[1] == '-' ]]; then
			if [[ $ok == 0 ]]; then
				exitv=127 _failure "Unrecognized option ::1 arg:: for subcommand ::2 subcommand::" $arg $subcommand
			fi
		fi
		PARAM+=$arg
	done
	# First parameter actually is the subcommand: delete it and shift
	[[ $subcommand != '__default' ]] && { PARAM[1]=(); shift }

	### End parsing command-specific options

	# Use colors unless told not to
	{ ! option_is_set --no-color } && { autoload -Uz colors && colors }
	# Some options are only available during insecure mode
	{ ! option_is_set --unsafe } && {
		for opt in --tomb-pwd --tomb-old-pwd; do
			{ option_is_set $opt } && {
				exitv=127 _failure "You specified option ::1 option::, which is DANGEROUS and should only be used for testing\nIf you really want so, add --unsafe" $opt }
		done
	}
	# read -t or --tmp flags to set a custom temporary directory
	option_is_set --tmp && TMPDIR=$(option_value --tmp)

	option_is_set --sudo && {
	    local _opt=`basename $(option_value --sudo)`
            _message "Privilege escalation tool configured: ::1 exec::" $_opt
	}

	# When we run as root, we remember the original uid:gid to set
	# permissions for the calling user and drop privileges
	_whoami # Reset _UID, _GID, _TTY

	[[ -z $PARAM ]] && {
		_verbose "Tomb command: ::1 subcommand::" $subcommand
	} || {
		_verbose "Tomb command: ::1 subcommand:: ::2 param::" $subcommand $PARAM
	}

	[[ -z $_UID ]] || {
		_verbose "Caller: uid[::1 uid::], gid[::2 gid::], tty[::3 tty::]." \
				 $_UID $_GID $_TTY
	}

	_verbose "Temporary directory: $TMPDIR"

	# Process subcommand
	case "$subcommand" in

		# USAGE
		help)
			usage
			;;

		# DEPRECATION notice (leave here as 'create' is still present in old docs)
		create)
			_warning "The create command is deprecated, please use dig, forge and lock instead."
			_warning "For more informations see Tomb's manual page (man tomb)."
			_failure "Operation aborted."
			;;

		# CREATE Step 1: dig -s NN file.tomb
		dig)
			dig_tomb $PARAM
			;;

		# CREATE Step 2: forge file.tomb.key
		forge)
			forge_key $PARAM
			;;

		# CREATE Step 3: lock -k file.tomb.key file.tomb
		lock)
			lock_tomb_with_key $PARAM
			;;

		# Open the tomb
		mount|open)
			mount_tomb $PARAM
			;;

		# List all processes using a tomb
		ps)
			list_processes $PARAM
			;;

		# Slam a tomb killing all processes running inside
		slam)
			slam_tomb $PARAM[1]
			;;

		# Close the tomb
		# `slam` is used to force closing.
		umount|close)
			[[ "$subcommand" == "slam" ]] && {
				SLAM=1
				[[ $LSOF == 0 ]] && {
					unset SLAM
					_warning "lsof not installed: cannot slam tombs."
					_warning "Trying a regular close." }}
			umount_tomb $PARAM[1]
			;;

		# Grow tomb's size
		resize)
			[[ $RESIZER == 0 ]] && {
				_failure "Resize2fs not installed: cannot resize tombs." }
			resize_tomb $PARAM[1]
			;;

		## Contents manipulation

		# Index tomb contents
		index)
			index_tombs $PARAM[1]
			;;

		# List tombs
		list)
			list_tombs $PARAM[1]
			;;

		# Search tomb contents
		search)
			search_tombs $PARAM
			;;

		## Locking operations

		# Export key to QR Code
		engrave)
			[[ $QRENCODE == 0 ]] && {
				_failure "QREncode not installed: cannot engrave keys on paper." }
			engrave_key $PARAM
			;;

		# Change password on existing key
		passwd)
			change_passwd $PARAM[1]
			;;

		# Change tomb key
		setkey)
			change_tomb_key $PARAM
			;;

		# STEGANOGRAPHY: hide key inside an image
		bury)
			[[ $STEGHIDE == 0 ]] && {
				_failure "Steghide not installed: cannot bury keys into images." }
			bury_key $PARAM[1]
			;;

		# STEGANOGRAPHY: read key hidden in an image
		exhume)
			[[ $STEGHIDE == 0 ]] && {
				_failure "Steghide not installed: cannot exhume keys from images." }
			exhume_key $PARAM[1]
			;;

		# STEGANOGRAPHY: transform key into text using cipher
		cloak)
			[[ $CLOAKIFY == 0 ]] && {
				_failure "Cloakify not installed: cannot cipher keys into texts" }
			cloakify_key $PARAM
			;;

		# STEGANOGRAPHY: read key from text using cipher
		uncloak)
			[[ $DECLOAKIFY == 0 ]] && {
				_failure "Decloakify not installed: cannot decipher keys from texts" }
			decloakify_key $PARAM
			;;


		## Internal commands useful to developers

		# Make tomb functions available to the calling shell or script
		'source')	return 0 ;;

		# Ask user for a password interactively
		askpass)	ask_password $PARAM[1] $PARAM[2] ;;

		# Default operation: presentation, or version information with -v
		__default)
			_print "Tomb ::1 version:: - a strong and gentle undertaker for your secrets" $VERSION
			echo
			_print " Copyright (C) 2007-2024 Dyne.org Foundation, License GNU GPL v3+"
			_print " This is free software: you are free to change and redistribute it"
			_print " For the latest sourcecode go to <http://dyne.org/software/tomb>"
			echo
			option_is_set -v && {
				local langwas=$LANG
				LANG=en
				_print " This source code is distributed in the hope that it will be useful,"
				_print " but WITHOUT ANY WARRANTY; without even the implied warranty of"
				_print " MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
				LANG=$langwas
				_print " When in need please refer to <http://dyne.org/support>."
				echo
				_print "System utils:"
				echo
				cat <<EOF
  `zsh --version`
  `sudo -V | head -n1`
  `cryptsetup --version`
  `pinentry --version | head -n1`
  `findmnt -V`
  `gpg --version | head -n1` - key forging algorithms (GnuPG symmetric ciphers):
  `list_gnupg_ciphers`
EOF
				echo
				_print "Optional utils:"
				echo
				_list_optional_tools version
				return 0
			}
			usage
			;;

		# Reject unknown command and suggest help
		*)
			_warning "Command \"::1 subcommand::\" not recognized." $subcommand
			_message "Try -h for help."
			return 1
			;;
	esac
	return $?
}

# }}}

# {{{ Run

main "$@" || exit $?   # Prevent `source tomb source` from exiting

# }}}