Package hkdf

import "crypto/hkdf"

Overview ▸

Overview ▾

Package hkdf implements the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as defined in RFC 5869.

HKDF is a cryptographic key derivation function (KDF) with the goal of expanding limited input keying material into one or more cryptographically strong secret keys.

▸ Example (Usage)

▾ Example (Usage)

Usage example that expands one master secret into three other cryptographically secure keys.

package main

import (
	"bytes"
	"crypto/hkdf"
	"crypto/rand"
	"crypto/sha256"
	"fmt"
)

func main() {
	// Underlying hash function for HMAC.
	hash := sha256.New
	keyLen := hash().Size()

	// Cryptographically secure master secret.
	secret := []byte{0x00, 0x01, 0x02, 0x03} // i.e. NOT this.

	// Non-secret salt, optional (can be nil).
	// Recommended: hash-length random value.
	salt := make([]byte, hash().Size())
	if _, err := rand.Read(salt); err != nil {
		panic(err)
	}

	// Non-secret context info, optional (can be nil).
	info := "hkdf example"

	// Generate three 128-bit derived keys.
	var keys [][]byte
	for i := 0; i < 3; i++ {
		key, err := hkdf.Key(hash, secret, salt, info, keyLen)
		if err != nil {
			panic(err)
		}
		keys = append(keys, key)
	}

	for i := range keys {
		fmt.Printf("Key #%d: %v\n", i+1, !bytes.Equal(keys[i], make([]byte, 16)))
	}

}

Key #1: true
Key #2: true
Key #3: true

Index ▸

Index ▾

func Expand[H hash.Hash](h func() H, pseudorandomKey []byte, info string, keyLength int) ([]byte, error)

func Extract[H hash.Hash](h func() H, secret, salt []byte) ([]byte, error)

func Key[Hash hash.Hash](h func() Hash, secret, salt []byte, info string, keyLength int) ([]byte, error)

Examples (Expand All)

Package (Usage)

Package files

hkdf.go

func Expand ¶

func Expand[H hash.Hash](h func() H, pseudorandomKey []byte, info string, keyLength int) ([]byte, error)

Expand derives a key from the given hash, key, and optional context info, returning a []byte of length keyLength that can be used as cryptographic key. The extraction step is skipped.

The key should have been generated by Extract, or be a uniformly random or pseudorandom cryptographically strong key. See RFC 5869, Section 3.3. Most common scenarios will want to use Key instead.

func Extract ¶

func Extract[H hash.Hash](h func() H, secret, salt []byte) ([]byte, error)

Extract generates a pseudorandom key for use with Expand from an input secret and an optional independent salt.

Only use this function if you need to reuse the extracted key with multiple Expand invocations and different context values. Most common scenarios, including the generation of multiple keys, should use Key instead.

func Key ¶

func Key[Hash hash.Hash](h func() Hash, secret, salt []byte, info string, keyLength int) ([]byte, error)

Key derives a key from the given hash, secret, salt and context info, returning a []byte of length keyLength that can be used as cryptographic key. Salt and info can be nil.