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 were originally designed to be upwardly
30 compatible with the GNU
32 program, but the two have diverged somewhat. See the
33 .B "COMPATIBILITY NOTES"
34 section of this manual for details.
38 generates checksums of a collection of files named either on the command
39 line or read from standard input, and write their hashes to standard
40 output using a simple file format. However, given the
42 option, it will read in files in its usual output format and verify that
43 the named files have the reported hashes.
47 program understands the following options:
50 Prints a help message to standard output and exits successfully.
53 Prints the program's version number to standard output and exits
57 Prints a brief usage summary to standard output and exits successfully.
59 .BR "\-l, \-\-list " [ \fIitem ...]
60 Show lists of hash functions and encodings supported.
62 .BI "\-a, \-\-algorithm=" alg
63 Use the hash algorithm
65 If this option is not given, a default hashing algorithm is selected:
67 .B "Hashing algorithms"
70 .BI "\-E, \-\-encoding=" encoding
73 to represent hashes in the output. This is not interoperable with other
74 programs, but it's handy, e.g., for building sha1 URNs. The encodings
82 .B hashsum \-\-list enc
83 for a list of supported encodings.
86 Each input file is considered to be a list of filenames which should be
87 read and hashed. By default, the filenames are considered to be
88 whitespace-separated, although control characters can be escaped (see
89 .B "Escaping control characters"
93 In conjunction with the
95 option above, reads null-terminated filenames, as emitted by GNU
98 option, rather than whitespace-delimited filenames. If the
100 option is also given, each named in the list is a list of filename/hash
104 Escape control characters (see
105 .B "Escaping control characters"
106 below) in filenames when generating output. Escaped
107 output is not compatible with
109 but copes better with files containing newlines and other strange
113 Check hashes. Each input file is assumed to be in
115 output format. It is read, and
117 will verify that each named file has the correct hash. Assuming that
118 the hash list is authentic (e.g., it has been digitally signed, or
119 obtained via some secure medium), this provides strong assurance that
120 the files listed have not been tampered with.
123 Report files whose hashes have not been checked. This is most useful in
126 though it's valid without. The program merely prints warnings about
127 junk files when computing hashes, but will exit nonzero if any are found
131 Assume that the files to be hashed are binary files. This doesn't make
132 any difference in Unix systems, although it might on other platforms
133 which draw a distinction.
135 .B "\-p, \-\-progress"
136 Display a progress indicator while hashing large files. The progress
137 indicator is written to standard error.
139 .B "\-v, \-\-verbose"
140 In conjunction with the
142 option above, be verbose when checking files.
144 If no filenames are given on the command line, standard input is read.
145 Standard input does not have a filename.
147 There are three types of line in
159 character. These directives are currently understood:
162 Subsequent hashes in this file were generated using the algorithm
165 .BI "#encoding " encoding
166 Subsequent hashes in this file are represented using the named
170 Filenames in subsequence lines are written using the `escaped' format,
175 consists of a hash, in the requested encoding, followed by a space, a
177 and the filename. The
181 to indicate that the file should be read in binary mode, or a space.
182 The rest of the line contains the filename.
186 line is one which doesn't look like a directive or a file line. Rubbish
187 lines are ignored. Hence, you can apply PGP clear-signing to a
189 file without preventing it from being read.
190 .SS "Escaping control characters"
191 When reading filenames to hash from a list of files or an escaped hash
192 list, the following rules are obeyed:
194 An escaped string cannot contain unescaped, unquoted whitespace
195 characters. If such a character is found, the string is considered to
200 escapes the following character. If the character is one of
209 it is replaced by the control character for an audible alert, backspace,
210 form-feed, newline, carriage return, horizontal tab or vertical tab
211 respectively; other escaped characters are unchanged, although they lose
212 any special meaning they might have had.
214 A section of text may be quoted by surrounding it by
219 pairs. Within a quoted section, whitespace characters may appear
220 unescaped. The backslash may be used to quote control characters or the
221 quoting characters as usual.
223 A word beginning with a hash
225 character is considered to begin a
227 which extends to the end of the current line. The hash character may be
229 .SS "Hashing algorithms"
232 program understands several hashing algorithms:
235 Designed by Ron Rivest, although I don't know when, and described in
236 RFC1319, MD2 is a really old and slow hash function. Its security is
237 suspect too: only its checksum stands between it and collision-finding
238 attacks. Use of MD2 is not recommended, though it's still used in
242 Designed by Ron Rivest in 1990 and 1992 respectively and described in
243 RFCs 1186, 1320 and 1321, these two early hash functions are efficient
244 but cryptographically suspect: the MD4 algorithm has been shown not to
245 be collision-resistant and there are `pseudo-collisions' in MD5.
248 has been used heavily since its introduction and is still popular. MD4
249 is still useful when a fast non-cryptographic hash is wanted.
252 Designed by the US National Security Agency as part of the Digital
253 Signature Standard, SHA-1 provides a longer output than
257 and is seen as being more secure.
259 .BR rmd128 ", " rmd160 ", " rmd256 " and " rmd320
260 Designed by Antoon Bosselaers, Hans Dobbertin and Bart Preneel in 1996
261 as a replacement for the earlier RIPEMD algorithm, RIPEMD160 provides
262 the same length output as SHA-1, but has been designed in the open by
263 experts. RIPEMD28 is a shortened version of RIPEMD160 designed as a
264 drop-in replacement for MD4, MD5 and the old RIPEMD. The 256 and
265 320-bit versions are efficient double-width extensions of the 128 and
266 160-bit hashes, although they may not offer any additional security.
269 Designed by Ross Anderson and Eli Biham to take advantage of 64-bit
270 processors, Tiger seems to be an efficient and strong hash function.
271 It's a relatively new algorithm, however, and should probably be
272 approached with an open-minded caution.
274 .BR sha256 ", " sha384 " and " sha512
275 Designed by the US National Security Agency to provide security
276 commensurate with the Advanced Encryption Standard, these hash functions
277 provide long outputs. SHA-256 is fairly quick, though the longer
278 variants are slower on 32-bit hardware since they require 64-bit
279 arithmetic. They're all very new at the moment, and should be
280 approached with an open-minded caution.
282 The default hashing algorithm is determined by looking at the name by
283 which it was invoked passed to it in
290 is the name of a hash function, that hash becomes the default. (Hence,
292 can be used as a drop-in replacement for
294 If the program name doesn't match an algorithm, then
296 is selected for compatibility with files generated by
299 Note that the same default algorithm is used for both generating new
300 output files and checking existing ones. If the algorithm is forced by
307 directive in its output.
308 .SH "COMPATIBILITY NOTES"
309 Once upon a time, there was only the
311 utility. As its name suggested, it calculated MD5 hashes of files. MD5
312 was shown to be weak, so the author wrote
314 to do the same job with other, hopefully stronger, hash functions. The
317 program tried hard to be compatible with GNU
319 but the latter has itself changed in incompatible ways since then;
321 has intentionally not changed to match.
325 features are not found in the GNU Coreutils hashing utilities.
327 Filename escaping (the
331 Magic comment lines in hash data to indicate algorithm selection, hash
332 encoding, and filename escaping.
334 Base-64 and Base-32 output.
336 Other differences are as follows.
340 was invoked without any filename arguments, it would print only the hash
341 of its stdin to stdout, which was very convenient for scripts which
342 manipulate hashes in nontrivial ways. This behaviour was later changed,
343 and now the GNU Coreutils hashing utilities always print a filename or
347 program follows the original
349 behaviour, and doesn't print a filename if no files were listed on the
357 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob