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