go.step.sm/crypto v0.89.0: keyutil.Equal, keyutil.Fingerprint, keyutil.GenerateKey

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 pkg:golang/go.step.sm/crypto@v0.89.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.step.sm/crypto@v0.89.0
Demonstrate these symbols/APIs:
  - keyutil.Equal
  - keyutil.Fingerprint
  - keyutil.GenerateKey
  - keyutil.GenerateKeyPair
  - keyutil.PublicKey
  - keyutil.VerifyPair

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:98a3312ba5140ac2c99f0a53796d6b2f3ca4b2da40edff8793e52aeb087b71ea","contract":["keyutil.GenerateDefaultKeyPair generates an ECDSA P-256 keypair that passes keyutil.VerifyPair","keyutil.GenerateKeyPair generates RSA and Ed25519 asymmetric keypairs that pass keyutil.VerifyPair","keyutil.GenerateKeyPair creates an X25519 keypair and keyutil.PublicKey extracts the matching public key","keyutil.Equal returns true for identical public keys and false for non-matching public keys","keyutil.Fingerprint and keyutil.EncodedFingerprint return SHA-256 fingerprint strings for public keys","keyutil.GenerateKey returns an error for invalid key types, invalid curves, or RSA key sizes smaller than 2048 bits"],"goal":"verify pkg:golang/go.step.sm/crypto@v0.89.0","kind":"HOW","packages":["pkg:golang/go.step.sm/crypto@v0.89.0"],"schemaVersion":1,"symbols":["keyutil.Equal","keyutil.Fingerprint","keyutil.GenerateKey","keyutil.GenerateKeyPair","keyutil.PublicKey","keyutil.VerifyPair"]},"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/go.step.sm/crypto@v0.89.0"],"schemaVersion":1,"subject":"pkg:golang/go.step.sm/crypto@v0.89.0","symbols":["keyutil.Equal","keyutil.Fingerprint","keyutil.GenerateKey","keyutil.GenerateKeyPair","keyutil.PublicKey","keyutil.VerifyPair"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.26.6

require go.step.sm/crypto v0.89.0

require (
	filippo.io/edwards25519 v1.2.0 // indirect
	github.com/pkg/errors v0.9.1 // indirect
	golang.org/x/crypto v0.54.0 // indirect
	golang.org/x/sys v0.47.0 // indirect
)

filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
go.step.sm/crypto v0.89.0 h1:NPxryE+cZ4XDwXOQY2U6Gu+mOzOihuRLPIsX7WtPzZM=
go.step.sm/crypto v0.89.0/go.mod h1:IEgE6DndnYojbDyHU7eYXpwWzpu4ftkouw7nyI6jsxg=
golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package main

import (
	"crypto/ecdsa"
	"fmt"
	"os"

	"go.step.sm/crypto/keyutil"
)

func main() {
	pub, priv, err := keyutil.GenerateDefaultKeyPair()
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to generate key pair: %v\n", err)
		os.Exit(1)
	}

	if err := keyutil.VerifyPair(pub, priv); err != nil {
		fmt.Fprintf(os.Stderr, "key pair verification failed: %v\n", err)
		os.Exit(1)
	}

	fp, err := keyutil.Fingerprint(pub)
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to compute fingerprint: %v\n", err)
		os.Exit(1)
	}

	if _, ok := pub.(*ecdsa.PublicKey); !ok {
		fmt.Fprintf(os.Stderr, "unexpected public key type: %T\n", pub)
		os.Exit(1)
	}

	fmt.Printf("Generated key pair successfully with fingerprint: %s\n", fp)
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/go.step.sm/crypto@v0.89.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.step.sm/crypto@v0.89.0"
  ],
  "symbols": [
    "keyutil.Equal",
    "keyutil.Fingerprint",
    "keyutil.GenerateKey",
    "keyutil.GenerateKeyPair",
    "keyutil.PublicKey",
    "keyutil.VerifyPair"
  ]
}

package main

import (
	"crypto/ecdsa"
	"crypto/ed25519"
	"crypto/elliptic"
	"crypto/rsa"
	"fmt"
	"os"

	"go.step.sm/crypto/keyutil"
	"go.step.sm/crypto/x25519"
)

func main() {
	if err := runContract(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract verification failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All keyutil contract assertions passed.")
}

func runContract() error {
	// Assertion 1: keyutil.GenerateDefaultKeyPair generates an ECDSA P-256 keypair that passes keyutil.VerifyPair
	if err := testDefaultKeyPair(); err != nil {
		return fmt.Errorf("default keypair test failed: %w", err)
	}

	// Assertion 2: keyutil.GenerateKeyPair generates RSA and Ed25519 asymmetric keypairs that pass keyutil.VerifyPair
	if err := testRSAAndEd25519KeyPairs(); err != nil {
		return fmt.Errorf("RSA and Ed25519 keypairs test failed: %w", err)
	}

	// Assertion 3: keyutil.GenerateKeyPair creates an X25519 keypair and keyutil.PublicKey extracts the matching public key
	if err := testX25519KeyPair(); err != nil {
		return fmt.Errorf("X25519 keypair test failed: %w", err)
	}

	// Assertion 4: keyutil.Equal returns true for identical public keys and false for non-matching public keys
	if err := testKeyEquality(); err != nil {
		return fmt.Errorf("key equality test failed: %w", err)
	}

	// Assertion 5: keyutil.Fingerprint and keyutil.EncodedFingerprint return SHA-256 fingerprint strings for public keys
	if err := testKeyFingerprints(); err != nil {
		return fmt.Errorf("key fingerprints test failed: %w", err)
	}

	// Assertion 6: keyutil.GenerateKey returns an error for invalid key types, invalid curves, or RSA key sizes smaller than 2048 bits
	if err := testErrorHandling(); err != nil {
		return fmt.Errorf("error handling test failed: %w", err)
	}

	return nil
}

func testDefaultKeyPair() error {
	pub, priv, err := keyutil.GenerateDefaultKeyPair()
	if err != nil {
		return fmt.Errorf("keyutil.GenerateDefaultKeyPair failed: %w", err)
	}
	ecPub, ok := pub.(*ecdsa.PublicKey)
	if !ok || ecPub.Curve != elliptic.P256() {
		return fmt.Errorf("expected ECDSA P-256 public key, got %T", pub)
	}
	if err := keyutil.VerifyPair(pub, priv); err != nil {
		return fmt.Errorf("keyutil.VerifyPair failed on default key pair: %w", err)
	}
	return nil
}

func testRSAAndEd25519KeyPairs() error {
	// RSA 2048
	rsaPub, rsaPriv, err := keyutil.GenerateKeyPair("RSA", "", 2048)
	if err != nil {
		return fmt.Errorf("keyutil.GenerateKeyPair(RSA) failed: %w", err)
	}
	if _, ok := rsaPub.(*rsa.PublicKey); !ok {
		return fmt.Errorf("expected *rsa.PublicKey, got %T", rsaPub)
	}
	if err := keyutil.VerifyPair(rsaPub, rsaPriv); err != nil {
		return fmt.Errorf("keyutil.VerifyPair(RSA) failed: %w", err)
	}

	// Ed25519
	edPub, edPriv, err := keyutil.GenerateKeyPair("OKP", "Ed25519", 0)
	if err != nil {
		return fmt.Errorf("keyutil.GenerateKeyPair(OKP/Ed25519) failed: %w", err)
	}
	if _, ok := edPub.(ed25519.PublicKey); !ok {
		return fmt.Errorf("expected ed25519.PublicKey, got %T", edPub)
	}
	if err := keyutil.VerifyPair(edPub, edPriv); err != nil {
		return fmt.Errorf("keyutil.VerifyPair(OKP/Ed25519) failed: %w", err)
	}
	return nil
}

func testX25519KeyPair() error {
	xPub, xPriv, err := keyutil.GenerateKeyPair("OKP", "X25519", 0)
	if err != nil {
		return fmt.Errorf("keyutil.GenerateKeyPair(OKP/X25519) failed: %w", err)
	}
	if _, ok := xPub.(x25519.PublicKey); !ok {
		return fmt.Errorf("expected x25519.PublicKey, got %T", xPub)
	}
	extractedPub, err := keyutil.PublicKey(xPriv)
	if err != nil {
		return fmt.Errorf("keyutil.PublicKey failed on X25519 private key: %w", err)
	}
	if !keyutil.Equal(xPub, extractedPub) {
		return fmt.Errorf("extracted X25519 public key does not equal returned public key")
	}
	return nil
}

func testKeyEquality() error {
	pub1, _, err := keyutil.GenerateDefaultKeyPair()
	if err != nil {
		return fmt.Errorf("generating pub1 failed: %w", err)
	}
	pub2, _, err := keyutil.GenerateDefaultKeyPair()
	if err != nil {
		return fmt.Errorf("generating pub2 failed: %w", err)
	}

	if !keyutil.Equal(pub1, pub1) {
		return fmt.Errorf("keyutil.Equal should return true for the same key instance")
	}
	if keyutil.Equal(pub1, pub2) {
		return fmt.Errorf("keyutil.Equal should return false for distinct generated keys")
	}
	return nil
}

func testKeyFingerprints() error {
	pub, _, err := keyutil.GenerateDefaultKeyPair()
	if err != nil {
		return fmt.Errorf("generating default keypair for fingerprint failed: %w", err)
	}

	fp, err := keyutil.Fingerprint(pub)
	if err != nil {
		return fmt.Errorf("keyutil.Fingerprint failed: %w", err)
	}
	if len(fp) == 0 {
		return fmt.Errorf("keyutil.Fingerprint returned empty string")
	}

	hexFp, err := keyutil.EncodedFingerprint(pub, keyutil.HexFingerprint)
	if err != nil {
		return fmt.Errorf("keyutil.EncodedFingerprint(Hex) failed: %w", err)
	}
	if len(hexFp) == 0 {
		return fmt.Errorf("keyutil.EncodedFingerprint(Hex) returned empty string")
	}
	return nil
}

func testErrorHandling() error {
	if _, err := keyutil.GenerateKey("UNKNOWN_KTY", "", 0); err == nil {
		return fmt.Errorf("expected error for unknown key type, got nil")
	}

	if _, err := keyutil.GenerateKey("EC", "UNKNOWN_CURVE", 0); err == nil {
		return fmt.Errorf("expected error for invalid curve, got nil")
	}

	if _, err := keyutil.GenerateKey("RSA", "", 1024); err == nil {
		return fmt.Errorf("expected error for RSA key size below 2048 bits, got nil")
	}

	return nil
}