last fixes and documentation for release

manual page updates and improvements to kdf argument handling

ChangeLog

@@ -1,4 +1,16 @@
-June 2013 - 1.3.1
+June 2013 - 1.4
+
+	This release fixes an important bug affecting Tomb 1.3.* which
+	breaks backward compatibility with older tombs and invalidates
+	keys created using 1.3 or 1.3.1. For more information about it
+	read the file KNOWN_BUGS.  New features are also included:
+	indexing and search of file contents, engraving of keys into paper
+	printable QRCodes for backup purposes and improvements in key
+	encryption. A setkey command is added to change the key file that
+	is locking a Tomb. This release restores backward compatibility
+	with tombs created before the 1.3 release series.
+
+June 2013 - 1.3.1 (DEPRECATED USAGE, see 1.4 and KNOWN_BUGS)
 
 	Major bugfixes following the recent refactoring. This release
 	fixes various advanced commands as search/index, KDF key
@@ -8,7 +20,7 @@ June 2013 - 1.3.1
 	consistent and full paths are honored. A new test suite is
 	included and documentation is updated accordingly.
 
-May 2013 - 1.3
+May 2013 - 1.3 (DEPRECATED USAGE, see 1.4 and KNOWN_BUGS)
 
 	A refactoring of Tomb's main script internals was made, including
 	a new messaging system, machine parsable output, cleaner code and

KNOWN_BUGS

@@ -0,0 +1,19 @@
+* Compatibility broken in Tomb 1.3 and 1.3.1
+
+ Due to an error in the creation and decoding of key files, release
+ versions 1.3 and 1.3.1 cannot open older tombs, plus the tombs created
+ with them will not be opened with older and newer versions of Tomb.
+
+ This bug was fixed in commit 551a7839f500a9ba4b26cd63774019d91615cb16
+
+ Those who have created tombs with older versions can simply upgrade
+ to release 1.4 (and any other following release) to fix this issue
+ and be able to operate their tombs normally.
+
+ Those who have used Tomb 1.3 or 1.3.1 to create new tombs should use
+ Tomb version 1.3.1 to open them and then migrate the contents into a
+ new tomb created using the latest Tomb version.
+
+ This bug was due to a typo in the code which appended a GnuPG status
+ string to the content of keys.  All users of Tomb 1.3.* should pay
+ particular attention to this issue.

README

@@ -12,7 +12,7 @@ X~     `?888888hx~  ...ue888b   .888: x888  x888.   8888   .
 '    "*88888888*      'Y"         `~    "    `"`    `%888*%"
         ^"***"`                                        "`
 
-A minimalistic commandline tool to manage encrypted volumes  v.1.3.1
+A minimalistic commandline tool to manage encrypted volumes  v.1.4
 
                    http://tomb.dyne.org
 

doc/tomb.1

@@ -1,4 +1,4 @@
-.TH tomb 1 "May 25, 2013" "tomb"
+.TH tomb 1 "June 20, 2013" "tomb"
 
 .SH NAME
 Tomb \- the Crypto Undertaker
@@ -30,18 +30,23 @@ harddisk and its key file on a USB stick.
 .IP "dig"
 Generates a file that can be used as a tomb and will occupy as much
 space as its desired initial size, the unlocked \fI.tomb\fR file can
-then be locked using a \fI.tomb.key\fR. It takes a mandatory option
+then be locked using a \fIkey\fR. It takes a mandatory option which is
-which is the \fI--size\fR in megabytes (MiB). This generation is
+the \fI--size\fR in megabytes (MiB). Tombs are digged using
-relatively simple: its a data dump (dd) of low-quality random data
+low-quality random data (/dev/urandom).
-(from /dev/urandom) and does not require root privileges.
 
 .B
 .IP "forge"
 Creates a new \fIkey\fR and prompts the user for a \fIpassword\fR to
 protect its usage. This operation requires high quality random data
-(from /dev/random) which can take quite some time to be gathered on a
+(/dev/random) which can take quite some time to be gathered on a
 server: it works better on a desktop where the mouse can be moved
-around for entropy.
+around for entropy. The default cipher to protect the key is AES256, a
+custom one can be specified using the \fI-o\fR option, for a list of
+supported ciphers use \fI-v\fR. For additional protection against
+dictionary attacks on keys, the (experimental) \fI--kdf\fR option can
+be used when forging a key, making sure that the \fItomb-kdb-pbkdf2\fR
+binaries in \fIextras/kdf\fR were compiled and installed on the
+system.
 
 .B
 .IP "lock"
@@ -102,13 +107,20 @@ situations.
 
 .B
 .IP "passwd"
-Changes the password protecting a \fIkey\fR file specified using
+Changes the password protecting a key file specified using
 \fI-k\fR. The user will need to know the key's current password, then
 its content will be decoded and reencoded using the new one. This
 action can't be forced if the current password is not known. If the
 key file is broken (missing headers) this function also attempts its
 recovery.
 
+.B
+.IP "setkey"
+Changes the key file that locks a tomb, substituting the old one with
+a new one. Both the old and the new key files are needed for this
+operation and their passwords must be known. The new key must be
+specified using the \fI-k\fR option, the first argument should be the old
+key and the second and last argument the tomb file.
 
 .B
 .IP "resize"
@@ -119,6 +131,15 @@ can never be made smaller. This command makes use of the cryptsetup
 resize feature and the resize2fs command: its much more practical than
 creating a new tomb and moving everything into it.
 
+.B
+.IP "engrave"
+This command transforms a tomb key into an image that can be printed
+on paper and phisically stored as backup, i.e. hidden in a book. It
+Renders a QRCode of the tomb key, still protected by its password: a
+PNG image (extension \fI.qr.png\fR) will be created in the current
+directory and can be later printed (fits an A4 or Letter format).  To
+recover an engraved key one can use any QRCode reader on a smartphone:
+save it into a file and then use that file as a key (\fI-k\fR).
 
 .B
 .IP "bury"
@@ -152,9 +173,10 @@ other media.  If \fI<keyfile>\fR is "-" (dash), it will read it from
 stdin.
 .B
 .IP "--kdf \fI<seconds>\fR"
-Activate the KDF feature against dictionary attacks when creating a key: forces a
+Activate the KDF feature against dictionary attacks when creating a
-delay of \fI<seconds>\fR every time this key is used. Floating point values
+key: forces a delay of \fI<seconds>\fR every time this key is
-are accepted, default is 1.
+used. This feature is still \fIexperimental\fR and not recommended in
+production environments.
 .B
 .IP "-n"
 Skip processing of post-hooks and bind-hooks if found inside the tomb.

extras/test/runtests

@@ -57,7 +57,15 @@ notice "Testing creation: forge"
 
 tt --ignore-swap --unsecure-dev-mode --tomb-pwd ${dummypass} --use-urandom forge /tmp/test.tomb.key
 
-{ test $? = 0 } && { results+=(forge SUCCESS) }
+{ test $? = 0 } && { 
+    results+=(forge SUCCESS)
+    # 
+    say "Dump of clear key contents to examine them:"
+    print ${dummypass} \
+	| gpg --batch --passphrase-fd 0 --no-tty --no-options -d /tmp/test.tomb.key \
+	| hexdump -C
+    echo --
+}
 
 notice "Testing creation: lock"
 

tomb

@@ -270,16 +270,18 @@ Commands:
  list    list of open TOMBs and information on them
  close   close a specific TOMB (or 'all')
  slam    slam a TOMB killing all programs using it
-
- // Operations on keys:
- passwd  change the password of a KEY
- change  change the KEY locking a TOMB (needs old one)
 EOF
     if [ "$RESIZER" = 1 ]; then
 	cat <<EOF
  resize  resize a TOMB to a new --size (can only grow)
 EOF
     fi
+cat <<EOF
+
+ // Operations on keys:
+ passwd  change the password of a KEY
+ setkey  change the KEY locking a TOMB (needs old one)
+EOF
 
     { test "$QRENCODE" = "1" } && {
 	cat <<EOF
@@ -769,16 +771,21 @@ gen_key() {
     fi
 
     header=""
+    { test "$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`"
-	{ test "$itertime" = "" } && { itertime=".5" }
+	# removing support of floating points because they can't be type checked well
-	_verbose "KDF itertime chosen: $itertime"
+	    if [[ "$itertime" != <-> ]]; then
+		unset tombpass
+		unset tombpasstmp
+		die "Wrong argument for --kdf: must be an integer number (iteration seconds)"
+	    fi
 	    # --kdf takes one parameter: iter time (on present machine) in seconds
 	    local -i microseconds
-	microseconds=$((itertime*1000000))
+	    microseconds=$((itertime*10000))
-	_verbose "Microseconds: $microseconds"
+	    yes "Using KDF, iterations: $microseconds"
 	    pbkdf2_salt=`tomb-kdb-pbkdf2-gensalt`
 	    pbkdf2_iter=`tomb-kdb-pbkdf2-getiter $microseconds`
 	    # We use a length of 64bytes = 512bits (more than needed!?)
@@ -786,6 +793,7 @@ gen_key() {
 	    
 	    header="_KDF_pbkdf2sha1_${pbkdf2_salt}_${pbkdf2_iter}_64\n"
 	}
+    }
 
 
     print -n $header
@@ -796,6 +804,7 @@ gen_key() {
 	-o - -c -a ${lukskey}
 
     unset tombpass
+    unset tombpasstmp
 }
 
 # prints an array of ciphers available in gnupg (to encrypt keys)
@@ -2147,7 +2156,7 @@ main() {
     subcommands_opts[forge]="f -force -ignore-swap k: -key=k -kdf: o: -tomb-pwd: -use-urandom "
     subcommands_opts[dig]="f -force -ignore-swap s: -size=s "
     subcommands_opts[lock]="f -force -ignore-swap k: -key=k o: -sudo-pwd: -tomb-pwd: "
-    subcommands_opts[change]="f -force -ignore-swap k: -key=k -sudo-pwd: -tomb-pwd: "
+    subcommands_opts[setkey]="f -force -ignore-swap k: -key=k -sudo-pwd: -tomb-pwd: "
     subcommands_opts[engrave]="k: -key=k "
 
     subcommands_opts[passwd]="f -ignore-swap -kdf: -tomb-old-pwd: -tomb-pwd: "
@@ -2275,7 +2284,7 @@ main() {
 	    lock_tomb_with_key ${=PARAM}
 	    ;;
 
-	change)
+	setkey)
 	    check_priv
 	    change_tomb_key ${=PARAM}
 	    ;;