crc32.go

Documentation: hash/crc32

		 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  }
	 271
View as plain text