bitter 1.0

                            What is bitter?
                            ===============

bitter is a tool to calculate the urn:bitprint, urn:sha1 or urn:tiger:tree of
one or more files.


                           What is urn:sha1?
                           =================

The urn:sha1 is exactly the same as an SHA-1 except that it is prefixed with
"urn:sha1:" and the SHA-1 is base32 encoded instead of base16 (hex) as usual.


                        What is urn:tree:tiger?
                        =======================

This is the root hash of a Merkle hash tree using the Tiger hash algorithm.
The hash itself is base32 encoded.


                         What is urn:bitprint?
                         =====================

It is the concatenation of the SHA-1 and the root Tiger Tree Hash of a
given file separated by a single ASCII period. Both hashes are base32
encoded.


                        How do I compile bitter?
                        ========================

Just run "make". This runs config.sh and then proceeds to build bitter.
The default installation path is /usr/local. You can run ./config.sh
--help before making to configure a different location and other
options. When compiling succeeded, it is advisable to run "make checks"
to verify bitter using a couple of test cases. Finally, run "make
install" if you want to install bitter. You do not have to install it in
any specific location though. You can as well copy it anywhere you want
and execute it from there. Thus, typically:

        $ make && make checks && make install

If some vital functions, library or headers are not detected by
config.sh, try running it again after setting CFLAGS, LDFLAGS etc.
appropriately. This may be necessary if such files are installed in
non-standard locations.


                          How do I use bitter?
                          ====================

Make sure bitter is in your PATH. To calculate the bitprint of a file,
run:

 $ bitter file

If you just want the urn:sha1 run this:

 $ bitter -S file

Likewise, if you just want the urn:tiger:tree run this:

 $ bitter -T file

If you pass '-q' as parameter, the filename is omitted.

If you pass no arguments at all, the standard input is read instead.
This is useful to calculate the hashsums of data passed over a pipe. For
example, to calculate a hashsum of a file during its download, you could
run this:

 $ curl -sS http://example.com/ | tee download | bitter

This might be useful for larger files when the calculation of the
hashsum takes a couple of minutes. In any case, it's just an arbitrary
example for using bitter with a pipe.

Run "bitter -h" to get a list of all supported options.

You can also pass multiple file arguments to bitter to calculate the
hashsums of multiple files in one go:

  $ bitter file_1 ... file_n

bitter will print a line for each file and prefix the hashsum with the
filename followed by a space an a colon. Example:

 $ echo | bitter -S /dev/null /dev/stdin LICENSE

/dev/null: urn:sha1:3I42H3S6NNFQ2MSVX7XZKYAYSCX5QBYJ
/dev/stdin: urn:sha1:VXEDWGPHSNERWHDOUD6YWRWNT4ZOLEX4
LICENSE: urn:sha1:UZHW2ANBQXREWV7GQSX6PSFOQBGM46U2

An additional feature is converting SHA-1 checksums from the hexadecimal
representation to the base32 representation and vice-versa. The leading
'urn:sha1:' is mandatory when passing a base32 SHA-1.

$ bitter -c urn:sha1:3I42H3S6NNFQ2MSVX7XZKYAYSCX5QBYJ
da39a3ee5e6b4b0d3255bfef95601890afd80709

$ bitter -c da39a3ee5e6b4b0d3255bfef95601890afd80709
urn:sha1:3I42H3S6NNFQ2MSVX7XZKYAYSCX5QBYJ


                                APPENDIX
                                ========

RFC 3174 - US Secure Hash Algorithm 1 (SHA1):
http://www.faqs.org/ftp/rfc/rfc3174.txt

Tiger: A Fast New Cryptographic Hash Function (Designed in 1995):
http://www.cs.technion.ac.il/~biham/Reports/Tiger/

Bitzi Bitprint Definition:
http://bitzi.com/developer/bitprint

Tree Hash EXchange format (THEX):
http://www.open-content.net/specs/draft-jchapweske-thex-02.html

/* vi: set tw=72 et: */