golang.org/x/crypto v0.54.0: hkdf.Expand, hkdf.Extract, hkdf.New

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify hkdf in pkg:golang/golang.org/x/crypto@v0.54.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/crypto@v0.54.0
Demonstrate these symbols/APIs:
  - golang.org/x/crypto/hkdf.Expand
  - golang.org/x/crypto/hkdf.Extract
  - golang.org/x/crypto/hkdf.New

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:c51b11cd9b68d919d0b10cbab222508794ea3d6c9f744c0788c95ce7accaa983","contract":["hkdf.Extract extracts pseudorandom key matching RFC 5869 test vector","hkdf.Extract with nil salt defaults to hash size zeros","hkdf.Expand expands pseudorandom key into key stream matching RFC 5869 test vector","hkdf.New combines Extract and Expand into a single key derivation reader","hkdf.New produces deterministic output for identical secret, salt, and info","hkdf.New produces distinct outputs when secret, salt, or info differs","hkdf.Expand returns error when reading beyond 255 times hash size"],"goal":"verify hkdf in pkg:golang/golang.org/x/crypto@v0.54.0","kind":"HOW","packages":["pkg:golang/golang.org/x/crypto@v0.54.0"],"schemaVersion":1,"symbols":["golang.org/x/crypto/hkdf.Expand","golang.org/x/crypto/hkdf.Extract","golang.org/x/crypto/hkdf.New"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/golang.org/x/crypto@v0.54.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/crypto@v0.54.0","symbols":["golang.org/x/crypto/hkdf.Expand","golang.org/x/crypto/hkdf.Extract","golang.org/x/crypto/hkdf.New"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require golang.org/x/crypto v0.54.0

golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=

package main

import (
	"crypto/rand"
	"crypto/sha256"
	"fmt"
	"io"
	"log"

	"golang.org/x/crypto/hkdf"
)

func main() {
	// Master secret material (e.g. from key exchange or high-entropy source)
	secret := make([]byte, 32)
	if _, err := io.ReadFull(rand.Reader, secret); err != nil {
		log.Fatalf("Failed to generate secret: %v", err)
	}

	// Optional salt and application-specific context info
	salt := make([]byte, 16)
	if _, err := io.ReadFull(rand.Reader, salt); err != nil {
		log.Fatalf("Failed to generate salt: %v", err)
	}
	info := []byte("example.com/sample/v1/aes-gcm-key")

	// 1. Extract stage: derive pseudorandom key (PRK) from secret and salt
	prk := hkdf.Extract(sha256.New, secret, salt)
	fmt.Printf("Extracted PRK length: %d bytes\n", len(prk))

	// 2. Expand stage: expand PRK into application key material
	expandReader := hkdf.Expand(sha256.New, prk, info)
	derivedKey1 := make([]byte, 32) // 256-bit AES key
	if _, err := io.ReadFull(expandReader, derivedKey1); err != nil {
		log.Fatalf("Failed to expand key: %v", err)
	}
	fmt.Printf("Derived AES key: %x\n", derivedKey1)

	// 3. Combined helper: hkdf.New performs Extract and Expand in one step
	hkdfReader := hkdf.New(sha256.New, secret, salt, info)
	derivedKey2 := make([]byte, 32)
	if _, err := io.ReadFull(hkdfReader, derivedKey2); err != nil {
		log.Fatalf("Failed to read from hkdf.New reader: %v", err)
	}
	fmt.Printf("Derived key from hkdf.New: %x\n", derivedKey2)
}

{
  "schemaVersion": 1,
  "goal": "verify hkdf in pkg:golang/golang.org/x/crypto@v0.54.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/crypto@v0.54.0"
  ],
  "symbols": [
    "golang.org/x/crypto/hkdf.Expand",
    "golang.org/x/crypto/hkdf.Extract",
    "golang.org/x/crypto/hkdf.New"
  ]
}

package main

import (
	"bytes"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"os"

	"golang.org/x/crypto/hkdf"
)

func main() {
	// RFC 5869 Test Case 1 (SHA-256)
	ikm1 := bytes.Repeat([]byte{0x0b}, 22)
	salt1, _ := hex.DecodeString("000102030405060708090a0b0c")
	info1, _ := hex.DecodeString("f0f1f2f3f4f5f6f7f8f9")
	expectedPRK1, _ := hex.DecodeString("077709362c2e32df0ddc3f0dc47bba6390b6c73bb50f9c3122ec844ad7c2b3e5")
	expectedOKM1, _ := hex.DecodeString("3cb25f25faacd57a90434f64d0362f2a2d2d0a90cf1a5a4c5db02d56ecc4c5bf34007208d5b887185865")

	// 1. hkdf.Extract extracts pseudorandom key matching RFC 5869 test vector
	prk1 := hkdf.Extract(sha256.New, ikm1, salt1)
	if !bytes.Equal(prk1, expectedPRK1) {
		fmt.Fprintf(os.Stderr, "hkdf.Extract PRK mismatch: got %x, want %x\n", prk1, expectedPRK1)
		os.Exit(1)
	}

	// 2. hkdf.Extract with nil salt defaults to hash size zeros
	zeroSalt := make([]byte, sha256.Size)
	prkNilSalt := hkdf.Extract(sha256.New, ikm1, nil)
	prkZeroSalt := hkdf.Extract(sha256.New, ikm1, zeroSalt)
	if !bytes.Equal(prkNilSalt, prkZeroSalt) {
		fmt.Fprintf(os.Stderr, "hkdf.Extract with nil salt did not match zero salt\n")
		os.Exit(1)
	}
	expectedPRK3, _ := hex.DecodeString("19ef24a32c717b167f33a91d6f648bdf96596776afdb6377ac434c1c293ccb04")
	if !bytes.Equal(prkNilSalt, expectedPRK3) {
		fmt.Fprintf(os.Stderr, "hkdf.Extract RFC 5869 Case 3 PRK mismatch: got %x, want %x\n", prkNilSalt, expectedPRK3)
		os.Exit(1)
	}

	// 3. hkdf.Expand expands pseudorandom key into key stream matching RFC 5869 test vector
	expandReader := hkdf.Expand(sha256.New, prk1, info1)
	okm1 := make([]byte, len(expectedOKM1))
	if _, err := io.ReadFull(expandReader, okm1); err != nil {
		fmt.Fprintf(os.Stderr, "hkdf.Expand read failed: %v\n", err)
		os.Exit(1)
	}
	if !bytes.Equal(okm1, expectedOKM1) {
		fmt.Fprintf(os.Stderr, "hkdf.Expand OKM mismatch: got %x, want %x\n", okm1, expectedOKM1)
		os.Exit(1)
	}

	// 4. hkdf.New combines Extract and Expand into a single key derivation reader
	newReader := hkdf.New(sha256.New, ikm1, salt1, info1)
	okmFromNew := make([]byte, len(expectedOKM1))
	if _, err := io.ReadFull(newReader, okmFromNew); err != nil {
		fmt.Fprintf(os.Stderr, "hkdf.New read failed: %v\n", err)
		os.Exit(1)
	}
	if !bytes.Equal(okmFromNew, expectedOKM1) {
		fmt.Fprintf(os.Stderr, "hkdf.New output mismatch with expected OKM: got %x, want %x\n", okmFromNew, expectedOKM1)
		os.Exit(1)
	}

	// 5. hkdf.New produces deterministic output for identical secret, salt, and info
	readerA := hkdf.New(sha256.New, ikm1, salt1, info1)
	readerB := hkdf.New(sha256.New, ikm1, salt1, info1)
	bufA := make([]byte, 64)
	bufB := make([]byte, 64)
	if _, err := io.ReadFull(readerA, bufA); err != nil {
		fmt.Fprintf(os.Stderr, "readerA read failed: %v\n", err)
		os.Exit(1)
	}
	if _, err := io.ReadFull(readerB, bufB); err != nil {
		fmt.Fprintf(os.Stderr, "readerB read failed: %v\n", err)
		os.Exit(1)
	}
	if !bytes.Equal(bufA, bufB) {
		fmt.Fprintf(os.Stderr, "hkdf.New deterministic check failed\n")
		os.Exit(1)
	}

	// 6. hkdf.New produces distinct outputs when secret, salt, or info differs
	diffSecretReader := hkdf.New(sha256.New, []byte("different secret"), salt1, info1)
	diffSaltReader := hkdf.New(sha256.New, ikm1, []byte("different salt"), info1)
	diffInfoReader := hkdf.New(sha256.New, ikm1, salt1, []byte("different info"))

	bufDiffSecret := make([]byte, 64)
	bufDiffSalt := make([]byte, 64)
	bufDiffInfo := make([]byte, 64)

	io.ReadFull(diffSecretReader, bufDiffSecret)
	io.ReadFull(diffSaltReader, bufDiffSalt)
	io.ReadFull(diffInfoReader, bufDiffInfo)

	if bytes.Equal(bufA, bufDiffSecret) || bytes.Equal(bufA, bufDiffSalt) || bytes.Equal(bufA, bufDiffInfo) {
		fmt.Fprintf(os.Stderr, "hkdf.New failed to produce distinct output for varied parameters\n")
		os.Exit(1)
	}

	// 7. hkdf.Expand returns error when reading beyond 255 times hash size
	maxBytes := 255 * sha256.Size // 8160 bytes for SHA-256
	limitReader := hkdf.Expand(sha256.New, prk1, info1)
	maxBuf := make([]byte, maxBytes)
	if _, err := io.ReadFull(limitReader, maxBuf); err != nil {
		fmt.Fprintf(os.Stderr, "Failed to read max allowed HKDF bytes (%d): %v\n", maxBytes, err)
		os.Exit(1)
	}
	extraByte := make([]byte, 1)
	if _, err := limitReader.Read(extraByte); err == nil {
		fmt.Fprintf(os.Stderr, "hkdf.Expand unexpectedly allowed reading beyond 255 * hash.Size\n")
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed.")
}