+++ /dev/null
-.\" -*-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" "Straylight/Edgeware" "Catacomb cryptographic library"
-.SH NAME
-hashsum \- compute and verify cryptographic checksums of files
-.SH SYNOPSIS
-.B hashsum
-.RB [ \-f0ecbjpv ]
-.RB [ \-a
-.IR algorithm ]
-.RB [ \-E
-.IR encoding ]
-.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 were originally designed to be upwardly
-compatible with the GNU
-.BR md5sum (1)
-program, but the two have diverged somewhat. See the
-.B "COMPATIBILITY NOTES"
-section of this manual for details.
-.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
-.BR "\-l, \-\-list " [ \fIitem ...]
-Show lists of hash functions and encodings supported.
-.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
-.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
-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 "\-j, \-\-junk"
-Report files whose hashes have not been checked. This is most useful in
-conjunction with
-.RB ` \-c ',
-though it's valid without. The program merely prints warnings about
-junk files when computing hashes, but will exit nonzero if any are found
-when checking them.
-.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 "\-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
-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. 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 the requested encoding, followed by a space, a
-.IR flag ,
-and the filename. 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 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
-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.
-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
-.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 "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 dsig (1),
-.BR catsign (1),
-.BR catcrypt (1).
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>
projects / u / mdw / catacomb / blobdiff