crypto, hash: document marshal/unmarshal implementation

Unless you go back and read the hash package documentation, it's
not clear that all the hash packages implement marshaling and
unmarshaling. Document the behaviour specifically in each package
that implements it as it this is hidden behaviour and easy to miss.

Change-Id: Id9d3508909362f1a3e53872d0319298359e50a94
Reviewed-on: https://go-review.googlesource.com/77251
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Joe Tsai <thebrokentoaster@gmail.com>

diff --git a/src/crypto/hmac/hmac.go b/src/crypto/hmac/hmac.go
index 9ef9c448ee20b1d8fac437e385748e1c8e4b9568..3c8e727bc8c3d48122d71eeb8008f09bcd6b8b7a 100644 (file)
--- a/src/crypto/hmac/hmac.go
+++ b/src/crypto/hmac/hmac.go
@@ -64,6 +64,9 @@ func (h *hmac) Reset() {
 }
 
 // New returns a new HMAC hash using the given hash.Hash type and key.
+// Note that unlike other hash implementations in the standard library,
+// the returned Hash does not implement encoding.BinaryMarshaler
+// or encoding.BinaryUnmarshaler.
 func New(h func() hash.Hash, key []byte) hash.Hash {
        hm := new(hmac)
        hm.outer = h()

diff --git a/src/crypto/md5/md5.go b/src/crypto/md5/md5.go
index c4820dab660a83b5ee3078a8535df68bcd859473..3a29af1f15b2b06700eaf6cb68ab433752af4a5d 100644 (file)
--- a/src/crypto/md5/md5.go
+++ b/src/crypto/md5/md5.go
@@ -123,7 +123,9 @@ func consumeUint32(b []byte) ([]byte, uint32) {
        return b[4:], x
 }
 
-// New returns a new hash.Hash computing the MD5 checksum.
+// New returns a new hash.Hash computing the MD5 checksum. The Hash also
+// implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
+// marshal and unmarshal the internal state of the hash.
 func New() hash.Hash {
        d := new(digest)
        d.Reset()

diff --git a/src/crypto/sha1/sha1.go b/src/crypto/sha1/sha1.go
index 2586b59ddf18fecf3456c7f6415bf80597ac8680..5f32434f0f94d46ba4dadf728df6d3300b165078 100644 (file)
--- a/src/crypto/sha1/sha1.go
+++ b/src/crypto/sha1/sha1.go
@@ -113,7 +113,9 @@ func (d *digest) Reset() {
        d.len = 0
 }
 
-// New returns a new hash.Hash computing the SHA1 checksum.
+// New returns a new hash.Hash computing the SHA1 checksum. The Hash also
+// implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
+// marshal and unmarshal the internal state of the hash.
 func New() hash.Hash {
        d := new(digest)
        d.Reset()

diff --git a/src/crypto/sha256/sha256.go b/src/crypto/sha256/sha256.go
index 568477c3fddb9deb53950ac130d08564d6667fdd..f078cab3783bcc6fcf9c918c746a6f57b5a6c79f 100644 (file)
--- a/src/crypto/sha256/sha256.go
+++ b/src/crypto/sha256/sha256.go
@@ -164,7 +164,10 @@ func (d *digest) Reset() {
        d.len = 0
 }
 
-// New returns a new hash.Hash computing the SHA256 checksum.
+// New returns a new hash.Hash computing the SHA256 checksum. The Hash
+// also implements encoding.BinaryMarshaler and
+// encoding.BinaryUnmarshaler to marshal and unmarshal the internal
+// state of the hash.
 func New() hash.Hash {
        d := new(digest)
        d.Reset()

diff --git a/src/crypto/sha512/sha512.go b/src/crypto/sha512/sha512.go
index 9b60facb0ad9111c052454527fed4fa9282d0233..2ea27c5535b225aac8e5af9f5b619bef2216c275 100644 (file)
--- a/src/crypto/sha512/sha512.go
+++ b/src/crypto/sha512/sha512.go
@@ -4,6 +4,10 @@
 
 // Package sha512 implements the SHA-384, SHA-512, SHA-512/224, and SHA-512/256
 // hash algorithms as defined in FIPS 180-4.
+//
+// All the hash.Hash implementations returned by this package also
+// implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
+// marshal and unmarshal the internal state of the hash.
 package sha512
 
 import (

diff --git a/src/hash/adler32/adler32.go b/src/hash/adler32/adler32.go
index 149a6b889ea124ed2b5d1c15804694272c73893a..e8783e4c39eda5da394bf01d111c27e6cdc2c90f 100644 (file)
--- a/src/hash/adler32/adler32.go
+++ b/src/hash/adler32/adler32.go
@@ -35,8 +35,11 @@ type digest uint32
 
 func (d *digest) Reset() { *d = 1 }
 
-// New returns a new hash.Hash32 computing the Adler-32 checksum.
-// Its Sum method will lay the value out in big-endian byte order.
+// New returns a new hash.Hash32 computing the Adler-32 checksum. Its
+// Sum method will lay the value out in big-endian byte order. The
+// returned Hash32 also implements encoding.BinaryMarshaler and
+// encoding.BinaryUnmarshaler to marshal and unmarshal the internal
+// state of the hash.
 func New() hash.Hash32 {
        d := new(digest)
        d.Reset()

diff --git a/src/hash/crc32/crc32.go b/src/hash/crc32/crc32.go
index db05f124c4ae37fc5abacee13f128bdb17e33237..1912caa212ba1d9ad86d835c871a67f1549ec9d9 100644 (file)
--- a/src/hash/crc32/crc32.go
+++ b/src/hash/crc32/crc32.go
@@ -139,9 +139,11 @@ type digest struct {
        tab *Table
 }
 
-// New creates a new hash.Hash32 computing the CRC-32 checksum
-// using the polynomial represented by the Table.
-// Its Sum method will lay the value out in big-endian byte order.
+// New creates a new hash.Hash32 computing the CRC-32 checksum using the
+// polynomial represented by the Table. Its Sum method will lay the
+// value out in big-endian byte order. The returned Hash32 also
+// implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
+// marshal and unmarshal the internal state of the hash.
 func New(tab *Table) hash.Hash32 {
        if tab == IEEETable {
                ieeeOnce.Do(ieeeInit)
@@ -149,9 +151,11 @@ func New(tab *Table) hash.Hash32 {
        return &digest{0, tab}
 }
 
-// NewIEEE creates a new hash.Hash32 computing the CRC-32 checksum
-// using the IEEE polynomial.
-// Its Sum method will lay the value out in big-endian byte order.
+// NewIEEE creates a new hash.Hash32 computing the CRC-32 checksum using
+// the IEEE polynomial. Its Sum method will lay the value out in
+// big-endian byte order. The returned Hash32 also implements
+// encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to marshal
+// and unmarshal the internal state of the hash.
 func NewIEEE() hash.Hash32 { return New(IEEETable) }
 
 func (d *digest) Size() int { return Size }

diff --git a/src/hash/crc64/crc64.go b/src/hash/crc64/crc64.go
index 54c942c97aedcd0261d220cebfd9e218d477f0ce..3b24c2440628aac249818fd2e1aaab7c9d6b1a56 100644 (file)
--- a/src/hash/crc64/crc64.go
+++ b/src/hash/crc64/crc64.go
@@ -80,9 +80,11 @@ type digest struct {
        tab *Table
 }
 
-// New creates a new hash.Hash64 computing the CRC-64 checksum
-// using the polynomial represented by the Table.
-// Its Sum method will lay the value out in big-endian byte order.
+// New creates a new hash.Hash64 computing the CRC-64 checksum using the
+// polynomial represented by the Table. Its Sum method will lay the
+// value out in big-endian byte order. The returned Hash64 also
+// implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
+// marshal and unmarshal the internal state of the hash.
 func New(tab *Table) hash.Hash64 { return &digest{0, tab} }
 
 func (d *digest) Size() int { return Size }

diff --git a/src/hash/fnv/fnv.go b/src/hash/fnv/fnv.go
index 99c892000b12f9622180a98890facda2018ab7ee..7662315d43cf8fc4dee0f6600f0f2b17e110f98c 100644 (file)
--- a/src/hash/fnv/fnv.go
+++ b/src/hash/fnv/fnv.go
@@ -6,6 +6,10 @@
 // created by Glenn Fowler, Landon Curt Noll, and Phong Vo.
 // See
 // https://en.wikipedia.org/wiki/Fowler-Noll-Vo_hash_function.
+//
+// All the hash.Hash implementations returned by this package also
+// implement encoding.BinaryMarshaler and encoding.BinaryUnmarshaler to
+// marshal and unmarshal the internal state of the hash.
 package fnv
 
 import (