Ubuntu Manpage: tthsum ‐ generates or checks TTH message digests

NAME

       tthsum ‐ generates or checks TTH message digests

SYNOPSIS

       tthsum [-bhmpvVw] [-c [file]] | [file...]

DESCRIPTION

tthsum generates or checks TTH checksums (roots of the Tiger/THEX hash tree). The Merkle
Hash Tree, invented by Ralph Merkle, is a hash construct that exhibits desirable
properties for verifying the integrity of files and file subranges in an incremental or
out‐of‐order fashion. tthsum uses the Tiger hash algorithm, by Ross Anderson and Eli
Biham, for both the internal and the leaf nodes.

The specification of the THEX algorithm is at:
. http://tthsum.devs.nu/draft-jchapweske-thex-02.html

The specification of the Tiger hash algorithm is at:
. http://www.cs.technion.ac.il/~biham/Reports/Tiger/

Normally tthsum generates checksums of all files given to it as parameters and prints the
checksums followed by the filenames. If, however, -c is specified, only one filename
parameter is allowed. This file should contain checksums and filenames to which these
checksums refer, and the files listed in that file are checked against the checksums
listed there. See option -c for more information.

If no file is specified data will be read from standard input.

OPTIONS
-b An md5sum compatibility option. It does absolutely nothing. (md5sum uses -b to
treat binary files differently from texts files.)

-c Check tthsum of all files listed in file against the checksum listed in the same
file. The actual format of that file is the same as output of tthsum. That is,
each line in the file describes a file. A line looks like:

So, for example, if a file were created and its message digest calculated like so:

echo foo > tth-test-file; tthsum tth-test-file

tthsum would report:

A2MPPCGS5CPJV6AOAP37ICDCFV3WYU7PBREC6FY tth-test-file

See NOTES for more information on the digest file format.

-m Use mmap(2) instead of read(2) to read the contents of the files to hash. Normally,
using read is cheaper. This all depends on system load, I/O speed, CPU speed, L1
and/or L2 cache size and whatnot.

-p Show the progress. Print the percentage of completeness while hashing on standard
error. Prints file position instead of percentage when the file size is unknown.

-v Be verbose. Print filenames when checking (with -c).

-w Warn on improperly formatted lines when checking (with -c).

-h, -V Print a small help text or the version, respectively, on standard out. If an
unknown combination of options is encountered, the small help is printed on
standard error and tthsum will return non‐zero.

RETURN VALUE

       tthsum  returns 0 if no error occurred or, when checking a digest, if at least one line is
       formatted properly and the TTHs of all properly formatted lines match.  tthsum  returns  2
       if  an  unknown  combination  of  options  is encountered.  In all other cases will tthsum
       return 1.

NOTES

       tthsum intentionally uses an interface identical to md5sum.

       tthsum   uses    BASE32    encoding    consisting    of    the    following    characters:
       ABCDEFGHIJKLMNOPQRSTUVWXYZ234567.   It  will accept lower case letters in the digest input
       as well.

       tthsum does not accept long options such as --help.

       A digest file format line looks like: <BASE32><SPACES><FILENAME><EOL>.   BASE32  is  a  39
       character  long BASE32 encoded string.  SPACES is a set of two spaces (0x20).  FILENAME is
       the name of the file, encoded in UTF8 and with all control characters (those  below  0x20)
       encoded  as  \xNN  or  \C  C‐style  escapes.  (The  backslash is escaped as \\ as well. On
       Windows, backslashes in paths will be translated to slashes for  compatibility  with  real
       operating systems.)  EOL may be CRLF (\r\n), just plain LF (\n) or even nothing at end‐of‐
       file.

       If you see warnings about an improper  locale  setup,  check  your  LANG  and/or  LC_CTYPE
       environment  variables.   If these are not set properly, tthsum cannot represent non‐ASCII
       characters (those above 0x7F) in UTF8. See locale(1) for more information or  try  to  set
       LC_CTYPE to e.g. "en_US".

REPORTING BUGS

       Report bugs to <walter+tthsum@wjd.nu>.

COPYRIGHT

       Copyright   ©   2009   Walter  Doekes.   License  GPLv3+:  GNU  GPL  version  3  or  later
       <http://gnu.org/licenses/gpl.html>
       This is free software: you are free to change and redistribute it.  There is NO  WARRANTY,
       to the extent permitted by law.

AUTHOR

       tthsum and this manpage were written by Walter Doekes (walter+tthsum@wjd.nu).  The hashing
       code was copied directly from DC++, an open source peer‐to‐peer file  sharing  program  by
       Jacek Sieka (jacek@creatio.se) who had based the hashing code on the one used in BCDC++ (a
       modified DC++) by Dustin Brody (blackclaw@parsoma.net).  After version 1.1.0, the  hashing
       code  from the Tiger hash authors is used instead, to support big endian architectures and
       to remove the need for C++ compilers and libraries.  The md5sum manpage, written  by  Juho
       Vuori  (javuori@cc.helsinki.fi),  was  used  as  a template. This manpage was proofread by
       Dustin Brody.