Source: hmac.go in package crypto/hmac

Package hmac implements the Keyed-Hash Message Authentication Code (HMAC) asdefined in U.S. Federal Information Processing Standards Publication 198.An HMAC is a cryptographic hash that uses a key to sign a message.The receiver verifies the hash by recomputing it using the same key.

Receivers should be careful to use Equal to compare MACs in order to avoidtiming side-channels:

ValidMAC reports whether messageMAC is a valid HMAC tag for message. func ValidMAC(message, messageMAC, key []byte) bool { mac := hmac.New(sha256.New, key) mac.Write(message) expectedMAC := mac.Sum(nil) return hmac.Equal(messageMAC, expectedMAC) }

package hmac

import (
	"crypto/subtle"
	"hash"
)

FIPS 198-1: https://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf

key is zero padded to the block size of the hash function ipad = 0x36 byte repeated for key length opad = 0x5c byte repeated for key length hmac = H([key ^ opad] H([key ^ ipad] text))

Marshalable is the combination of encoding.BinaryMarshaler and encoding.BinaryUnmarshaler. Their method definitions are repeated here to avoid a dependency on the encoding package.

type marshalable interface {
	MarshalBinary() ([]byte, error)
	UnmarshalBinary([]byte) error
}

type hmac struct {
	opad, ipad   []byte
	outer, inner hash.Hash

If marshaled is true, then opad and ipad do not contain a padded copy of the key, but rather the marshaled state of outer/inner after opad/ipad has been fed into it.

	marshaled bool
}

func (h *hmac) Sum(in []byte) []byte {
	origLen := len(in)
	in = h.inner.Sum(in)

	if h.marshaled {
		if err := h.outer.(marshalable).UnmarshalBinary(h.opad); err != nil {
			panic(err)
		}
	} else {
		h.outer.Reset()
		h.outer.Write(h.opad)
	}
	h.outer.Write(in[origLen:])
	return h.outer.Sum(in[:origLen])
}

func (h *hmac) Write(p []byte) (n int, err error) {
	return h.inner.Write(p)
}

func (h *hmac) Size() int      { return h.outer.Size() }
func (h *hmac) BlockSize() int { return h.inner.BlockSize() }

func (h *hmac) Reset() {
	if h.marshaled {
		if err := h.inner.(marshalable).UnmarshalBinary(h.ipad); err != nil {
			panic(err)
		}
		return
	}

	h.inner.Reset()
	h.inner.Write(h.ipad)

If the underlying hash is marshalable, we can save some time by saving a copy of the hash state now, and restoring it on future calls to Reset and Sum instead of writing ipad/opad every time. If either hash is unmarshalable for whatever reason, it's safe to bail out here.

	marshalableInner, innerOK := h.inner.(marshalable)
	if !innerOK {
		return
	}
	marshalableOuter, outerOK := h.outer.(marshalable)
	if !outerOK {
		return
	}

	imarshal, err := marshalableInner.MarshalBinary()
	if err != nil {
		return
	}

	h.outer.Reset()
	h.outer.Write(h.opad)
	omarshal, err := marshalableOuter.MarshalBinary()
	if err != nil {
		return
	}

Marshaling succeeded; save the marshaled state for later

	h.ipad = imarshal
	h.opad = omarshal
	h.marshaled = true
}

New returns a new HMAC hash using the given hash.Hash type and key. New functions like sha256.New from crypto/sha256 can be used as h. h must return a new Hash every time it is called. 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()
	hm.inner = h()
	unique := true
	func() {

The comparison might panic if the underlying types are not comparable.

			_ = recover()
		}()
		if hm.outer == hm.inner {
			unique = false
		}
	}()
	if !unique {
		panic("crypto/hmac: hash generation function does not produce unique values")
	}
	blocksize := hm.inner.BlockSize()
	hm.ipad = make([]byte, blocksize)
	hm.opad = make([]byte, blocksize)

If key is too big, hash it.

		hm.outer.Write(key)
		key = hm.outer.Sum(nil)
	}
	copy(hm.ipad, key)
	copy(hm.opad, key)
	for i := range hm.ipad {
		hm.ipad[i] ^= 0x36
	}
	for i := range hm.opad {
		hm.opad[i] ^= 0x5c
	}
	hm.inner.Write(hm.ipad)

	return hm
}

Equal compares two MACs for equality without leaking timing information.

We don't have to be constant time if the lengths of the MACs are different as that suggests that a completely different hash function was used.

	return subtle.ConstantTimeCompare(mac1, mac2) == 1