--- /dev/null
+.\" -*-nroff-*-
+.de hP
+.IP
+.ft B
+\h'-\w'\\$1\ 'u'\\$1\ \c
+.ft P
+..
+.ie t .ds o \(bu
+.el .ds o o
+.TH hashsum 1 "29 July 2000" Catacomb
+.SH NAME
+hashsum \- compute and verify cryptographic checksums of files
+.SH SYNOPSIS
+.B hashsum
+.RB [ \-f0ecbv ]
+.RB [ \-a
+.IR algorithm ]
+.IR files ...
+.SH DESCRIPTION
+The
+.B hashsum
+program generates and verifies cryptographic checksums (hashes) of
+files. A number of hashing algorithms are available.
+.PP
+The
+.B hashsum
+program's options and output are designed to be upwardly compatible with
+the GNU
+.BR md5sum (1)
+program.
+.PP
+Usually,
+.B hashsum
+generates checksums of a collection of files named either on the command
+line or read from standard input, and write their hashes to standard
+output using a simple file format. However, given the
+.B \-c
+option, it will read in files in its usual output format and verify that
+the named files have the reported hashes.
+.SS "Options"
+The
+.B hashsum
+program understands the following options:
+.TP
+.B "\-h, \-\-help"
+Prints a help message to standard output and exits successfully.
+.TP
+.B "\-V, \-\-version"
+Prints the program's version number to standard output and exits
+successfully.
+.TP
+.B "\-u, \-\-usage"
+Prints a brief usage summary to standard output and exits successfully.
+.TP
+.BI "\-a, \-\-algorithm=" alg
+Use the hash algorithm
+.IR alg .
+If this option is not given, a default hashing algorithm is selected:
+see
+.B "Hashing algorithms"
+below.
+.TP
+.B "\-l, \-\-list"
+Prints a space-separated list of available hashing algorithms to
+standard output and exits successfully.
+.TP
+.B "\-f, \-\-files"
+Each input file is considered to be a list of filenames which should be
+read and hashed. By default, the filenames are considered to be
+whitespace-separated, although control characters can be escaped (see
+.B "Escaping control characters"
+below).
+.TP
+.B "\-0, \-\-null"
+In conjunction with the
+.B \-f
+option above, reads null-terminated filenames, as emitted by GNU
+.BR find (1)'s
+.B \-print0
+option, rather than whitespace-delimited filenames. If the
+.B \-c
+option is also given, each named in the list is a list of filename/hash
+pairs to be checked.
+.TP
+.B "\-e, \-\-escape"
+Escape control characters (see
+.B "Escaping control characters"
+below) in filenames when generating output. Escaped
+output is not compatible with
+.BR md5sum (1),
+but copes better with files containing newlines and other strange
+control characters.
+.TP
+.B "\-c, \-\-check"
+Check hashes. Each input file is assumed to be in
+.BR hashsum 's
+output format. It is read, and
+.B hashsum
+will verify that each named file has the correct hash. Assuming that
+the hash list is authentic (e.g., it has been digitally signed, or
+obtained via some secure medium), this provides strong assurance that
+the files listed have not been tampered with.
+.TP
+.B "\-b, \-\-binary"
+Assume that the files to be hashed are binary files. This doesn't make
+any difference in Unix systems, although it might on other platforms
+which draw a distinction.
+.TP
+.B "\-v, \-\-verbose"
+In conjunction with the
+.B \-c
+option above, be verbose when checking files.
+.PP
+If no filenames are given on the command line, standard input is read.
+Standard input does not have a filename.
+.SS "Output format"
+There are three types of line in
+.BR hashsum 's
+output format:
+.IR directives ,
+.IR "file lines" ,
+and
+.IR rubbish .
+.PP
+A
+.I directive
+begins with a hash
+.RB (` # ')
+character. Two directives are currently understood:
+.TP
+.BI "#hash " alg
+Subsequent hashes in this file were generated using the algorithm
+.IR alg .
+.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
+.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
+.I flag
+is either a star
+.RB (` * ')
+to indicate that the file should be read in binary mode, or a space.
+The rest of the line contains the filename.
+.PP
+A
+.I rubbish
+line is one which doesn't look like a directive or a file line. Rubbish
+lines are ignored. Hence, you can apply PGP clear-signing to a
+.B hashsum
+file without preventing it from being read.
+.SS "Escaping control characters"
+When reading filenames to hash from a list of files or an escaped hash
+list, the following rules are obeyed:
+.hP \*o
+An escaped string cannot contain unescaped, unquoted whitespace
+characters. If such a character is found, the string is considered to
+have ended.
+.hP \*o
+A backslash
+.RB (` \e ')
+escapes the following character. If the character is one of
+.RB ` a ',
+.RB ` b ',
+.RB ` f ',
+.RB ` n ',
+.RB ` r ',
+.RB ` t ',
+or
+.RB ` v ',
+it is replaced by the control character for an audible alert, backspace,
+form-feed, newline, carriage return, horizontal tab or vertical tab
+respectively; other escaped characters are unchanged, although they lose
+any special meaning they might have had.
+.hP \*o
+A section of text may be quoted by surrounding it by
+.BR ' ... ' ,
+.BR """" ... """" ,
+or
+.BR ` ... '
+pairs. Within a quoted section, whitespace characters may appear
+unescaped. The backslash may be used to quote control characters or the
+quoting characters as usual.
+.hP \*o
+A word beginning with a hash
+.RB (` # ')
+character is considered to begin a
+.I comment
+which extends to the end of the current line. The hash character may be
+escaped as usual.
+.SS "Hashing algorithms"
+The
+.B hashsum
+program understands several hashing algorithms:
+.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
+but cryptographically suspect: the MD4 algorithm has been shown not to
+be collision-resistant and there are `pseudo-collisions' in MD5.
+Despite this,
+.B md5
+has been used heavily since its introduction and is still popular. MD4
+is still useful when a fast non-cryptographic hash is wanted.
+.TP
+.B sha
+Designed by the US National Security Agency as part of the Digital
+Signature Standard, SHA-1 provides a longer output than
+.B md4
+and
+.BR md5 ,
+and is seen as being more secure.
+.TP
+.BR rmd128 ", " rmd160 ", " rmd256 " and " rmd320
+Designed by Antoon Bosselaers, Hans Dobbertin and Bart Preneel in 1996
+as a replacement for the earlier RIPEMD algorithm, RIPEMD160 provides
+the same length output as SHA-1, but has been designed in the open by
+experts. RIPEMD28 is a shortened version of RIPEMD160 designed as a
+drop-in replacement for MD4, MD5 and the old RIPEMD. The 256 and
+320-bit versions are efficient double-width extensions of the 128 and
+160-bit hashes, although they may not offer any additional security.
+.TP
+.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.
+.PP
+The default hashing algorithm is determined by looking at the name by
+which it was invoked passed to it in
+.BR argv[0] :
+if it has the form
+.RI ` alg \c
+.BR sum '
+where
+.I alg
+is the name of a hash function, that hash becomes the default. (Hence,
+.B hashsum
+can be used as a drop-in replacement for
+.BR md5sum (1).)
+If the program name doesn't match an algorithm, then
+.B md5
+is selected for compatibility with files generated by
+.BR md5sum (1).
+.PP
+Note that the same default algorithm is used for both generating new
+output files and checking existing ones. If the algorithm is forced by
+the
+.B \-a
+option,
+.B hashsum
+will emit a
+.RB ` #hash '
+directive in its output.
+.SH "SEE ALSO"
+.BR md5sum (1).
+.SH "AUTHOR"
+Mark Wooding, <mdw@nsict.org>
projects / u / mdw / catacomb / commitdiff