Annotation of src/usr.bin/cksum/cksum.1, Revision 1.6
1.6 ! deraadt 1: .\" $OpenBSD: cksum.1,v 1.5 1998/02/16 10:54:58 deraadt Exp $
1.1 deraadt 2: .\" $NetBSD: cksum.1,v 1.8 1995/09/02 05:45:15 jtc Exp $
3: .\"
4: .\" Copyright (c) 1991, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" the Institute of Electrical and Electronics Engineers, Inc.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. All advertising materials mentioning features or use of this software
19: .\" must display the following acknowledgement:
20: .\" This product includes software developed by the University of
21: .\" California, Berkeley and its contributors.
22: .\" 4. Neither the name of the University nor the names of its contributors
23: .\" may be used to endorse or promote products derived from this software
24: .\" without specific prior written permission.
25: .\"
26: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36: .\" SUCH DAMAGE.
37: .\"
38: .\" @(#)cksum.1 8.2 (Berkeley) 4/28/95
39: .\"
40: .Dd April 28, 1995
41: .Dt CKSUM 1
42: .Os BSD 4.4
43: .Sh NAME
44: .Nm cksum
45: .Nd display file checksums and block counts
46: .Sh SYNOPSIS
47: .Nm cksum
48: .Op Fl o Ar \&1 No \&| Ar \&2
49: .Op Ar file ...
50: .Nm sum
51: .Op Ar file ...
52: .Sh DESCRIPTION
53: The
54: .Nm cksum
55: utility writes to the standard output three whitespace separated
56: fields for each input file.
57: These fields are a checksum
58: .Tn CRC ,
59: the total number of octets in the file and the file name.
60: If no file name is specified, the standard input is used and no file name
61: is written.
62: .Pp
63: The
64: .Nm sum
65: utility is identical to the
66: .Nm cksum
67: utility, except that it defaults to using historic algorithm 1, as
68: described below.
69: It is provided for compatibility only.
70: .Pp
71: The options are as follows:
72: .Bl -tag -width indent
73: .It Fl o
74: Use historic algorithms instead of the (superior) default one.
75: .Pp
76: Algorithm 1 is the algorithm used by historic
77: .Bx
78: systems as the
79: .Xr sum 1
80: algorithm and by historic
81: .At V
82: systems as the
83: .Xr sum
84: algorithm when using the
85: .Fl r
86: option.
87: This is a 16-bit checksum, with a right rotation before each addition;
88: overflow is discarded.
89: .Pp
90: Algorithm 2 is the algorithm used by historic
91: .At V
92: systems as the
93: default
94: .Xr sum
95: algorithm.
96: This is a 32-bit checksum, and is defined as follows:
97: .Bd -unfilled -offset indent
98: s = sum of all bytes;
99: r = s % 2^16 + (s % 2^32) / 2^16;
100: cksum = (r % 2^16) + r / 2^16;
101: .Ed
102: .Pp
103: Both algorithm 1 and 2 write to the standard output the same fields as
104: the default algorithm except that the size of the file in bytes is
105: replaced with the size of the file in blocks.
106: For historic reasons, the block size is 1024 for algorithm 1 and 512
107: for algorithm 2.
108: Partial blocks are rounded up.
109: .El
110: .Pp
111: The default
112: .Tn CRC
113: used is based on the polynomial used for
114: .Tn CRC
115: error checking
116: in the networking standard
117: .St -iso8802-3
118: The
119: .Tn CRC
120: checksum encoding is defined by the generating polynomial:
121: .Pp
122: .Bd -unfilled -offset indent
123: G(x) = x^32 + x^26 + x^23 + x^22 + x^16 + x^12 +
124: x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
125: .Ed
126: .Pp
127: Mathematically, the
128: .Tn CRC
129: value corresponding to a given file is defined by
130: the following procedure:
131: .Bd -filled -offset indent
132: The
133: .Ar n
134: bits to be evaluated are considered to be the coefficients of a mod 2
135: polynomial M(x) of degree
136: .Ar n Ns \-1 .
137: These
138: .Ar n
139: bits are the bits from the file, with the most significant bit being the most
140: significant bit of the first octet of the file and the last bit being the least
141: significant bit of the last octet, padded with zero bits (if necessary) to
142: achieve an integral number of octets, followed by one or more octets
143: representing the length of the file as a binary value, least significant octet
144: first.
145: The smallest number of octets capable of representing this integer are used.
146: .Pp
147: M(x) is multiplied by x^32 (i.e., shifted left 32 bits) and divided by
148: G(x) using mod 2 division, producing a remainder R(x) of degree <= 31.
149: .Pp
150: The coefficients of R(x) are considered to be a 32-bit sequence.
151: .Pp
152: The bit sequence is complemented and the result is the CRC.
153: .Ed
154: .Pp
155: The
156: .Nm cksum
157: and
158: .Nm sum
159: utilities exit 0 on success, and >0 if an error occurs.
1.3 bitblt 160: .Sh WARNING
161: Do not use
162: .Nm sum
163: or
164: .Nm cksum
165: to detect hostile binary modifications. An attacker
166: can trivially produce backdoored daemons which have the same CRC as the
167: standard versions. Use a cryptographic checksum, such as MD5 instead.
1.1 deraadt 168: .Sh SEE ALSO
1.6 ! deraadt 169: .Xr md5 1 ,
! 170: .Xr rmd160 1 ,
! 171: .Xr sha1 1
1.5 deraadt 172: .Pp
1.1 deraadt 173: The default calculation is identical to that given in pseudo-code
174: in the following
175: .Tn ACM
176: article.
177: .Rs
178: .%T "Computation of Cyclic Redundancy Checks Via Table Lookup"
179: .%A Dilip V. Sarwate
180: .%J "Communications of the \\*(tNACM\\*(sP"
181: .%D "August 1988"
182: .Re
183: .Sh STANDARDS
184: The
185: .Nm cksum
1.4 denny 186: utility is compliant with the
187: .St -p1003.2-92
188: specification.
1.1 deraadt 189: .Sh HISTORY
190: The
191: .Nm cksum
192: utility appeared in
193: .Bx 4.4 .
194: .\" .Pp
195: .\" The
196: .\" .Nm sum
197: .\" utility appeared in
198: .\" .Bx ?.?
199: .\" and
200: .\" .At V .