| blob | fde17c966b163dbebf25201e6ea78d01cf2eac73 |
1 .\" $NetBSD: cksum.1,v 1.41 2009/01/02 09:42:51 lukem Exp $
2 .\"
3 .\" Copyright (c) 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to Berkeley by
7 .\" the Institute of Electrical and Electronics Engineers, Inc.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .\" @(#)cksum.1 8.2 (Berkeley) 4/28/95
34 .\"
35 .Dd January 2, 2009
36 .Dt CKSUM 1
37 .Os
38 .Sh NAME
39 .Nm cksum ,
40 .Nm md2 ,
41 .Nm md4 ,
42 .Nm md5 ,
43 .Nm rmd160 ,
44 .Nm sha1 ,
45 .Nm sum
46 .Nd display file checksums and block counts
47 .Sh SYNOPSIS
48 .Nm cksum
49 .Op Fl n
50 .Op Fl a Ar algorithm Oo Fl ptx Oc Oo Fl s Ar string Oc
51 .Op Fl o Ar 1 Ns | Ns Ar 2
52 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
53 .Nm sum
54 .Op Fl n
55 .Op Fl a Ar algorithm Oo Fl ptx Oc Oo Fl s Ar string Oc
56 .Op Fl o Ar 1 Ns | Ns Ar 2
57 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
58 .Nm md2
59 .Op Fl nptx
60 .Op Fl s Ar string
61 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
62 .Nm md4
63 .Op Fl nptx
64 .Op Fl s Ar string
65 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
66 .Nm md5
67 .Op Fl nptx
68 .Op Fl s Ar string
69 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
70 .Nm rmd160
71 .Op Fl nptx
72 .Op Fl s Ar string
73 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
74 .Nm sha1
75 .Op Fl nptx
76 .Op Fl s Ar string
77 .Op Ar Li \&| Fl c Oo Fl w Oc Oo Ar sumfile Oc
78 .Sh DESCRIPTION
79 The
80 .Nm
81 utility writes to the standard output three whitespace separated
82 fields for each input file.
83 These fields are a checksum
84 .Tn CRC ,
85 the total number of octets in the file and the file name.
86 If no file name is specified, the standard input is used and no file name
87 is written.
88 .Pp
89 The
90 .Nm sum
91 utility is identical to the
92 .Nm
93 utility, except that it defaults to using historic algorithm 1, as
94 described below.
95 It is provided for compatibility only.
96 .Pp
97 The
98 .Nm md5
99 utility takes as input a message of arbitrary length and produces
100 as output a 128-bit
101 .Dq fingerprint
102 or
103 .Dq message digest
104 of the input.
105 It is conjectured that it is computationally infeasible
106 to product two messages having the same message digest, or to produce
107 any message having a given prespecified target message digest.
108 The
109 MD5 algorithm is intended for digital signature applications, where
110 a large file must be
111 .Dq compressed
112 in a secure manner before being encrypted with a private (secret)
113 key under a public-key encryption system such as
114 .Pa RSA .
115 .Pp
116 The
117 .Nm md2
118 and
119 .Nm md4
120 utilities behave in exactly the same manner as
121 .Nm md5
122 but use different algorithms.
123 .Pp
124 The
125 .Nm rmd160
126 and
127 .Nm sha1
128 utilities also produce message digests, however the output from these
129 two programs is 160 bits in length, as opposed to 128.
130 .Pp
131 The options are as follows:
132 .Bl -tag -width indent
133 .It Fl a Ar algorithm
134 When invoked as
135 .Nm cksum ,
136 use the specified
137 .Ar algorithm .
138 Valid algorithms are:
139 .Bl -column -offset indent ".Sy Algorithm" ".Sy Bits" ".Sy Description"
140 .It Sy Algorithm Ta Sy Bits Ta Sy Description
141 .It Li CRC Ta 32 Ta Default CRC algorithm
142 .It Li MD2 Ta 128 Ta MD2, per Li RFC1319
143 .It Li MD4 Ta 128 Ta MD4, per Li RFC1320
144 .It Li MD5 Ta 128 Ta MD5, per Li RFC1321
145 .It Li RMD160 Ta 160 Ta RIPEMD-160
146 .It Li SHA1 Ta 160 Ta SHA-1, per Li FIPS PUB 180-1
147 .It Li SHA256 Ta 256 Ta SHA-2
148 .It Li SHA384 Ta 384 Ta SHA-2
149 .It Li SHA512 Ta 512 Ta SHA-2
150 .It Li old1 Ta 16 Ta Algorithm 1, per Fl o Ar 1
151 .It Li old2 Ta 16 Ta Algorithm 2, per Fl o Ar 2
152 .El
153 .It Fl c Op Ar sumfile
154 Verify (check) files against a list of checksums.
155 The list is read from
156 .Ar sumfile ,
157 or from stdin if no filename is given.
158 E.g. first run
159 .Dl Ic md5 *.tgz \*[Gt] MD5
160 .Dl Ic sha1 *.tgz \*[Gt] SHA1
161 to generate a list of MD5 checksums in
162 .Pa MD5 ,
163 then use the following command to verify them:
164 .Dl Ic cat MD5 SHA1 | cksum -c
165 If an error is found during checksum verification, an error
166 message is printed, and the program returns an error code of 1.
167 .It Fl o
168 Use historic algorithms instead of the (superior) default one.
169 .Pp
170 Algorithm 1 is the algorithm used by historic
171 .Bx
172 systems as the
173 .Xr sum 1
174 algorithm and by historic
175 .At V
176 systems as the
177 .Xr sum 1
178 algorithm when using the
179 .Fl r
180 option.
181 This is a 16-bit checksum, with a right rotation before each addition;
182 overflow is discarded.
183 .Pp
184 Algorithm 2 is the algorithm used by historic
185 .At V
186 systems as the
187 default
188 .Xr sum 1
189 algorithm.
190 This is a 32-bit checksum, and is defined as follows:
191 .Bd -unfilled -offset indent
192 s = sum of all bytes;
193 r = s % 2^16 + (s % 2^32) / 2^16;
194 cksum = (r % 2^16) + r / 2^16;
195 .Ed
196 .Pp
197 Both algorithm 1 and 2 write to the standard output the same fields as
198 the default algorithm except that the size of the file in bytes is
199 replaced with the size of the file in blocks.
200 For historic reasons, the block size is 1024 for algorithm 1 and 512
201 for algorithm 2.
202 Partial blocks are rounded up.
203 .It Fl w
204 Print warnings about malformed checksum files when verifying
205 checksums with
206 .Fl c .
207 .El
208 .Pp
209 The following options apply only when using the one of the message
210 digest algorithms:
211 .Bl -tag -width indent
212 .It Fl n
213 Print the hash and the filename in the normal sum output form, with
214 the hash at the left and the filename following on the right.
215 .It Fl p
216 Echo input from standard input to standard output, and append the
217 selected message digest.
218 .It Fl s Ar string
219 Print the hash of the given string
220 .Ar string .
221 .It Fl t
222 Run a built-in message digest time trial.
223 .It Fl x
224 Run a built-in message digest test script.
225 The tests that are run
226 are supposed to encompass all the various tests in the suites that
227 accompany the algorithms' descriptions with the exception of the
228 last test for the SHA-1 algorithm and the RIPEMD-160 algorithm.
229 The
230 last test for these is one million copies of the lower letter a.
231 .El
232 .Pp
233 The default
234 .Tn CRC
235 used is based on the polynomial used for
236 .Tn CRC
237 error checking
238 in the networking standard
239 .St -iso8802-3 .
240 The
241 .Tn CRC
242 checksum encoding is defined by the generating polynomial:
243 .Pp
244 .Bd -unfilled -offset indent
245 G(x) = x^32 + x^26 + x^23 + x^22 + x^16 + x^12 +
246 x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
247 .Ed
248 .Pp
249 Mathematically, the
250 .Tn CRC
251 value corresponding to a given file is defined by
252 the following procedure:
253 .Bd -filled -offset indent
254 The
255 .Ar n
256 bits to be evaluated are considered to be the coefficients of a mod 2
257 polynomial M(x) of degree
258 .Ar n Ns \-1 .
259 These
260 .Ar n
261 bits are the bits from the file, with the most significant bit being the most
262 significant bit of the first octet of the file and the last bit being the least
263 significant bit of the last octet, padded with zero bits (if necessary) to
264 achieve an integral number of octets, followed by one or more octets
265 representing the length of the file as a binary value, least significant octet
266 first.
267 The smallest number of octets capable of representing this integer are used.
268 .Pp
269 M(x) is multiplied by x^32 (i.e., shifted left 32 bits) and divided by
270 G(x) using mod 2 division, producing a remainder R(x) of degree \*[Le] 31.
271 .Pp
272 The coefficients of R(x) are considered to be a 32-bit sequence.
273 .Pp
274 The bit sequence is complemented and the result is the CRC.
275 .Ed
276 .Pp
277 The
278 .Nm
279 and
280 .Nm sum
281 utilities exit 0 on success, and \*[Gt]0 if an error occurs.
282 .Sh SEE ALSO
283 .Xr openssl 1 ,
284 .Xr mtree 8
285 .Pp
286 The default calculation is identical to that given in pseudo-code
287 in the following
288 .Tn ACM
289 article.
290 .Rs
291 .%T "Computation of Cyclic Redundancy Checks Via Table Lookup"
292 .%A Dilip V. Sarwate
293 .%J "Communications of the \\*(tNACM\\*(sP"
294 .%D "August 1988"
295 .Re
296 .Rs
297 .%A R. Rivest
298 .%T The MD2 Message-Digest Algorithm
299 .%O RFC 1319
300 .Re
301 .Rs
302 .%A R. Rivest
303 .%T The MD4 Message-Digest Algorithm
304 .%O RFC 1186 and RFC 1320
305 .Re
306 .Rs
307 .%A R. Rivest
308 .%T The MD5 Message-Digest Algorithm
309 .%O RFC 1321
310 .Re
311 .Rs
312 .%A U.S. DOC/NIST
313 .%T Secure Hash Standard
314 .%O FIPS PUB 180-1
315 .Re
316 .Sh STANDARDS
317 The
318 .Nm
319 utility is expected to conform to
320 .St -p1003.1-2004 .
321 .Sh HISTORY
322 The
323 .Nm
324 utility appeared in
325 .Bx 4.4 .
326 .Nm md5
327 was added in
328 .Nx 1.3 .
329 The functionality for
330 .Nm md2 ,
331 .Nm md4 ,
332 .Nm sha1 ,
333 and
334 .Nm rmd160
335 was added in
336 .Nx 1.6 .
337 Support for the SHA-2 algorithms
338 .Po
339 .Li SHA256 ,
340 .Li SHA384 ,
341 and
342 .Li SHA512
343 .Pc
344 was added in
345 .Nx 3.0 .
346 The functionality to verify checksum stored in a file
347 .Pq Fl c
348 first appeared in
349 .Nx 4.0 .
350 .\" .Pp
351 .\" The
352 .\" .Nm sum
353 .\" utility appeared in
354 .\" .Bx ?.?
355 .\" and
356 .\" .At V .