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 Assume that the files to be hashed are binary files. This doesn't make
124 any difference in Unix systems, although it might on other platforms
125 which draw a distinction.
127 .B "\-p, \-\-progress"
128 Display a progress indicator while hashing large files. The progress
129 indicator is written to standard error.
131 .B "\-v, \-\-verbose"
132 In conjunction with the
134 option above, be verbose when checking files.
136 If no filenames are given on the command line, standard input is read.
137 Standard input does not have a filename.
139 There are three types of line in
151 character. These directives are currently understood:
154 Subsequent hashes in this file were generated using the algorithm
157 .BI "#encoding " encoding
158 Subsequent hashes in this file are represented using the named
162 Filenames in subsequence lines are written using the `escaped' format,
167 consists of a hash, in the requested encoding, followed by a space, a
169 and the filename. The
173 to indicate that the file should be read in binary mode, or a space.
174 The rest of the line contains the filename.
178 line is one which doesn't look like a directive or a file line. Rubbish
179 lines are ignored. Hence, you can apply PGP clear-signing to a
181 file without preventing it from being read.
182 .SS "Escaping control characters"
183 When reading filenames to hash from a list of files or an escaped hash
184 list, the following rules are obeyed:
186 An escaped string cannot contain unescaped, unquoted whitespace
187 characters. If such a character is found, the string is considered to
192 escapes the following character. If the character is one of
201 it is replaced by the control character for an audible alert, backspace,
202 form-feed, newline, carriage return, horizontal tab or vertical tab
203 respectively; other escaped characters are unchanged, although they lose
204 any special meaning they might have had.
206 A section of text may be quoted by surrounding it by
211 pairs. Within a quoted section, whitespace characters may appear
212 unescaped. The backslash may be used to quote control characters or the
213 quoting characters as usual.
215 A word beginning with a hash
217 character is considered to begin a
219 which extends to the end of the current line. The hash character may be
221 .SS "Hashing algorithms"
224 program understands several hashing algorithms:
227 Designed by Ron Rivest, although I don't know when, and described in
228 RFC1319, MD2 is a really old and slow hash function. Its security is
229 suspect too: only its checksum stands between it and collision-finding
230 attacks. Use of MD2 is not recommended, though it's still used in
234 Designed by Ron Rivest in 1990 and 1992 respectively and described in
235 RFCs 1186, 1320 and 1321, these two early hash functions are efficient
236 but cryptographically suspect: the MD4 algorithm has been shown not to
237 be collision-resistant and there are `pseudo-collisions' in MD5.
240 has been used heavily since its introduction and is still popular. MD4
241 is still useful when a fast non-cryptographic hash is wanted.
244 Designed by the US National Security Agency as part of the Digital
245 Signature Standard, SHA-1 provides a longer output than
249 and is seen as being more secure.
251 .BR rmd128 ", " rmd160 ", " rmd256 " and " rmd320
252 Designed by Antoon Bosselaers, Hans Dobbertin and Bart Preneel in 1996
253 as a replacement for the earlier RIPEMD algorithm, RIPEMD160 provides
254 the same length output as SHA-1, but has been designed in the open by
255 experts. RIPEMD28 is a shortened version of RIPEMD160 designed as a
256 drop-in replacement for MD4, MD5 and the old RIPEMD. The 256 and
257 320-bit versions are efficient double-width extensions of the 128 and
258 160-bit hashes, although they may not offer any additional security.
261 Designed by Ross Anderson and Eli Biham to take advantage of 64-bit
262 processors, Tiger seems to be an efficient and strong hash function.
263 It's a relatively new algorithm, however, and should probably be
264 approached with an open-minded caution.
266 .BR sha256 ", " sha384 " and " sha512
267 Designed by the US National Security Agency to provide security
268 commensurate with the Advanced Encryption Standard, these hash functions
269 provide long outputs. SHA-256 is fairly quick, though the longer
270 variants are slower on 32-bit hardware since they require 64-bit
271 arithmetic. They're all very new at the moment, and should be
272 approached with an open-minded caution.
274 The default hashing algorithm is determined by looking at the name by
275 which it was invoked passed to it in
282 is the name of a hash function, that hash becomes the default. (Hence,
284 can be used as a drop-in replacement for
286 If the program name doesn't match an algorithm, then
288 is selected for compatibility with files generated by
291 Note that the same default algorithm is used for both generating new
292 output files and checking existing ones. If the algorithm is forced by
299 directive in its output.
300 .SH "COMPATIBILITY NOTES"
301 Once upon a time, there was only the
303 utility. As its name suggested, it calculated MD5 hashes of files. MD5
304 was shown to be weak, so the author wrote
306 to do the same job with other, hopefully stronger, hash functions. The
309 program tried hard to be compatible with GNU
311 but the latter has itself changed in incompatible ways since then;
313 has intentionally not changed to match.
317 features are not found in the GNU Coreutils hashing utilities.
319 Filename escaping (the
323 Magic comment lines in hash data to indicate algorithm selection, hash
324 encoding, and filename escaping.
326 Base-64 and Base-32 output.
328 Other differences are as follows.
332 was invoked without any filename arguments, it would print only the hash
333 of its stdin to stdout, which was very convenient for scripts which
334 manipulate hashes in nontrivial ways. This behaviour was later changed,
335 and now the GNU Coreutils hashing utilities always print a filename or
339 program follows the original
341 behaviour, and doesn't print a filename if no files were listed on the
349 Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blob