crypto/hmac

HMAC-SHA256, hmac.Equal, and why the key and message order matter, checked on Go 1.24.0.

模块页正文目前为英文。

The crypto/hmac package implements HMAC as defined in FIPS 198. Import it as "crypto/hmac". Official documentation states that an HMAC uses a key to sign a message, and that receivers should compare tags with Equal to avoid timing side channels. Examples were checked on Go 1.24.0.

The key used below, example-hmac-key-not-for-production, is a fixed public sample for these examples only. It is not a production credential. Do not paste real secrets into reference examples, and do not generate or store production keys here. hmac.New takes the key; Hash.Write takes the message. Swapping those two roles produces a different tag.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
hmac.New, hash.Hash.Write, hash.Hash.SumCompute an HMAC-SHA256 tag of a message under a key.
hmac.Equal, hmac.NewCompare HMAC tags in constant time, and show that swapping the key and the message changes the tag.

New, Write, and Sum

New(h, key) returns a hash.Hash that computes HMAC with the hash constructor h and the given key. crypto/sha256.New is a typical choice for h; h must return a new Hash every time it is called. Write appends message bytes, and Sum(nil) returns the tag. Official documentation notes that unlike many other hash.Hash values, the HMAC hash does not implement encoding.BinaryMarshaler.

hmac.New, hash.Hash.Write, hash.Hash.Sum

func New(h func() hash.Hash, key []byte) hash.Hash

Compute an HMAC-SHA256 tag of a message under a key.

ParameterDescription
hA function that returns a new hash.Hash, such as sha256.New.
keyThe HMAC key. The example uses the fixed public bytes example-hmac-key-not-for-production, which are not a production secret.

Returns: A hash.Hash. After Write of the message, Sum(nil) returns the MAC tag as a slice.

  • The printed digest is the HMAC-SHA256 of "hello" under that sample key, measured on Go 1.24.0.
go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func main() {
	key := []byte("example-hmac-key-not-for-production")
	msg := []byte("hello")
	mac := hmac.New(sha256.New, key)
	mac.Write(msg)
	fmt.Println(hex.EncodeToString(mac.Sum(nil)))
}

Expected output

d2a29298c27f3cf3b9aef19fe4ca1eae102be02c274a9dae5d2ded58c6697220

Related: crypto/sha256

Official documentation →

Equal and key versus message order

Equal compares two MAC tags without leaking timing information. Official documentation recommends it for verification. Equal only compares the two slices; it does not recompute a hash. Passing a short or unrelated slice returns false.

The first argument of New is the hash constructor, the second is the key, and Write consumes the message. If you pass the message as the key and write the key as the message, the tag is different, and Equal returns false. A different key with the same message also fails Equal.

hmac.Equal, hmac.New

func Equal(mac1, mac2 []byte) bool
func New(h func() hash.Hash, key []byte) hash.Hash

Compare HMAC tags in constant time, and show that swapping the key and the message changes the tag.

ParameterDescription
mac1 / mac2The two tags to compare. Equal is a slice comparison, not a hashing function.
key / messageNew(h, key) then Write(message) is the intended order. The sample key is not a production secret.

Returns: Equal returns whether the two slices are the same length and have the same bytes, without a timing leak described in the official documentation.

  • Do not compare tags with == on slices; that does not compile. bytes.Equal is not the API the HMAC package documents for this comparison.
go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"fmt"
)

func main() {
	key := []byte("example-hmac-key-not-for-production")
	msg := []byte("hello")
	mac := hmac.New(sha256.New, key)
	mac.Write(msg)
	tag := mac.Sum(nil)
	swapped := hmac.New(sha256.New, msg)
	swapped.Write(key)
	fmt.Println(hmac.Equal(tag, tag), hmac.Equal(tag, swapped.Sum(nil)), hmac.Equal(tag, []byte("short")))
}

Expected output

true false false

Official documentation →