General utilities cleanup. Add signature support to catcrypt. Throw in

[u/mdw/catacomb] / hashsum.1

diff --git a/hashsum.1 b/hashsum.1
index d7598a9..5eb280b 100644 (file)
--- a/hashsum.1
+++ b/hashsum.1
@@ -7,7 +7,7 @@
 ..
 .ie t .ds o \(bu
 .el .ds o o
-.TH hashsum 1 "29 July 2000" Catacomb
+.TH hashsum 1 "29 July 2000" "Straylight/Edgeware" "Catacomb cryptographic library"
 .SH NAME
 hashsum \- compute and verify cryptographic checksums of files
 .SH SYNOPSIS
@@ -15,6 +15,8 @@ hashsum \- compute and verify cryptographic checksums of files
 .RB [ \-f0ecbv ]
 .RB [ \-a
 .IR algorithm ]
+.RB [ \-E
+.IR encoding ]
 .IR files ...
 .SH DESCRIPTION
 The
@@ -52,6 +54,9 @@ successfully.
 .B "\-u, \-\-usage"
 Prints a brief usage summary to standard output and exits successfully.
 .TP
+.BR "\-l, \-\-list " [ \fIitem ...]
+Show lists of hash functions and encodings supported.
+.TP
 .BI "\-a, \-\-algorithm=" alg
 Use the hash algorithm
 .IR alg .
@@ -60,9 +65,20 @@ see
 .B "Hashing algorithms"
 below.
 .TP
-.B "\-l, \-\-list"
-Prints a space-separated list of available hashing algorithms to
-standard output and exits successfully.
+.BI "\-E, \-\-encoding=" encoding
+Use the given
+.I encoding
+to represent hashes in the output.  This is not interoperable with other
+programs, but it's handy, e.g., for building sha1 URNs.  The encodings
+recognized are
+.B hex 
+(the default),
+.B base64
+and
+.BR base32 .
+Type
+.B hashsum \-\-list enc
+for a list of supported encodings.
 .TP
 .B "\-f, \-\-files"
 Each input file is considered to be a list of filenames which should be
@@ -132,19 +148,19 @@ character.  Two directives are currently understood:
 Subsequent hashes in this file were generated using the algorithm
 .IR alg .
 .TP
+.BI "#encoding " encoding
+Subsequent hashes in this file are represented using the named
+.IR encoding .
+.TP
 .BI "#escape"
 Filenames in subsequence lines are written using the `escaped' format,
 described below.
 .PP
 A
 .I "file line"
-consists of a hash, in hexadecimal, followed by a space, a
+consists of a hash, in the requested encoding, followed by a space, a
 .IR flag ,
-and the filename.  If the current hash algorithm produces
-.IR n -bit
-output, there must be
-.IR n /4
-hex digits of hash in a file line.  The
+and the filename.  The
 .I flag
 is either a star
 .RB (` * ')
@@ -201,6 +217,13 @@ The
 .B hashsum
 program understands several hashing algorithms:
 .TP
+.BR md2
+Designed by Ron Rivest, although I don't know when, and described in
+RFC1319, MD2 is a really old and slow hash function.  Its security is
+suspect too: only its checksum stands between it and collision-finding
+attacks.  Use of MD2 is not recommended, though it's still used in
+various standards.
+.TP
 .BR md4 " and " md5
 Designed by Ron Rivest in 1990 and 1992 respectively and described in
 RFCs 1186, 1320 and 1321, these two early hash functions are efficient
@@ -231,11 +254,16 @@ drop-in replacement for MD4, MD5 and the old RIPEMD.  The 256 and
 .B tiger
 Designed by Ross Anderson and Eli Biham to take advantage of 64-bit
 processors, Tiger seems to be an efficient and strong hash function.
-Its 192-bit output is wider than that of any other algorithm supported
-by
-.BR hashsum .
 It's a relatively new algorithm, however, and should probably be
 approached with an open-minded caution.
+.TP
+.BR sha256 ", " sha384 " and " sha512
+Designed by the US National Security Agency to provide security
+commensurate with the Advanced Encryption Standard, these hash functions
+provide long outputs.  SHA-256 is fairly quick, though the longer
+variants are slower on 32-bit hardware since they require 64-bit
+arithmetic.  They're all very new at the moment, and should be
+approached with an open-minded caution.
 .PP
 The default hashing algorithm is determined by looking at the name by
 which it was invoked passed to it in