From 4a3d0d5241b42c7be803ba3a79008bb29e6522c4 Mon Sep 17 00:00:00 2001 From: mdw Date: Sat, 29 Jul 2000 21:57:55 +0000 Subject: [PATCH] Manual page for the new `hashsum' program. --- hashsum.1 | 269 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 hashsum.1 diff --git a/hashsum.1 b/hashsum.1 new file mode 100644 index 0000000..d7598a9 --- /dev/null +++ b/hashsum.1 @@ -0,0 +1,269 @@ +.\" -*-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, -- 2.11.0