libgo/go/hash/crc32/crc32.go

   1 // Copyright 2009 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 // Package crc32 implements the 32-bit cyclic redundancy check, or CRC-32,
   6 // checksum. See https://en.wikipedia.org/wiki/Cyclic_redundancy_check for
   7 // information.
   8 //
   9 // Polynomials are represented in LSB-first form also known as reversed representation.
  10 //
  11 // See https://en.wikipedia.org/wiki/Mathematics_of_cyclic_redundancy_checks#Reversed_representations_and_reciprocal_polynomials
  12 // for information.
  13 package crc32
  14
  15 import (
  16         "errors"
  17         "hash"
  18         "sync"
  19         "sync/atomic"
  20 )
  21
  22 // The size of a CRC-32 checksum in bytes.
  23 const Size = 4
  24
  25 // Predefined polynomials.
  26 const (
  27         // IEEE is by far and away the most common CRC-32 polynomial.
  28         // Used by ethernet (IEEE 802.3), v.42, fddi, gzip, zip, png, ...
  29         IEEE = 0xedb88320
  30
  31         // Castagnoli's polynomial, used in iSCSI.
  32         // Has better error detection characteristics than IEEE.
  33         // https://dx.doi.org/10.1109/26.231911
  34         Castagnoli = 0x82f63b78
  35
  36         // Koopman's polynomial.
  37         // Also has better error detection characteristics than IEEE.
  38         // https://dx.doi.org/10.1109/DSN.2002.1028931
  39         Koopman = 0xeb31d82e
  40 )
  41
  42 // Table is a 256-word table representing the polynomial for efficient processing.
  43 type Table [256]uint32
  44
  45 // This file makes use of functions implemented in architecture-specific files.
  46 // The interface that they implement is as follows:
  47 //
  48 //    // archAvailableIEEE reports whether an architecture-specific CRC32-IEEE
  49 //    // algorithm is available.
  50 //    archAvailableIEEE() bool
  51 //
  52 //    // archInitIEEE initializes the architecture-specific CRC3-IEEE algorithm.
  53 //    // It can only be called if archAvailableIEEE() returns true.
  54 //    archInitIEEE()
  55 //
  56 //    // archUpdateIEEE updates the given CRC32-IEEE. It can only be called if
  57 //    // archInitIEEE() was previously called.
  58 //    archUpdateIEEE(crc uint32, p []byte) uint32
  59 //
  60 //    // archAvailableCastagnoli reports whether an architecture-specific
  61 //    // CRC32-C algorithm is available.
  62 //    archAvailableCastagnoli() bool
  63 //
  64 //    // archInitCastagnoli initializes the architecture-specific CRC32-C
  65 //    // algorithm. It can only be called if archAvailableCastagnoli() returns
  66 //    // true.
  67 //    archInitCastagnoli()
  68 //
  69 //    // archUpdateCastagnoli updates the given CRC32-C. It can only be called
  70 //    // if archInitCastagnoli() was previously called.
  71 //    archUpdateCastagnoli(crc uint32, p []byte) uint32
  72
  73 // castagnoliTable points to a lazily initialized Table for the Castagnoli
  74 // polynomial. MakeTable will always return this value when asked to make a
  75 // Castagnoli table so we can compare against it to find when the caller is
  76 // using this polynomial.
  77 var castagnoliTable *Table
  78 var castagnoliTable8 *slicing8Table
  79 var castagnoliArchImpl bool
  80 var updateCastagnoli func(crc uint32, p []byte) uint32
  81 var castagnoliOnce sync.Once
  82 var haveCastagnoli uint32
  83
  84 func castagnoliInit() {
  85         castagnoliTable = simpleMakeTable(Castagnoli)
  86         castagnoliArchImpl = archAvailableCastagnoli()
  87
  88         if castagnoliArchImpl {
  89                 archInitCastagnoli()
  90                 updateCastagnoli = archUpdateCastagnoli
  91         } else {
  92                 // Initialize the slicing-by-8 table.
  93                 castagnoliTable8 = slicingMakeTable(Castagnoli)
  94                 updateCastagnoli = func(crc uint32, p []byte) uint32 {
  95                         return slicingUpdate(crc, castagnoliTable8, p)
  96                 }
  97         }
  98
  99         atomic.StoreUint32(&haveCastagnoli, 1)
 100 }
 101
 102 // IEEETable is the table for the IEEE polynomial.
 103 var IEEETable = simpleMakeTable(IEEE)
 104
 105 // ieeeTable8 is the slicing8Table for IEEE
 106 var ieeeTable8 *slicing8Table
 107 var ieeeArchImpl bool
 108 var updateIEEE func(crc uint32, p []byte) uint32
 109 var ieeeOnce sync.Once
 110
 111 func ieeeInit() {
 112         ieeeArchImpl = archAvailableIEEE()
 113
 114         if ieeeArchImpl {
 115                 archInitIEEE()
 116                 updateIEEE = archUpdateIEEE
 117         } else {
 118                 // Initialize the slicing-by-8 table.
 119                 ieeeTable8 = slicingMakeTable(IEEE)
 120                 updateIEEE = func(crc uint32, p []byte) uint32 {
 121                         return slicingUpdate(crc, ieeeTable8, p)
 122                 }
 123         }
 124 }
 125
 126 // MakeTable returns a Table constructed from the specified polynomial.
 127 // The contents of this Table must not be modified.
 128 func MakeTable(poly uint32) *Table {
 129         switch poly {
 130         case IEEE:
 131                 ieeeOnce.Do(ieeeInit)
 132                 return IEEETable
 133         case Castagnoli:
 134                 castagnoliOnce.Do(castagnoliInit)
 135                 return castagnoliTable
 136         }
 137         return simpleMakeTable(poly)
 138 }
 139
 140 // digest represents the partial evaluation of a checksum.
 141 type digest struct {
 142         crc uint32
 143         tab *Table
 144 }
 145
 146 // New creates a new hash.Hash32 computing the CRC-32 checksum using the
 147 // polynomial represented by the Table. Its Sum method will lay the
 148 // value out in big-endian byte order. The returned Hash32 also
 149 // implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
 150 // marshal and unmarshal the internal state of the hash.
 151 func New(tab *Table) hash.Hash32 {
 152         if tab == IEEETable {
 153                 ieeeOnce.Do(ieeeInit)
 154         }
 155         return &digest{0, tab}
 156 }
 157
 158 // NewIEEE creates a new hash.Hash32 computing the CRC-32 checksum using
 159 // the IEEE polynomial. Its Sum method will lay the value out in
 160 // big-endian byte order. The returned Hash32 also implements
 161 // encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to marshal
 162 // and unmarshal the internal state of the hash.
 163 func NewIEEE() hash.Hash32 { return New(IEEETable) }
 164
 165 func (d *digest) Size() int { return Size }
 166
 167 func (d *digest) BlockSize() int { return 1 }
 168
 169 func (d *digest) Reset() { d.crc = 0 }
 170
 171 const (
 172         magic         = "crc\x01"
 173         marshaledSize = len(magic) + 4 + 4
 174 )
 175
 176 func (d *digest) MarshalBinary() ([]byte, error) {
 177         b := make([]byte, 0, marshaledSize)
 178         b = append(b, magic...)
 179         b = appendUint32(b, tableSum(d.tab))
 180         b = appendUint32(b, d.crc)
 181         return b, nil
 182 }
 183
 184 func (d *digest) UnmarshalBinary(b []byte) error {
 185         if len(b) < len(magic) || string(b[:len(magic)]) != magic {
 186                 return errors.New("hash/crc32: invalid hash state identifier")
 187         }
 188         if len(b) != marshaledSize {
 189                 return errors.New("hash/crc32: invalid hash state size")
 190         }
 191         if tableSum(d.tab) != readUint32(b[4:]) {
 192                 return errors.New("hash/crc32: tables do not match")
 193         }
 194         d.crc = readUint32(b[8:])
 195         return nil
 196 }
 197
 198 func appendUint32(b []byte, x uint32) []byte {
 199         a := [4]byte{
 200                 byte(x >> 24),
 201                 byte(x >> 16),
 202                 byte(x >> 8),
 203                 byte(x),
 204         }
 205         return append(b, a[:]...)
 206 }
 207
 208 func readUint32(b []byte) uint32 {
 209         _ = b[3]
 210         return uint32(b[3]) | uint32(b[2])<<8 | uint32(b[1])<<16 | uint32(b[0])<<24
 211 }
 212
 213 // Update returns the result of adding the bytes in p to the crc.
 214 func Update(crc uint32, tab *Table, p []byte) uint32 {
 215         switch {
 216         case atomic.LoadUint32(&haveCastagnoli) != 0 && tab == castagnoliTable:
 217                 return updateCastagnoli(crc, p)
 218         case tab == IEEETable:
 219                 // Unfortunately, because IEEETable is exported, IEEE may be used without a
 220                 // call to MakeTable. We have to make sure it gets initialized in that case.
 221                 ieeeOnce.Do(ieeeInit)
 222                 return updateIEEE(crc, p)
 223         default:
 224                 return simpleUpdate(crc, tab, p)
 225         }
 226 }
 227
 228 func (d *digest) Write(p []byte) (n int, err error) {
 229         switch {
 230         case atomic.LoadUint32(&haveCastagnoli) != 0 && d.tab == castagnoliTable:
 231                 d.crc = updateCastagnoli(d.crc, p)
 232         case d.tab == IEEETable:
 233                 // We only create digest objects through New() which takes care of
 234                 // initialization in this case.
 235                 d.crc = updateIEEE(d.crc, p)
 236         default:
 237                 d.crc = simpleUpdate(d.crc, d.tab, p)
 238         }
 239         return len(p), nil
 240 }
 241
 242 func (d *digest) Sum32() uint32 { return d.crc }
 243
 244 func (d *digest) Sum(in []byte) []byte {
 245         s := d.Sum32()
 246         return append(in, byte(s>>24), byte(s>>16), byte(s>>8), byte(s))
 247 }
 248
 249 // Checksum returns the CRC-32 checksum of data
 250 // using the polynomial represented by the Table.
 251 func Checksum(data []byte, tab *Table) uint32 { return Update(0, tab, data) }
 252
 253 // ChecksumIEEE returns the CRC-32 checksum of data
 254 // using the IEEE polynomial.
 255 func ChecksumIEEE(data []byte) uint32 {
 256         ieeeOnce.Do(ieeeInit)
 257         return updateIEEE(0, data)
 258 }
 259
 260 // tableSum returns the IEEE checksum of table t.
 261 func tableSum(t *Table) uint32 {
 262         var a [1024]byte
 263         b := a[:0]
 264         if t != nil {
 265                 for _, x := range t {
 266                         b = appendUint32(b, x)
 267                 }
 268         }
 269         return ChecksumIEEE(b)
 270 }