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
 ..
 .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
 .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 [ \-f0ecbv ]
 .RB [ \-a
 .IR algorithm ]

+.RB [ \-E
+.IR encoding ]

 .IR files ...
 .SH DESCRIPTION
 The
 .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
 .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 .
 .BI "\-a, \-\-algorithm=" alg
 Use the hash algorithm
 .IR alg .


@@ -60,9 +65,20 @@ see
 .B "Hashing algorithms"
 below.
 .TP
 .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
 .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
 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"
 .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 ,
 .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 (` * ')
 .I flag
 is either a star
 .RB (` * ')


@@ -201,6 +217,13 @@ The
 .B hashsum
 program understands several hashing algorithms:
 .TP
 .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
 .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.
 .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.
 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
 .PP
 The default hashing algorithm is determined by looking at the name by
 which it was invoked passed to it in