| blob | ec6dce034690f355c8470db6a88611bbf9382101 |
1 .\" $NetBSD: cksum.1,v 1.44 2012/06/25 02:32:12 riastradh 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 June 24, 2012
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 md2 ,
99 .Nm md4 ,
100 .Nm md5 ,
101 .Nm sha1 ,
102 and
103 .Nm rmd160
104 utilities compute cryptographic hash functions, and write to standard
105 output the hexadecimal representation of the hash of their input.
106 .Pp
107 The options are as follows:
108 .Bl -tag -width indent
109 .It Fl a Ar algorithm
110 When invoked as
111 .Nm cksum ,
112 use the specified
113 .Ar algorithm .
114 Valid algorithms are:
115 .Bl -column -offset indent ".Sy Algorithm" ".Sy Bits" ".Sy Description"
116 .It Sy Algorithm Ta Sy Bits Ta Sy Description
117 .It Li CRC Ta 32 Ta Default CRC algorithm
118 .It Li MD2 Ta 128 Ta MD2, per Li RFC1319
119 .It Li MD4 Ta 128 Ta MD4, per Li RFC1320
120 .It Li MD5 Ta 128 Ta MD5, per Li RFC1321
121 .It Li RMD160 Ta 160 Ta RIPEMD-160
122 .It Li SHA1 Ta 160 Ta SHA-1, per Li FIPS PUB 180-1
123 .It Li SHA256 Ta 256 Ta SHA-2
124 .It Li SHA384 Ta 384 Ta SHA-2
125 .It Li SHA512 Ta 512 Ta SHA-2
126 .It Li old1 Ta 16 Ta Algorithm 1, per Fl o Ar 1
127 .It Li old2 Ta 16 Ta Algorithm 2, per Fl o Ar 2
128 .El
129 .It Fl c Op Ar sumfile
130 Verify (check) files against a list of checksums.
131 The list is read from
132 .Ar sumfile ,
133 or from stdin if no filename is given.
134 E.g. first run
135 .Dl Ic md5 *.tgz \*[Gt] MD5
136 .Dl Ic sha1 *.tgz \*[Gt] SHA1
137 to generate a list of MD5 checksums in
138 .Pa MD5 ,
139 then use the following command to verify them:
140 .Dl Ic cat MD5 SHA1 | cksum -c
141 If an error is found during checksum verification, an error
142 message is printed, and the program returns an error code of 1.
143 .It Fl o
144 Use historic algorithms instead of the (superior) default one.
145 .Pp
146 Algorithm 1 is the algorithm used by historic
147 .Bx
148 systems as the
149 .Xr sum 1
150 algorithm and by historic
151 .At V
152 systems as the
153 .Xr sum 1
154 algorithm when using the
155 .Fl r
156 option.
157 This is a 16-bit checksum, with a right rotation before each addition;
158 overflow is discarded.
159 .Pp
160 Algorithm 2 is the algorithm used by historic
161 .At V
162 systems as the
163 default
164 .Xr sum 1
165 algorithm.
166 This is a 32-bit checksum, and is defined as follows:
167 .Bd -unfilled -offset indent
168 s = sum of all bytes;
169 r = s % 2^16 + (s % 2^32) / 2^16;
170 cksum = (r % 2^16) + r / 2^16;
171 .Ed
172 .Pp
173 Both algorithm 1 and 2 write to the standard output the same fields as
174 the default algorithm except that the size of the file in bytes is
175 replaced with the size of the file in blocks.
176 For historic reasons, the block size is 1024 for algorithm 1 and 512
177 for algorithm 2.
178 Partial blocks are rounded up.
179 .It Fl w
180 Print warnings about malformed checksum files when verifying
181 checksums with
182 .Fl c .
183 .El
184 .Pp
185 The following options apply only when using the one of the message
186 digest algorithms:
187 .Bl -tag -width indent
188 .It Fl n
189 Print the hash and the filename in the normal sum output form, with
190 the hash at the left and the filename following on the right.
191 .It Fl p
192 Echo input from standard input to standard output, and append the
193 selected message digest.
194 .It Fl s Ar string
195 Print the hash of the given string
196 .Ar string .
197 .It Fl t
198 Run a built-in message digest time trial.
199 .It Fl x
200 Run a built-in message digest test script.
201 The tests that are run
202 are supposed to encompass all the various tests in the suites that
203 accompany the algorithms' descriptions with the exception of the
204 last test for the SHA-1 algorithm and the RIPEMD-160 algorithm.
205 The
206 last test for these is one million copies of the lower letter a.
207 .El
208 .Pp
209 The default
210 .Tn CRC
211 used is based on the polynomial used for
212 .Tn CRC
213 error checking
214 in the networking standard
215 .St -iso8802-3 .
216 The
217 .Tn CRC
218 checksum encoding is defined by the generating polynomial:
219 .Pp
220 .Bd -unfilled -offset indent
221 G(x) = x^32 + x^26 + x^23 + x^22 + x^16 + x^12 +
222 x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
223 .Ed
224 .Pp
225 Mathematically, the
226 .Tn CRC
227 value corresponding to a given file is defined by
228 the following procedure:
229 .Bd -filled -offset indent
230 The
231 .Ar n
232 bits to be evaluated are considered to be the coefficients of a mod 2
233 polynomial M(x) of degree
234 .Ar n Ns \-1 .
235 These
236 .Ar n
237 bits are the bits from the file, with the most significant bit being the most
238 significant bit of the first octet of the file and the last bit being the least
239 significant bit of the last octet, padded with zero bits (if necessary) to
240 achieve an integral number of octets, followed by one or more octets
241 representing the length of the file as a binary value, least significant octet
242 first.
243 The smallest number of octets capable of representing this integer are used.
244 .Pp
245 M(x) is multiplied by x^32 (i.e., shifted left 32 bits) and divided by
246 G(x) using mod 2 division, producing a remainder R(x) of degree \*[Le] 31.
247 .Pp
248 The coefficients of R(x) are considered to be a 32-bit sequence.
249 .Pp
250 The bit sequence is complemented and the result is the CRC.
251 .Ed
252 .Pp
253 The
254 .Nm
255 and
256 .Nm sum
257 utilities exit 0 on success, and \*[Gt]0 if an error occurs.
258 .Sh SEE ALSO
259 .Xr openssl 1 ,
260 .Xr mtree 8
261 .Pp
262 The default calculation is identical to that given in pseudo-code
263 in the following
264 .Tn ACM
265 article.
266 .Rs
267 .%T "Computation of Cyclic Redundancy Checks Via Table Lookup"
268 .%A Dilip V. Sarwate
269 .%J "Communications of the \*(tNACM\*(sP"
270 .%D "August 1988"
271 .Re
272 .Rs
273 .%A R. Rivest
274 .%T The MD2 Message-Digest Algorithm
275 .%O RFC 1319
276 .Re
277 .Rs
278 .%A R. Rivest
279 .%T The MD4 Message-Digest Algorithm
280 .%O RFC 1186 and RFC 1320
281 .Re
282 .Rs
283 .%A R. Rivest
284 .%T The MD5 Message-Digest Algorithm
285 .%O RFC 1321
286 .Re
287 .Rs
288 .%A U.S. DOC/NIST
289 .%T Secure Hash Standard
290 .%O FIPS PUB 180-1
291 .Re
292 .Sh STANDARDS
293 The
294 .Nm
295 utility is expected to conform to
296 .St -p1003.1-2004 .
297 .Sh HISTORY
298 The
299 .Nm
300 utility appeared in
301 .Bx 4.4 .
302 .Nm md5
303 was added in
304 .Nx 1.3 .
305 The functionality for
306 .Nm md2 ,
307 .Nm md4 ,
308 .Nm sha1 ,
309 and
310 .Nm rmd160
311 was added in
312 .Nx 1.6 .
313 Support for the SHA-2 algorithms
314 .Po
315 .Li SHA256 ,
316 .Li SHA384 ,
317 and
318 .Li SHA512
319 .Pc
320 was added in
321 .Nx 3.0 .
322 The functionality to verify checksum stored in a file
323 .Pq Fl c
324 first appeared in
325 .Nx 4.0 .
326 .\" .Pp
327 .\" The
328 .\" .Nm sum
329 .\" utility appeared in
330 .\" .Bx ?.?
331 .\" and
332 .\" .At V .