X-Git-Url: https://git.distorted.org.uk/u/mdw/catacomb/blobdiff_plain/d07dfe80efdb7969c7a4c2b3a22629836bd2c87e..e564e3f84ad0ea42b78559c0bfe304893fd5e76b:/hashsum.1 diff --git a/hashsum.1 b/hashsum.1 index 96e19ae..bc956d0 100644 --- a/hashsum.1 +++ b/hashsum.1 @@ -12,9 +12,11 @@ hashsum \- compute and verify cryptographic checksums of files .SH SYNOPSIS .B hashsum -.RB [ \-f0ecbv ] +.RB [ \-f0ecbpv ] .RB [ \-a .IR algorithm ] +.RB [ \-E +.IR encoding ] .IR files ... .SH DESCRIPTION The @@ -24,10 +26,12 @@ 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 +program's options and output were originally designed to be upwardly +compatible with the GNU .BR md5sum (1) -program. +program, but the two have diverged somewhat. See the +.B "COMPATIBILITY NOTES" +section of this manual for details. .PP Usually, .B hashsum @@ -52,6 +56,9 @@ successfully. .B "\-u, \-\-usage" Prints a brief usage summary to standard output and exits successfully. .TP +.BR "\-l, \-\-list " [ \fIitem ...] +Show lists of hash functions and encodings supported. +.TP .BI "\-a, \-\-algorithm=" alg Use the hash algorithm .IR alg . @@ -60,9 +67,20 @@ see .B "Hashing algorithms" below. .TP -.B "\-l, \-\-list" -Prints a space-separated list of available hashing algorithms to -standard output and exits successfully. +.BI "\-E, \-\-encoding=" encoding +Use the given +.I encoding +to represent hashes in the output. This is not interoperable with other +programs, but it's handy, e.g., for building sha1 URNs. The encodings +recognized are +.B hex +(the default), +.B base64 +and +.BR base32 . +Type +.B hashsum \-\-list enc +for a list of supported encodings. .TP .B "\-f, \-\-files" Each input file is considered to be a list of filenames which should be @@ -106,6 +124,10 @@ 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 "\-p, \-\-progress" +Display a progress indicator while hashing large files. The progress +indicator is written to standard error. +.TP .B "\-v, \-\-verbose" In conjunction with the .B \-c @@ -126,25 +148,25 @@ A .I directive begins with a hash .RB (` # ') -character. Two directives are currently understood: +character. These directives are currently understood: .TP .BI "#hash " alg Subsequent hashes in this file were generated using the algorithm .IR alg . .TP +.BI "#encoding " encoding +Subsequent hashes in this file are represented using the named +.IR encoding . +.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 +consists of a hash, in the requested encoding, 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 +and the filename. The .I flag is either a star .RB (` * ') @@ -201,6 +223,13 @@ The .B hashsum program understands several hashing algorithms: .TP +.BR md2 +Designed by Ron Rivest, although I don't know when, and described in +RFC1319, MD2 is a really old and slow hash function. Its security is +suspect too: only its checksum stands between it and collision-finding +attacks. Use of MD2 is not recommended, though it's still used in +various standards. +.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 @@ -231,11 +260,16 @@ drop-in replacement for MD4, MD5 and the old RIPEMD. The 256 and .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. +.TP +.BR sha256 ", " sha384 " and " sha512 +Designed by the US National Security Agency to provide security +commensurate with the Advanced Encryption Standard, these hash functions +provide long outputs. SHA-256 is fairly quick, though the longer +variants are slower on 32-bit hardware since they require 64-bit +arithmetic. They're all very new at the moment, and should 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 @@ -263,7 +297,53 @@ option, will emit a .RB ` #hash ' directive in its output. +.SH "COMPATIBILITY NOTES" +Once upon a time, there was only the +.BR md5sum (1) +utility. As its name suggested, it calculated MD5 hashes of files. MD5 +was shown to be weak, so the author wrote +.B hashsum +to do the same job with other, hopefully stronger, hash functions. The +original +.B hashsum +program tried hard to be compatible with GNU +.BR md5sum (1), +but the latter has itself changed in incompatible ways since then; +.B hashsum +has intentionally not changed to match. +.PP +The following +.B hashsum +features are not found in the GNU Coreutils hashing utilities. +.hP +Filename escaping (the +.B \-e +option). +.hP +Magic comment lines in hash data to indicate algorithm selection, hash +encoding, and filename escaping. +.hP +Base-64 and Base-32 output. +.PP +Other differences are as follows. +.hP +Originally, if GNU +.B md5sum +was invoked without any filename arguments, it would print only the hash +of its stdin to stdout, which was very convenient for scripts which +manipulate hashes in nontrivial ways. This behaviour was later changed, +and now the GNU Coreutils hashing utilities always print a filename or +.RB ` \- ' +after the hash. The +.B hashsum +program follows the original +.B md5sum +behaviour, and doesn't print a filename if no files were listed on the +command line. .SH "SEE ALSO" -.BR md5sum (1). +.BR md5sum (1), +.BR dsig (1), +.BR catsign (1), +.BR catcrypt (1). .SH "AUTHOR" -Mark Wooding, +Mark Wooding,