5 \h'-\w'\\$1\ 'u'\\$1\ \c
10 .TH hashsum 1 "29 July 2000" "Straylight/Edgeware" "Catacomb cryptographic library"
12 hashsum \- compute and verify cryptographic checksums of files
24 program generates and verifies cryptographic checksums (hashes) of
25 files. A number of hashing algorithms are available.
29 program's options and output are designed to be upwardly compatible with
36 generates checksums of a collection of files named either on the command
37 line or read from standard input, and write their hashes to standard
38 output using a simple file format. However, given the
40 option, it will read in files in its usual output format and verify that
41 the named files have the reported hashes.
45 program understands the following options:
48 Prints a help message to standard output and exits successfully.
51 Prints the program's version number to standard output and exits
55 Prints a brief usage summary to standard output and exits successfully.
57 .BR "\-l, \-\-list " [ \fIitem ...]
58 Show lists of hash functions and encodings supported.
60 .BI "\-a, \-\-algorithm=" alg
61 Use the hash algorithm
63 If this option is not given, a default hashing algorithm is selected:
65 .B "Hashing algorithms"
68 .BI "\-E, \-\-encoding=" encoding
71 to represent hashes in the output. This is not interoperable with other
72 programs, but it's handy, e.g., for building sha1 URNs. The encodings
80 .B hashsum \-\-list enc
81 for a list of supported encodings.
84 Each input file is considered to be a list of filenames which should be
85 read and hashed. By default, the filenames are considered to be
86 whitespace-separated, although control characters can be escaped (see
87 .B "Escaping control characters"
91 In conjunction with the
93 option above, reads null-terminated filenames, as emitted by GNU
96 option, rather than whitespace-delimited filenames. If the
98 option is also given, each named in the list is a list of filename/hash
102 Escape control characters (see
103 .B "Escaping control characters"
104 below) in filenames when generating output. Escaped
105 output is not compatible with
107 but copes better with files containing newlines and other strange
111 Check hashes. Each input file is assumed to be in
113 output format. It is read, and
115 will verify that each named file has the correct hash. Assuming that
116 the hash list is authentic (e.g., it has been digitally signed, or
117 obtained via some secure medium), this provides strong assurance that
118 the files listed have not been tampered with.
121 Assume that the files to be hashed are binary files. This doesn't make
122 any difference in Unix systems, although it might on other platforms
123 which draw a distinction.
125 .B "\-p, \-\-progress"
126 Display a progress indicator while hashing large files. The progress
127 indicator is written to standard error.
129 .B "\-v, \-\-verbose"
130 In conjunction with the
132 option above, be verbose when checking files.
134 If no filenames are given on the command line, standard input is read.
135 Standard input does not have a filename.
137 There are three types of line in
149 character. Two directives are currently understood:
152 Subsequent hashes in this file were generated using the algorithm
155 .BI "#encoding " encoding
156 Subsequent hashes in this file are represented using the named
160 Filenames in subsequence lines are written using the `escaped' format,
165 consists of a hash, in the requested encoding, followed by a space, a
167 and the filename. The
171 to indicate that the file should be read in binary mode, or a space.
172 The rest of the line contains the filename.
176 line is one which doesn't look like a directive or a file line. Rubbish
177 lines are ignored. Hence, you can apply PGP clear-signing to a
179 file without preventing it from being read.
180 .SS "Escaping control characters"
181 When reading filenames to hash from a list of files or an escaped hash
182 list, the following rules are obeyed:
184 An escaped string cannot contain unescaped, unquoted whitespace
185 characters. If such a character is found, the string is considered to
190 escapes the following character. If the character is one of
199 it is replaced by the control character for an audible alert, backspace,
200 form-feed, newline, carriage return, horizontal tab or vertical tab
201 respectively; other escaped characters are unchanged, although they lose
202 any special meaning they might have had.
204 A section of text may be quoted by surrounding it by
209 pairs. Within a quoted section, whitespace characters may appear
210 unescaped. The backslash may be used to quote control characters or the
211 quoting characters as usual.
213 A word beginning with a hash
215 character is considered to begin a
217 which extends to the end of the current line. The hash character may be
219 .SS "Hashing algorithms"
222 program understands several hashing algorithms:
225 Designed by Ron Rivest, although I don't know when, and described in
226 RFC1319, MD2 is a really old and slow hash function. Its security is
227 suspect too: only its checksum stands between it and collision-finding
228 attacks. Use of MD2 is not recommended, though it's still used in
232 Designed by Ron Rivest in 1990 and 1992 respectively and described in
233 RFCs 1186, 1320 and 1321, these two early hash functions are efficient
234 but cryptographically suspect: the MD4 algorithm has been shown not to
235 be collision-resistant and there are `pseudo-collisions' in MD5.
238 has been used heavily since its introduction and is still popular. MD4
239 is still useful when a fast non-cryptographic hash is wanted.
242 Designed by the US National Security Agency as part of the Digital
243 Signature Standard, SHA-1 provides a longer output than
247 and is seen as being more secure.
249 .BR rmd128 ", " rmd160 ", " rmd256 " and " rmd320
250 Designed by Antoon Bosselaers, Hans Dobbertin and Bart Preneel in 1996
251 as a replacement for the earlier RIPEMD algorithm, RIPEMD160 provides
252 the same length output as SHA-1, but has been designed in the open by
253 experts. RIPEMD28 is a shortened version of RIPEMD160 designed as a
254 drop-in replacement for MD4, MD5 and the old RIPEMD. The 256 and
255 320-bit versions are efficient double-width extensions of the 128 and
256 160-bit hashes, although they may not offer any additional security.
259 Designed by Ross Anderson and Eli Biham to take advantage of 64-bit
260 processors, Tiger seems to be an efficient and strong hash function.
261 It's a relatively new algorithm, however, and should probably be
262 approached with an open-minded caution.
264 .BR sha256 ", " sha384 " and " sha512
265 Designed by the US National Security Agency to provide security
266 commensurate with the Advanced Encryption Standard, these hash functions
267 provide long outputs. SHA-256 is fairly quick, though the longer
268 variants are slower on 32-bit hardware since they require 64-bit
269 arithmetic. They're all very new at the moment, and should be
270 approached with an open-minded caution.
272 The default hashing algorithm is determined by looking at the name by
273 which it was invoked passed to it in
280 is the name of a hash function, that hash becomes the default. (Hence,
282 can be used as a drop-in replacement for
284 If the program name doesn't match an algorithm, then
286 is selected for compatibility with files generated by
289 Note that the same default algorithm is used for both generating new
290 output files and checking existing ones. If the algorithm is forced by
297 directive in its output.
304 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob